Multi-Agent Systems

When one agent isn't enough, coordinate multiple specialists.

Two Patterns

Manager Pattern

One agent delegates to specialists.

manager = Agent(
    name="Manager",
    instructions="Route requests to the right specialist.",
    tools=[
        sales_agent.as_tool(description="Handle sales inquiries"),
        support_agent.as_tool(description="Handle support issues"),
        billing_agent.as_tool(description="Handle billing questions"),
    ],
)

# User talks to manager, manager delegates
result = await Runner.run(manager, "I want to upgrade my plan")

The manager stays in control. It receives results from specialists and synthesizes the response.

Decentralized Pattern

Agents hand off to each other directly.

triage = Agent(
    name="Triage",
    instructions="Identify what the customer needs and hand off.",
    handoffs=[sales_agent, support_agent, billing_agent],
)

# Triage identifies need, hands off completely
result = await Runner.run(triage, "My order hasn't arrived")
# → Hands off to support_agent

Once handed off, the new agent takes full control.

Choosing a Pattern

Use Manager When	Use Decentralized When
Need unified response	Specialists work independently
Want central control	Clean separation of concerns
Combining multiple results	One specialist handles entire task

Example: Customer Service

# Specialists
tech_support = Agent(
    name="Tech Support",
    instructions="Resolve technical issues.",
    tools=[search_kb, run_diagnostic],
)

billing = Agent(
    name="Billing",
    instructions="Handle payment and subscription issues.",
    tools=[lookup_invoice, process_refund],
)

orders = Agent(
    name="Orders",
    instructions="Track and manage orders.",
    tools=[track_shipment, modify_order],
)

# Triage routes incoming requests
triage = Agent(
    name="Triage",
    instructions="Identify customer need and route to specialist.",
    handoffs=[tech_support, billing, orders],
)