Handoffs

Let one agent transfer a conversation to a specialist agent.

Handoffs let one agent transfer a conversation to another, more specialized agent — without losing any context along the way.

This is useful for building systems where a single triage agent routes a conversation to the right specialist, similar to how a support team routes tickets between departments.

Example#

Pass a list of agents to the handoffs parameter, and the triage agent decides which one to transfer to.

triage.py

from abzagent import Agent

billing_agent = Agent(
    name="Billing Agent",
    instructions="Help customers with billing, invoices, and refunds.",
    model="gemini-2.5-flash",
)

technical_agent = Agent(
    name="Technical Agent",
    instructions="Help customers troubleshoot technical problems.",
    model="gemini-2.5-flash",
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="Understand what the customer needs and hand off to the right specialist.",
    model="gemini-2.5-flash",
    handoffs=[billing_agent, technical_agent],
)

result = triage_agent.run("I was charged twice for my subscription this month.")

print(result.content)

Example Output

Output

I've transferred you to our Billing Agent, who can help resolve the duplicate
charge on your subscription. Could you share the date of the two charges?

How It Works#

For every agent listed in handoffs, the SDK automatically creates a transfer tool — you don't need to write one yourself.
The triage agent calls this tool the same way it would call any other tool, whenever it decides the conversation belongs with a specialist.
The full conversation history is passed along to the new agent, so the customer never has to repeat themselves.
The specialist agent then takes over and generates the response that's returned to the caller.

Accessing the Final Agent#

Because a handoff can change which agent actually answers, result.last_agent tells you which one produced the final response — useful for logging, analytics, or displaying "You're now speaking with…" in a UI.

Python

result = triage_agent.run("I was charged twice for my subscription this month.")

print(result.last_agent.name)
print(result.content)

Example Output

Output

Billing Agent
I've transferred you to our Billing Agent, who can help resolve the duplicate
charge on your subscription. Could you share the date of the two charges?

Advanced Handoffs#

For more control over a handoff, wrap the agent with the handoff() helper instead of passing it directly. This lets you override the name of the generated transfer tool or run a callback the moment the handoff occurs.

Python

from abzagent import Agent, handoff

def on_billing_handoff():
    print("Handed off to Billing Agent")

triage_agent = Agent(
    name="Triage Agent",
    instructions="Understand what the customer needs and hand off to the right specialist.",
    model="gemini-2.5-flash",
    handoffs=[
        handoff(billing_agent, tool_name_override="escalate_billing_issue", on_handoff=on_billing_handoff),
        technical_agent,
    ],
)

Mix and match

Plain agents and handoff()-wrapped agents can be combined in the same handoffs list — use the helper only where you need the extra control.

Next Step#

Continue to Agent as a Tool.