Subagents and agent teams
Specialized workers that perform bounded tasks in separate contexts and return results to a coordinating agent or shared team.
Use it when
- Research, logs, tests, or repository exploration would flood the main context.
- Independent workstreams can run in parallel with clear ownership.
- A specialist needs a narrower prompt, model, or tool permission set.
Choose another layer when
- A quick change that depends on the full conversation and frequent user feedback.
- Parallel edits to the same files without isolation and merge ownership.
Production path
Build it in this order
- 01
Delegate a bounded outcome
Give each worker a concrete task, relevant context, allowed tools, constraints, and the expected return format.
Quality check: The worker can complete without asking the coordinator to reconstruct the task.
- 02
Partition state and writes
Prefer read-heavy parallel work. For edits, assign non-overlapping files or isolated worktrees and name the integration owner.
Quality check: Two workers cannot silently overwrite the same state.
- 03
Verify the synthesis
Treat worker summaries as inputs, not proof. The coordinator checks citations, tests, and conflicts before acting.
Quality check: The final result preserves evidence and resolves disagreements explicitly.
Artifacts you may see
- .codex/agents/*.toml
- .claude/agents/*.md
- agent manifests
- worktree task plans
Connected layers
Evidence ledger
Primary documentation behind this guide
Provider-specific behavior is sourced to that provider. Open standards are sourced to their specifications and official maintainers.
Codex subagents
OpenAI
Delegation patterns, custom agents, permissions, and token tradeoffs in Codex.
Create custom subagents
Anthropic
Claude Code subagent contexts, invocation, permissions, background work, and common patterns.
Run agents in parallel
Anthropic
The distinction among subagents, teams, background sessions, and worktree isolation.