Agent team
A lead agent coordinating several long-running agent sessions that share a task list and message each other directly.
An agent team is a lead agent plus several teammate agents, each a full, long-running session with its own context. The lead splits the work into tasks on a shared task list; teammates claim tasks, work in parallel and message each other directly. It is one shape of a multi-agent system, closer to a small team of people than to a batch job.
Claude Code offers this as agent teams, marked experimental and off by default. Tasks there are pending, in progress or completed, can depend on other tasks, and claiming uses file locking so two teammates don’t take the same task. The docs warn that a team uses significantly more tokens than a single session, because each teammate is a separate Claude instance, and that two teammates editing the same file overwrite each other. They suggest starting with three to five teammates, and with research or review before writing code.
Compare it with subagents: a subagent does one job and reports back once, and the main agent manages all the work. Teammates keep running, talk to each other and can challenge each other’s findings, which helps when debugging with competing hypotheses. A dynamic workflow moves the plan into a script and scales to hundreds of agents, but the script decides what runs next, not a lead agent. Pick a team when the parts need discussion, and subagents when only the result matters.
Sources
- Claude Code Docs: Orchestrate teams of Claude Code sessions code.claude.com
Related terms
- Multi-agent system (multi-agent orchestration): Several AI agents with separate roles and contexts working on one task, usually coordinated by a lead agent or a fixed workflow.
- Subagent: A separate agent run with its own fresh context, started by a main agent for one subtask.
- Dynamic workflow: An orchestration script the agent writes at run time. A runtime executes it, starting many subagents in phases and combining their results in code.
- Orchestrator-workers pattern (supervisor): One model plans the task, hands parts of it to worker models or subagents, and combines their results.
- Coding agent: An agent that reads a repository, edits files, runs commands and tests, and opens pull requests.
- Tokens: The pieces of text models read and write, and the unit you pay for.
- Agent handoff: One agent passes control of a conversation, together with its context, to a specialist agent or to a person.
