Teams

Any agent with subagents leads a team. The lead and every subagent it starts share one task list and one mailbox, so work can be split up, claimed, and reported on without the lead relaying every detail. There is nothing extra to configure: the team tools come with subagents.

The team tools

A member is identified by its agent name. A message arrives as reference material just before the recipient's next model call, prefixed with the sender's name, and is delivered once.

Example

The lead creates a task and starts a writer. The writer claims the task, finishes it and tells the lead.

const writer = agent({
  name: "writer",
  instructions: "Claim an open task, do it, then mark it completed.",
  model: scriptedModel({
    responses: [
      use("team_task_claim", { task_id: "lead/t1" }, "w1"),
      use("team_task_update", { task_id: "lead/t1", status: "completed" }, "w2"),
      use("send_message", { to: "lead", text: "Draft is ready." }, "w3"),
      say("Done."),
    ],
  }),
});

const lead = agent({
  name: "lead",
  instructions: "Plan the work as team tasks, then start your team.",
  model: scriptedModel({
    responses: [
      use("team_task_create", { subject: "Write the release notes" }, "t1"),
      use("spawn_agent", { agent: "writer", prompt: "Pick up the open task." }, "s1"),
      say("The release notes are drafted."),
    ],
  }),
  subagents: [writer],
});

The scripted model plays the calls a real model would make. With a real model, the task id (lead/t1 here) comes back as the result of team_task_create.

How it behaves

• The lead's thread holds the team. Tasks, claims and messages are recorded in the lead's log, so you can see who did what in the lead's timeline.
• Claims are atomic. Two members racing for one task: one wins, the other gets an error it can act on.
• Blockers are respected. A task with blocked_by can't be claimed until every blocker is completed.
• Safe to retry. If a member's process restarts and repeats a call, it gets the same answer. Nothing is claimed or sent twice.
• Run members in parallel by starting them with background: true. The lead's run returns once all of them have finished.

Related