Multi-agent orchestration

Already implementing explicit handoffs? Skip to the next lesson.

Here is the thing nobody says early enough:

A handoff is a tool call.

def handoff_to_specialist(reason: str) -> str:
    return specialist.run(reason).text

That is it. The first agent asks for a tool. Your code runs it. The tool happens to be another agent. Your loop from Module 2 already supports this and always did. There is no separate multi-agent engine.

When a second agent earns its place

Two agents are worth it when the roles genuinely differ:

• different instructions, and
• different tools or different permissions

Triage can read policy. The specialist can reset a VPN token. That is a real boundary, and it is a security boundary too, which is the stronger argument. The junior agent cannot reset anything because it was never given the ability.

When it does not

Every handoff is a wall that context has to cross, and detail is lost each time. The specialist gets a summary, not the conversation.

Most multi-agent designs are one agent that needed better tools, paying extra delay and tokens for the privilege of forgetting things. Two agents is a design. Five is usually a diagram somebody fell in love with.

What to write

1. Build the chat client as in Module 14
2. Create specialist with its own instructions and its own tool
3. Write handoff_to_specialist(reason) calling specialist.run(...)
4. Create triage with the handoff function in its tools, and run it

Watch the trace. The handoff appears as tool_requested, and inside it you will see the specialist's own model calls. Two agents, one stream of events.

The point

Most multi-agent designs should have been one agent with better tools.

Break it on purpose

Give triage the specialist's tools as well. It answers without ever handing off, which tells you the second agent was never needed.