All agents have ahandoffs param, which can either take anAgent directly, or aHandoff object that customizes the Handoff.

You can create a handoff using thehandoff() function provided by the Agents SDK. This function allows you to specify the agent to hand off to, along with optional overrides and input filters.

Basic Usage

Here's how you can create a simple handoff:

fromagentsimportAgent,handoffbilling_agent=Agent(name="Billing agent")refund_agent=Agent(name="Refund agent")# (1)!triage_agent=Agent(name="Triage agent",handoffs=[billing_agent,handoff(refund_agent)])

1. You can use the agent directly (as inbilling_agent), or you can use thehandoff() function.

Customizing handoffs via thehandoff() function

Thehandoff() function lets you customize things.

• agent: This is the agent to which things will be handed off.
• tool_name_override: By default, theHandoff.default_tool_name() function is used, which resolves totransfer_to_<agent_name>. You can override this.
• tool_description_override: Override the default tool description fromHandoff.default_tool_description()
• on_handoff: A callback function executed when the handoff is invoked. This is useful for things like kicking off some data fetching as soon as you know a handoff is being invoked. This function receives the agent context, and can optionally also receive LLM generated input. The input data is controlled by theinput_type param.
• input_type: The type of input expected by the handoff (optional).
• input_filter: This lets you filter the input received by the next agent. See below for more.
• is_enabled: Whether the handoff is enabled. This can be a boolean or a function that returns a boolean, allowing you to dynamically enable or disable the handoff at runtime.

fromagentsimportAgent,handoff,RunContextWrapperdefon_handoff(ctx:RunContextWrapper[None]):print("Handoff called")agent=Agent(name="My agent")handoff_obj=handoff(agent=agent,on_handoff=on_handoff,tool_name_override="custom_handoff_tool",tool_description_override="Custom description",)

Handoff inputs

In certain situations, you want the LLM to provide some data when it calls a handoff. For example, imagine a handoff to an "Escalation agent". You might want a reason to be provided, so you can log it.

frompydanticimportBaseModelfromagentsimportAgent,handoff,RunContextWrapperclassEscalationData(BaseModel):reason:strasyncdefon_handoff(ctx:RunContextWrapper[None],input_data:EscalationData):print(f"Escalation agent called with reason:{input_data.reason}")agent=Agent(name="Escalation agent")handoff_obj=handoff(agent=agent,on_handoff=on_handoff,input_type=EscalationData,)

Input filters

When a handoff occurs, it's as though the new agent takes over the conversation, and gets to see the entire previous conversation history. If you want to change this, you can set aninput_filter. An input filter is a function that receives the existing input via aHandoffInputData, and must return a newHandoffInputData.

By default the runner now collapses the prior transcript into a single assistant summary message (seeRunConfig.nest_handoff_history). The summary appears inside a<CONVERSATION HISTORY> block that keeps appending new turns when multiple handoffs happen during the same run. You can provide your own mapping function viaRunConfig.handoff_history_mapper to replace the generated message without writing a fullinput_filter. That default only applies when neither the handoff nor the run supplies an explicitinput_filter, so existing code that already customizes the payload (including the examples in this repository) keeps its current behavior without changes. You can override the nesting behaviour for a single handoff by passingnest_handoff_history=True orFalse tohandoff(...), which setsHandoff.nest_handoff_history. If you just need to change the wrapper text for the generated summary, callset_conversation_history_wrappers (and optionallyreset_conversation_history_wrappers) before running your agents.

There are some common patterns (for example removing all tool calls from the history), which are implemented for you inagents.extensions.handoff_filters

fromagentsimportAgent,handofffromagents.extensionsimporthandoff_filtersagent=Agent(name="FAQ agent")handoff_obj=handoff(agent=agent,input_filter=handoff_filters.remove_all_tools,# (1)!)

1. This will automatically remove all tools from the history whenFAQ agent is called.

Recommended prompts

To make sure that LLMs understand handoffs properly, we recommend including information about handoffs in your agents. We have a suggested prefix inagents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX, or you can callagents.extensions.handoff_prompt.prompt_with_handoff_instructions to automatically add recommended data to your prompts.

fromagentsimportAgentfromagents.extensions.handoff_promptimportRECOMMENDED_PROMPT_PREFIXbilling_agent=Agent(name="Billing agent",instructions=f"""{RECOMMENDED_PROMPT_PREFIX}    <Fill in the rest of your prompt here>.""",)