Advanced: Build an Agent Team With a Lead and a Critic on the Claude Agent SDK

What You Will Get

A standard operating procedure (SOP) for building an Agent team: one orchestrator splits up tasks and aggregates results, several specialists each handle one thing, a reviewer sends substandard work back for revision, and three caps apply: budget, depth, and time. It uses the Claude Agent SDK (Python). Each step states "what to do" and "what done looks like," so you can follow it by hand or hand it directly to Claude Code to build.

The bottom line first: a team is usually the wrong tool. A well-written single Agent is faster and cheaper. Step 0 below helps you decide whether you need one.

Step 0: Decide Whether You Need a Team

Split work into a team only if at least one of the following holds; otherwise, use a single Agent:

Condition	Example
The task can be split into several parts that don't depend on each other and can run at the same time	Researching three competitors at once
A subtask reads a large amount of material but only needs one conclusion at the end	Reading fifty pages of documentation and needing only a three-line summary
A part needs different specialized instructions or different permissions	A reviewer that can only read, not edit

Done when: you can state in one sentence "I'm splitting this into a team in order to ___." If you can't, stay with a single Agent.

There Are Only Three Roles in a Team

Orchestrator: takes the goal, splits up tasks, dispatches them to specialists, and assembles the results. It doesn't do the detailed work itself, and it is the only one you talk to.
Specialist: each does one narrow thing, such as only verifying facts or only writing from materials. The narrower, the better.
Reviewer: only checks against standards, and if something fails, lists the problems and sends it back. This role is most often skipped, and it's the one you should least skip.

Step 1: Install the SDK

Requirements: Python 3.10+ and an API key, which you create in the Claude Console.

pip install claude-agent-sdk
export ANTHROPIC_API_KEY="your key"

The SDK does not read .env files automatically; the key must be set in the environment where the program runs. Shipping this inside a product for other people? Use API key auth, never a claude.ai login.

Done when: python -c "import claude_agent_sdk" runs without errors.

Step 2: Get One Orchestrator Running First

Don't design the whole team up front. First, have a single Agent complete the entire job on its own, and note three things: where it spends the most tokens, which parts are actually independent of each other, and where quality is least stable.

Parts that are independent of each other → later split into parallel specialists;
The part with unstable quality → later handed to the reviewer.

Done when: the single Agent completes the task, and you have written down the three observations above.

Step 3: Define Specialists, Writing the Description as "When to Call Me"

Specialists are defined with AgentDefinition. prompt is their job description; description determines when the orchestrator dispatches work to them. If it's vague, the orchestrator will either not use them or use them wrongly.

Done when: each specialist's description answers "in what situation should it be called?"

Step 4: Give Each Role the Fewest Tools Possible

Any tool not listed in tools is completely unavailable to that specialist. This is the cleanest safety switch:

Role	Tools
Researcher	Search and web page reading only
Writer	Read and write files
Reviewer	Read only, no write, otherwise it will quietly edit things itself instead of reporting problems
Orchestrator	Needs `Agent`: that tool is how specialists get launched

Done when: no role has write permission it doesn't need.

Step 5: Spell Everything Out at Handoff

A specialist starts from a blank context: it cannot see the orchestrator's conversation, tool results, or system prompt, and can only see the message the orchestrator wrote when dispatching the work. A one-line brief such as "draft the report" leaves the writer guessing. So the orchestrator's instructions must require that each dispatch message state the goal, all needed materials or file paths, decisions already made, and the output format.

Done when: you can read any single dispatch message on its own and start work without any surrounding context.

Step 6: Complete Team Code

Below is a "research + writing" team: three parallel research threads, a writer that uses only verified material, a read-only reviewer, at most three rounds of revision, all enclosed by budget, turn, and time caps.

New accounts get 10 free credits, plus 1 more for each daily check-in. Spend 1 credit to unlock and it stays open for you.

Done when: after running, you can see the final draft in report.md, the terminal prints the cost, and if you deliberately set the budget very low, you confirm it ends with error_max_budget_usd.

Step 7: Three Caps, None Can Be Skipped

Cap	How to set it	Default
Spending	`max_budget_usd`	Unlimited, you must set it yourself
Depth	Environment variable `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`	3 levels, recommended 1
Concurrency	Environment variable `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`	20
Time	Your own timeout (e.g., `asyncio.wait_for`)	None

Also set effort per role: the legwork researcher uses low, the writer and reviewer use medium, and the orchestrator starts at medium and is raised only if truly needed.

Done when: every item in the table has an explicit value.

When Handing Off to an Agent for Execution

Give this article's link to Claude Code, and state:

Build an Agent team for me following this SOP, with the task being [your task]. Start from Step 0, and after each step, check yourself against the "done when" criteria. If Step 0 concludes that no team is needed, stop and tell me. Do not skip the cap settings in Step 7; first set the spending cap to [amount] USD.

Notes

Get one working Agent before adding a second. Five mediocre Agents chained together are worse than one good orchestrator.
Leave irreversible actions to humans: the team can draft emails, but sending, publishing, paying, and deleting must be confirmed by you.
A team can't fix a process you haven't thought through: if you can't explain step by step how this job should be done, splitting it across five Agents won't make it any clearer.