Praison AI

handoff • AI Agent SDK

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

handoff

Function

</div>

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 with tool security boundary enforcement.

Signature

python
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], tool_policy_mode: Optional[Literal['intersect', 'passthrough']], blocked_tools: Optional[List[str]]) -> Handoff

Parameters

ParamField Agent

The target agent to hand off to

ParamField Optional[str]

Custom tool name (defaults to transfer_to_&lt;agent_name&gt;)

ParamField Optional[str]

Custom tool description

ParamField Optional[Callable]

Callback function executed when handoff is invoked

ParamField Optional[type]

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

ParamField Optional

Function to filter/transform input before passing to target agent

ParamField Optional[HandoffConfig]

HandoffConfig for advanced settings

ParamField Optional[str]

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

ParamField Optional[float]

Shorthand for config.timeout_seconds

ParamField Optional[int]

Shorthand for config.max_concurrent

ParamField Optional[bool]

Shorthand for config.detect_cycles

ParamField Optional[int]

Shorthand for config.max_depth

ParamField Optional

Tool boundary mode (“intersect” = secure by default, “passthrough” = legacy)

ParamField Optional

List of tool names to always block regardless of intersection

Returns

ResponseField Handoff

A configured Handoff instance

Usage

python
from praisonaiagents import Agent, handoff, HandoffConfig, HandoffToolPolicy

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

    # Simple usage (secure by default - tools intersected)
    triage_agent = Agent(
        name="Triage Agent",
        handoffs=[billing_agent, handoff(refund_agent)]
    )

    # With tool security config
    triage_agent = Agent(
        name="Triage Agent", 
        handoffs=[
            handoff(billing_agent, 
                    tool_policy_mode="intersect",  # Only shared tools
                    blocked_tools=["execute_code", "shell_tools"]),
            handoff(refund_agent,
                    config=HandoffConfig(
                        tool_policy=HandoffToolPolicy(
                            mode="passthrough",  # Legacy behavior
                            blocked_tools=["dangerous_tool"]
                        )
                    ))
        ]
    )

Uses

  • HandoffConfig
  • ContextPolicy
  • HandoffToolPolicy
  • Handoff

Source

View on GitHub

praisonaiagents/agent/handoff.py at line 1226

Related Documentation

Handoffs Concept Handoffs Feature