Team

A team is an agent 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.

1 · Delegation

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.

2 · The board

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.

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.
It then calls send_to_agent once per card, with a brief that names the card.
The member does the work in its own session and moves its own card to done before it answers.
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.
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.

Why delegate at all

Delegation is fundamentally about context isolation and cost, not wall-clock speed.

Isolate context

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.

Bound cost

Because context is isolated, downstream calls carry fewer tokens. The coordinator’s budget bounds the whole team, and each delegated call is still quoted before it runs.

Compose specialists

Reference existing agents by id and version. A specialist’s persona, tools, and skills are reused wholesale rather than re-prompted.

Fan out

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.

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

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,
  },
});

{
  "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

Delegation

send_to_agent, wait_for_agents and list_agents — their real arguments, the isolated threads, typed results, and how a refusal comes back.

Team board

board_read and board_write, the four fixed statuses, the card and comment shapes, and the routes a person reads them through.

Coordinator

The multiagent object and the roster entry types, and which of them are served today.

Rosters & versioning

How the roster is snapshotted, why pins never drift, mixing harnesses, and the vetta team commands.

Context & budgets

What is shared across threads versus per-member, what an idle member costs, and the cross-thread event view.

Next: delegation

The first of the two mechanisms, in full.

Agent

Running an agent

Agent capabilities

Computer

Identity

Team

Two ways a team coordinates

1 · Delegation

2 · The board

How each one behaves

When to reach for which

They compose, and this is the proven pattern

The coordinator model

Why delegate at all

Isolate context

Bound cost

Compose specialists

Fan out

A minimal team

Explore the reference

Delegation

Team board

Coordinator

Rosters & versioning

Context & budgets

Next: delegation

​Two ways a team coordinates

1 · Delegation

2 · The board

​How each one behaves

​When to reach for which

​They compose, and this is the proven pattern

​The coordinator model

​Why delegate at all

Isolate context

Bound cost

Compose specialists

Fan out

​A minimal team

​Explore the reference

Delegation

Team board

Coordinator

Rosters & versioning

Context & budgets

Next: delegation

Two ways a team coordinates

How each one behaves

When to reach for which

They compose, and this is the proven pattern

The coordinator model

Why delegate at all

A minimal team

Explore the reference