handoff • AI Agent SDK

handoff: Create a handoff configuration for delegating tasks to another agent.

handoff

Function

This function is defined in the handoff module.

Create a handoff configuration for delegating tasks to another agent.

This is a convenience function that creates a Handoff instance with the specified configuration. It supports both the legacy API and the new unified HandoffConfig.

Signature

def handoff(agent: 'Agent', tool_name_override: Optional[str], tool_description_override: Optional[str], on_handoff: Optional[Callable], input_type: Optional[type], input_filter: Optional[Callable[[HandoffInputData], HandoffInputData]], config: Optional[HandoffConfig], context_policy: Optional[str], timeout_seconds: Optional[float], max_concurrent: Optional[int], detect_cycles: Optional[bool], max_depth: Optional[int]) -> Handoff

Parameters

agent · Agent · required

The target agent to hand off to

tool_name_override · Optional

Custom tool name (defaults to transfer_to_<agent_name>)

tool_description_override · Optional

Custom tool description

on_handoff · Optional

Callback function executed when handoff is invoked

input_type · Optional

Type of input expected by the handoff (for structured data)

input_filter · Optional

Function to filter/transform input before passing to target agent

config · Optional

HandoffConfig for advanced settings

context_policy · Optional

Shorthand for config.context_policy (“full”, “summary”, “none”, “last_n”)

timeout_seconds · Optional

Shorthand for config.timeout_seconds

max_concurrent · Optional

Shorthand for config.max_concurrent

detect_cycles · Optional

Shorthand for config.detect_cycles

max_depth · Optional

Shorthand for config.max_depth

Returns

Returns · Handoff

A configured Handoff instance

Usage

from praisonaiagents import Agent, handoff, HandoffConfig

    billing_agent = Agent(name="Billing Agent")
    refund_agent = Agent(name="Refund Agent")

    # Simple usage
    triage_agent = Agent(
        name="Triage Agent",
        handoffs=[billing_agent, handoff(refund_agent)]
    )

    # With config
    triage_agent = Agent(
        name="Triage Agent",
        handoffs=[
            handoff(billing_agent, context_policy="summary", timeout_seconds=60),
            handoff(refund_agent, config=HandoffConfig(detect_cycles=True))
        ]
    )

Uses

• HandoffConfig
• ContextPolicy
• Handoff

Source

View on GitHub

praisonaiagents/agent/handoff.py at line 669

---

Related Documentation

Handoffs Concept

Handoffs Feature