Implementation:Openai Openai agents python Handoff Helper

Knowledge Sources	OpenAI Agents Python Agents SDK Docs
Domains	AI_Agents, Multi_Agent, Orchestration, Handoffs
Last Updated	2026-02-11 15:00 GMT

Overview

The handoff() helper function creates configured Handoff objects that enable agent-to-agent delegation in the OpenAI Agents Python SDK. It wraps a target agent with optional customization for tool naming, descriptions, callbacks, input types, and conversation history filtering.

Import

from agents import handoff

Full Signature

def handoff(
    agent: Agent[TContext],
    tool_name_override: str | None = None,
    tool_description_override: str | None = None,
    on_handoff: OnHandoffWithInput[THandoffInput] | OnHandoffWithoutInput | None = None,
    input_type: type[THandoffInput] | None = None,
    input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None,
    nest_handoff_history: bool | None = None,
    is_enabled: bool | Callable[[RunContextWrapper[Any], Agent[TContext]], MaybeAwaitable[bool]] = True,
) -> Handoff[TContext, Agent[TContext]]:

Parameters

Parameter	Type	Default	Description
agent	Agent[TContext]	required	The target agent to hand off to. This agent will become the active agent when the handoff is invoked.
tool_name_override	None	None	Custom tool name for the handoff. If not provided, defaults to transfer_to_{agent.name}.
tool_description_override	None	None	Custom tool description. If not provided, uses the agent's handoff_description or a default description.
on_handoff	OnHandoffWithoutInput | None	None	Callback function executed when the handoff occurs. Can optionally accept a typed input parameter.
input_type	None	None	The type of the input the LLM must provide when invoking the handoff. Used with on_handoff callbacks that accept input.
input_filter	Callable[[HandoffInputData], HandoffInputData] | None	None	Function that filters the conversation history before passing it to the target agent.
nest_handoff_history	None	None	If True, nests the previous conversation history in a system message rather than passing it as direct context.
is_enabled	Callable[..., MaybeAwaitable[bool]]	True	Controls whether the handoff tool is available. Can be a static boolean or a callable for dynamic enablement.

Return Value

Returns a Handoff[TContext, Agent[TContext]] object that can be added to an agent's handoffs list. The SDK converts this object into a tool definition that the LLM can invoke.

Usage Examples

Basic Handoff

from agents import Agent, handoff

billing_agent = Agent(
    name="billing",
    instructions="Handle billing questions.",
    handoff_description="Handles billing and payment issues",
)
account_agent = Agent(
    name="account",
    instructions="Handle account management.",
)

triage_agent = Agent(
    name="triage",
    instructions="Route customer requests to the right agent.",
    handoffs=[handoff(billing_agent), handoff(account_agent)],
)

Handoff with Callback

from agents import Agent, handoff, RunContextWrapper

async def on_billing_handoff(ctx: RunContextWrapper[MyContext]) -> None:
    ctx.context.current_department = "billing"

triage_agent = Agent(
    name="triage",
    instructions="Route requests appropriately.",
    handoffs=[
        handoff(billing_agent, on_handoff=on_billing_handoff),
    ],
)

Handoff with Typed Input

from pydantic import BaseModel
from agents import Agent, handoff, RunContextWrapper

class EscalationInput(BaseModel):
    reason: str
    priority: int

async def on_escalate(ctx: RunContextWrapper[MyContext], input: EscalationInput) -> None:
    ctx.context.escalation_reason = input.reason
    ctx.context.priority = input.priority

triage_agent = Agent(
    name="triage",
    instructions="Route requests. When escalating, provide a reason and priority.",
    handoffs=[
        handoff(
            escalation_agent,
            on_handoff=on_escalate,
            input_type=EscalationInput,
        ),
    ],
)

Handoff with Custom Tool Name

from agents import Agent, handoff

triage_agent = Agent(
    name="triage",
    instructions="Route requests.",
    handoffs=[
        handoff(
            billing_agent,
            tool_name_override="route_to_billing",
            tool_description_override="Send the user to the billing department.",
        ),
    ],
)

Source Reference

Source: src/agents/handoffs/__init__.py:L211-320

Related Pages

• Principle: Openai_Openai_agents_python_Handoff_Configuration -- theory of agent-to-agent delegation.
• Implementation: Openai_Openai_agents_python_Bidirectional_Handoff_Pattern -- patterns for circular handoffs.
• Workflow: Openai_Openai_agents_python_Multi_Agent_Handoff -- end-to-end multi-agent workflow.

GitHub URL

Source: handoffs/__init__.py