Designing a Multi-Agent System for Real-World Use

When one agent stops being enough

The first agent you build will do one thing well. The second will do two things badly. That is the moment to split responsibilities instead of adding instructions to one prompt.

The supervisor pattern

A planner receives the user goal and decides which specialist should act. Each specialist, such as a research agent or an analysis agent, owns a narrow toolset: data access, external APIs or a human feedback channel. The supervisor merges results and decides whether the goal is met.

1supervisor = Agent(
2    name="Supervisor",
3    instructions="Coordinate the workflow between agents.",
4    sub_agents=[research_agent, analysis_agent],
5)

Contracts between agents

In production the pattern depends on the contract between agents more than on the prompt: typed inputs, typed outputs and a trace identifier that follows the request through every hop.

Trade-offs

• Latency grows with every hand-off. Run specialists in parallel where the plan allows it.
• Cost multiplies. Use a smaller model for routing and a larger one only where judgment matters.
• Debugging needs a timeline view, because logs alone are not enough. Emit spans per agent step.

Where to put humans

Any step that writes to a system of record, spends money or sends a message to a customer should pause for approval until you have months of evidence that it does not need to.