Multi-Agent Systems
Orchestrator and worker patterns, agent communication, and when it makes sense to split work across agents.
Multi-agent systems split work across specialized agents. The most common shape in production is orchestrator-worker: an orchestrator dispatches independent subtasks to specialist agents, waits for all of them, then synthesizes the results into one final output.
This is the real orchestrator-worker code from `agentic/code-review-agent` in the companion repo. Three specialist agents review the same PR diff in parallel, each with a narrow system prompt, then an orchestrator agent merges their findings into one review.
async def run_specialist(role: str, focus: str, diff: str) -> str:
system = f"You are a {role} code reviewer. Focus only on {focus}. Be concise."
response = await client.chat.completions.create(
model=MODEL,
messages=[
{"role": "system", "content": system},
{"role": "user", "content": f"Review this diff:\n\n{diff[:6000]}"},
],
)
return response.choices[0].message.content
async def review_pr(owner: str, repo: str, pr_number: int):
diff = await get_pr_diff(owner, repo, pr_number)
# Three specialists run concurrently, not sequentially
security, performance, style = await asyncio.gather(
run_specialist("security", "SQL injection, secrets, unsafe inputs, auth issues", diff),
run_specialist("performance", "N+1 queries, memory leaks, inefficient loops", diff),
run_specialist("style", "naming conventions, function length, duplication", diff),
)
# Orchestrator synthesizes all three into one final review
final_review = await run_orchestrator(security, performance, style)
return final_review`asyncio.gather` is doing the real work here: all three specialists call the model at the same time, so the wall-clock cost is one round trip, not three. Coordination is the hard part in systems like this: you need a clear contract for what each specialist returns, a synthesis step that can handle disagreement between them, and (as this project does) a human-approval gate before anything gets posted back to GitHub.
A single agent is one strong generalist. A multi-agent setup is a team with a manager, specialists, and QA. You get better depth, but only if communication is disciplined.