Session 8· 09· 20 min
Multi-Agent Handoff
What you'll learn
- ▸Build two agents that hand off to each other mid-conversation
- ▸Use Command to update state and switch active agent
- ▸Implement state-driven routing with @wrap_model_call
What you will build
A sales + support agent pair. When the user asks a technical question during a sales conversation, the sales agent hands off to support — and vice versa. The handoff is implemented as a tool that updates a state variable.
09_handoff.py (handoff tool)
@tool
def transfer_to_support(
runtime: ToolRuntime[None, HandoffState] ①
) -> Command:
"""Transfer the conversation to the support agent."""
return Command(update={ ②
"messages": [
ToolMessage(
content="Transferred to support agent.",
tool_call_id=runtime.tool_call_id,
)
],
"current_agent": "support", ③
})①ToolRuntime gives the tool access to state and the current tool_call_id.
②Command updates state with new messages and the current_agent field.
③Setting current_agent triggers the middleware to switch prompt + tools on the next model call.
$ python 09_handoff.py
When to use handoffs vs subagents
Handoffs = conversational flows where agents talk directly to the user. Subagents = a supervisor dispatching background work. Session 7 lesson 05 has the full decision framework.
Knowledge Check
How does the handoff mechanism work under the hood?
Recap — what you just learned
- ✓Handoff tools use Command to update a state variable (e.g. current_agent)
- ✓Middleware reads the state variable and switches prompt + tools
- ✓Single agent graph, multiple personalities — state-driven routing
- ✓Each agent talks directly to the user