> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Team
> Multiagent orchestration on Vetta: a coordinator agent and a version-pinned roster, coordinating two ways — point-to-point delegation and a durable shared board.
A **team** is an [agent](/docs/concepts/agents) whose configuration carries a `multiagent` object. That agent is the **coordinator**: it owns the top-level task and the top-level context, and it works with a **roster** of member agents. Each member runs in its own session thread with only the context it was handed.
There is no separate "team" object to create. A team is just an agent with a roster — so everything you already know about agents (versioning, budgets, sessions, events) applies unchanged.
## Two ways a team coordinates
This is the thing to understand before anything else on these pages. Vetta gives a team **two** coordination mechanisms, and they are not variations of one idea — they have different shapes, different lifetimes, and different audiences.
**Point-to-point, task-shaped, one-shot.** The coordinator calls `send_to_agent` with a brief. The member runs in its **own** session, and its answer folds back into the coordinator's transcript as a tool result. Private between those two threads, and gone when the run is.
**Broadcast, durable, many-to-many.** Any thread calls `board_read` / `board_write`. Cards are rows in the database that outlive every session that touched them, and every member reads and writes the same surface.
```
DELEGATION — point to point, ephemeral THE BOARD — broadcast, durable
──────────────────────────────────────── ─────────────────────────────────────
coordinator coordinator ──┐
│ send_to_agent(member, brief) │
▼ member A ─────┼──▶ ┌──────────────┐
member's OWN session ──▶ its own turns │ │ todo doing │
│ member B ─────┘ │ blocked done │
▼ result folds back as a tool result └──────────────┘
coordinator resumes cards outlive the sessions
```
### How each one behaves
| | Delegation | The board |
| ------------------- | -------------------------------------------------------------- | --------------------------------------------------- |
| Shape | One coordinator → one member | Any thread ↔ every thread |
| Carries | A brief, and a result | Cards: title, notes, status, assignee, `blocked_by` |
| Who can see it | Only the two threads involved | The whole team, and you, and the dashboard |
| Lifetime | The delegated thread; ephemeral | Durable — one board per agent, in Postgres |
| Coordinator's state | Parks on `awaiting_delegation` until the member finishes | Nothing parks; a board write returns immediately |
| Who starts it | Only the coordinator — a member is never given `send_to_agent` | Any thread on the team, coordinator or member |
### When to reach for which
* **Delegate** when the work is *bounded and you want the answer back*. "Summarize this contract." "Check these numbers." The coordinator cannot continue without the result, so parking on it is exactly right.
* **Use the board** when the work is *state, not a question*. What the team is collectively trying to do, who holds what, what is stuck and on which other card, and what a member should pick up next time it runs. A card is also how a member hands work over: no member can see another member's conversation, so what you did and what is left has to be written down somewhere both can read.
* **Use both** when the run is long enough that "what is still outstanding" is a real question. That is most long-horizon work.
### They compose, and this is the proven pattern
The pattern that runs in production is: **the coordinator puts the plan on the board, then delegates each card.**
1. The coordinator writes one card per unit of work — `board_write` with `op: "create"`, an `assignee`, and enough in the notes that the member can act with no other context.
2. It then calls `send_to_agent` once per card, with a brief that names the card.
3. The member does the work in its own session and moves its own card to `done` before it answers.
4. The coordinator parks on `wait_for_agents`, wakes with the results, and reads the board to see what is left.
The board survives step 4. If the coordinator's session ends — budget, window, a person cancelling it — the cards are still there, still saying who held what and what was finished, and the next session picks up from them rather than from a transcript nobody kept.
**Both are shipped and both are proven in production.** A delegation run drove a coordinator → a `pi` member → back to the coordinator → a `vetta` member → `end_turn`, with each member in its own session. A board run created two cards, assigned them to a member, and both reached `done`.
## The coordinator model
```
┌─────────────────────────────┐
│ Coordinator │ owns the task + full context
│ multiagent.type = coordinator
└──────────────┬──────────────┘
delegates bounded briefs
┌──────────────┼──────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ member │ │ member │ │ self │ each in its OWN isolated,
│ (agent) │ │ (agent) │ │ (copy) │ persistent thread
└─────────┘ └─────────┘ └─────────┘
```
* Every member runs in its **own session thread** with its **own conversation history**. Nothing about one member's transcript leaks into another's.
* Delegation is capped to **one level**: a member is never handed `send_to_agent` at all, so it cannot delegate and cannot be talked into it.
* A team may **mix harnesses below the coordinator**. A member's harness decides what its session holds and costs — see [Rosters & versioning](/docs/team/rosters-and-versioning#mixing-harnesses).
* **Any published harness can be the coordinator's.** Both coordination mechanisms are tools Vetta contributes to the turn; `claude_code` and `hermes` run their own CLI's toolset inside a box and reach ours over a session-scoped tool endpoint. The one caveat there is that `wait_for_agents` does not pause the turn — the coordinator parks once the turn goes idle and still opens its threads. See [Harness capabilities](/docs/concepts/harness-capabilities#two-limits-on-the-second-road).
## Why delegate at all
Delegation is fundamentally about **context isolation and cost**, not wall-clock speed.
A member starts fresh with only its brief. The coordinator's long transcript never rides along on every downstream call, so each member stays focused and cheap.
Because context is isolated, downstream calls carry fewer tokens. The coordinator's [budget](/docs/concepts/budgets) bounds the whole team, and each delegated call is still quoted before it runs.
Reference existing agents by id and version. A specialist's persona, tools, and skills are reused wholesale rather than re-prompted.
The coordinator can have several members running at once, each in its own thread — useful for map-style work over a batch.
Fan-out is real parallelism, but the *reason* to delegate is context and cost. If a single agent can hold the whole task in its context comfortably and cheaply, you do not need a team.
## A minimal team
The roster lives on the coordinator's config, so a team is made in two steps: create an ordinary agent, then give it a roster.
```bash CLI theme={"system"}
vetta agent create --name research-lead --model zai-org/GLM-5.2-FP8 --harness pi --budget-usd 100 --max-task-usd 10 --budget-period month
vetta team set research-lead --member web-researcher@3 --member fact-checker@1 --board
```
```typescript TypeScript theme={"system"}
const lead = await vetta.agents.create({
name: "research-lead",
model: "zai-org/GLM-5.2-FP8",
harness: "pi",
budget: { capUsd: 100, maxTaskUsd: 10, period: "month" },
});
await vetta.agents.update(lead.id, {
expected_version: lead.current_version,
multiagent: {
type: "coordinator",
agents: [
{ type: "agent", id: "agt_9f2c…", version: 3 },
{ type: "agent", id: "agt_4a71…", version: 1 },
],
board: true,
},
});
```
```json Agent config theme={"system"}
{
"name": "research-lead",
"model": "zai-org/GLM-5.2-FP8",
"harness": "pi",
"budget": { "cap_usd": 100, "max_task_usd": 10, "period": "month" },
"multiagent": {
"type": "coordinator",
"agents": [
{ "type": "agent", "id": "agt_9f2c…", "version": 3 },
{ "type": "agent", "id": "agt_4a71…", "version": 1 }
],
"board": true
}
}
```
On the wire a roster member is always an `agt_` id — the CLI resolves the friendly `name@version` spelling for you before it writes. Each member is **pinned by version**, so the team's behavior is reproducible even as members evolve independently. `board: true` is what makes the two board tools exist; without it the team has delegation only.
## Explore the reference
`send_to_agent`, `wait_for_agents` and `list_agents` — their real arguments, the isolated threads, typed results, and how a refusal comes back.
`board_read` and `board_write`, the four fixed statuses, the card and comment shapes, and the routes a person reads them through.
The `multiagent` object and the roster entry types, and which of them are served today.
How the roster is snapshotted, why pins never drift, mixing harnesses, and the `vetta team` commands.
What is shared across threads versus per-member, what an idle member costs, and the cross-thread event view.
The first of the two mechanisms, in full.