Some jobs are better split across specialised agents than crammed into one. Build a two-agent system — a researcher and a writer — and have an orchestrator hand work between them.
Why: a single agent with ten tools and a sprawling prompt gets confused; smaller agents with focused tools and instructions each do one job well. When: split when sub-tasks need different tools, skills, or personas. Where: an orchestrator routes work and combines the results.
┌──────────────┐
│ Orchestrator │ decides who does what
└──────┬───────┘
┌──────┴───────┐
▼ ▼
┌───────────┐ ┌───────────┐
│ Researcher│ │ Writer │
│ (search) │ │ (compose) │
└───────────┘ └───────────┘Why: each agent is just a focused call with its own system prompt and tools — the researcher gathers facts, the writer turns them into prose. When: give each only the tools it needs, so neither is distracted by the other's job.
def researcher(topic):
return run_agent_with_system(
f"Research this topic and return the key facts as bullet points: {topic}",
tools=[search_tool],
system="You are a researcher. Gather facts with search_docs. Do not write prose.",
)
def writer(facts):
return text_of(client.messages.create(
model="claude-opus-4-8", max_tokens=1024,
system="You are a writer. Turn the given facts into a tight 5-sentence summary.",
messages=[{"role": "user", "content": facts}],
))Why: the orchestrator is the conductor — it calls each agent in turn and passes one's output as the next one's input. When: this sequential handoff suits pipelines; for independent sub-tasks, call agents in parallel and merge their results. Where: keep the orchestrator thin — its only job is routing.
def run_pipeline(topic):
facts = researcher(topic) # agent 1 gathers
article = writer(facts) # agent 2 composes from agent 1's output
return article
print(run_pipeline("our company refund policy"))
# Sequential here. For independent sub-tasks (e.g. research 3 topics
# at once), run the agents concurrently and combine their outputs.