---
name: distri
description: >-
  Use when building, running, or deploying Distri agents, writing agent.md
  files, using the distri CLI (run, serve, agents/skills/workflows push),
  reading traces, managing secrets/connections, or embedding agents in a product
  with @distri/react. Triggers on "distri", "distri run", "distri agents push",
  "create a distri agent", "agent.md", "distri traces", "embed an agent".
---

# Distri

Distri is a runtime for **in-product agents**. You define an agent once in a
markdown file, connect your own functions as tools, and run it from the CLI, as
a streaming API server, or embedded in a product. This skill covers building,
running, and deploying agents with the `distri` CLI, plus the SDK.

- Docs: https://distri.dev/docs
- Full LLM reference (curl-able): https://distri.dev/llms-full.txt
- CLI reference: https://distri.dev/docs/reference/cli-reference

Deeper references live next to this file in `references/`, read them when a task
needs the detail:

- `references/agents.md`, the full `agent.md` format (frontmatter, tools, model).
- `references/cli.md`, every CLI command and flag.
- `references/traces.md`, reading and debugging runs with traces.
- `references/workflows-and-skills.md`, reusable skills, prompts, and multi-step workflows.
- `references/embedding.md`, embedding in React and calling the SDK (`agent.invoke`, `client.llm`, `resubscribe`).

## Install the CLI

```bash
curl -fsSL https://distri.dev/install.sh | sh
distri --version
```

Running agents locally needs **no account**, just a model provider key:

```bash
export OPENAI_API_KEY="sk-..."   # or the key for your chosen model provider
```

## Write an agent

An agent is a markdown file with a TOML frontmatter block. Put agents in an
`agents/` directory (e.g. `agents/search_agent.md`):

```markdown
---
name = "search_agent"
description = "Answers questions by searching the web"
max_iterations = 3

[tools]
builtin = ["final"]

[tools.packages]
search = ["search"]

[model_settings]
model = "gpt-4.1-mini"
temperature = 0.3
---

# ROLE
You are a research assistant. Use the search tool to find current
information, then answer concisely and cite what you found.

# TASK
{{task}}
```

Key frontmatter fields (see `references/agents.md` for all):

- `name`, `description`, `version`, `max_iterations`
- `[tools]`, `builtin` (e.g. `final`, `transfer_to_agent`), `external` (tools your
  app provides at runtime; use `["*"]` for all), `packages` (e.g. `search`), and
  `[[tools.mcp]]` blocks for MCP servers
- `[model_settings]`, `model`, `temperature`, `max_tokens`
- The body is the system prompt. `{{task}}` interpolates the run's task.

The leap from chatbot to **in-product** agent is `external` tools, your product's
own functions, handed to the agent at runtime (`external = ["*"]`).

## Run it

```bash
# Single task
distri run --task "Who is the prime minister of Singapore?" --agent search_agent

# Interactive TUI (pick/switch agents, resume threads)
distri
distri tui search_agent
distri tui search_agent --resume last

# Run in a remote browsr sandbox
distri run --task "..." --agent search_agent --remote
```

## Serve it as an API

```bash
distri serve                        # local server on :7777, opens the web UI
distri serve --port 9000            # custom port
distri serve --headless             # don't open the web UI (CI / containers)
```

Exposes agents over an A2A-compatible JSON-RPC API with SSE streaming.

## Deploy to Distri Cloud

Authenticate, then push. `distri push` is the primary deploy, it **syncs the
whole `agents/`, `skills/`, `templates/` tree** to your workspace. Run it after
editing any agent, skill, or template.

```bash
distri login                        # authenticate (creates a profile)

distri push                         # sync agents/ skills/ templates/ from cwd
distri push --dry-run               # preview what would upload
distri checkout                     # pull the workspace back into the local layout
```

Per-resource commands when you want finer control:

```bash
distri agents list
distri agents push agents/search_agent.md   # one agent
distri agents push agents/ --all            # every agent in the dir
distri agents delete old_agent -y

distri skills push skills/my-skill --all
distri prompts push templates/system.hbs    # prompt templates are .hbs files
```

> Workflows are **not** a CLI resource, they run via the runtime and the
> `@distri/core` `WorkflowRunner` (see `references/workflows-and-skills.md`).

## Read traces (debug a run)

Every run is an OpenTelemetry trace, tool calls, tokens, latency, reasoning.

```bash
distri traces list                  # recent runs
distri traces list --limit 50
distri traces show <trace-id>       # Gantt view of the run
distri traces show <trace-id> --span "llm"   # just the LLM spans
distri traces show <trace-id> -v    # full span data
```

See `references/traces.md` for how to read them.

## Secrets & connections

```bash
distri secrets set OPENAI_API_KEY "sk-..."
distri secrets list
distri connections list
distri connections token <connection-id>
```

## Embed in a product

Install `@distri/core` + `@distri/react` and drop in a `<Chat>`, or call the SDK
directly. Full detail in `references/embedding.md`:

```tsx
import { DistriProvider, Chat, useAgent } from '@distri/react';

function Assistant() {
  const { agent } = useAgent({ agentIdOrDef: 'search_agent' });
  return <Chat agent={agent} externalTools={tools} theme="dark" />;
}
```

```ts
import { DistriClient } from '@distri/core';
const client = new DistriClient({ baseUrl: 'http://localhost:7777' });
const agent = await client.getAgent('search_agent');
const reply = await agent.invoke({ message: 'Reconcile Q3 and flag any gaps.' });
const res = await client.llm([{ role: 'user', parts: [{ type: 'text', text: '…' }] }]);
```

## Command cheat sheet

| Task | Command |
|------|---------|
| Install CLI | `curl -fsSL https://distri.dev/install.sh \| sh` |
| Run a task | `distri run --task "…" --agent NAME` |
| Interactive TUI | `distri` / `distri tui NAME` |
| Serve API | `distri serve` (listens on :7777) |
| Authenticate | `distri login` |
| Deploy (sync all) | `distri push` · `distri push --dry-run` · `distri checkout` |
| List / push / delete agents | `distri agents list` · `distri agents push agents/ --all` · `distri agents delete NAME -y` |
| List / push skills | `distri skills list` · `distri skills push skills/my-skill --all` |
| Skill registries | `distri search "pdf"` · `distri install NAME@REGISTRY` |
| Traces | `distri traces list` · `distri traces show ID` |
| Tools | `distri tools list` · `distri tools invoke NAME --input '{…}'` |
| Secrets | `distri secrets set KEY VALUE` · `distri secrets list` |

## Rules of thumb

- Local dev needs no account; only pushing to cloud requires `distri login`.
- Edit an `agent.md`/skill/template → `distri push` to sync everything (or the
  per-resource `distri agents/skills/prompts push`).
- `--all` is required to push a whole directory; `-y` skips delete confirmations; `-v` adds debug output.
- `--remote` on `distri run` executes in a remote browsr sandbox.
- Keep secrets in `distri secrets`, never in agent files.
- `distri serve` listens on **:7777** by default, match your SDK `baseUrl` to it.