> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# handoff • AI Agent SDK

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

# handoff

<div className="flex items-center gap-2">
  <Badge color="teal">Function</Badge>
</div>

> This function is defined in the [**handoff**](../modules/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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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 query="agent" type="Agent" required={true}>
  The target agent to hand off to
</ParamField>

<ParamField query="tool_name_override" type="Optional[str]" required={false}>
  Custom tool name (defaults to transfer\_to\_\<agent\_name>)
</ParamField>

<ParamField query="tool_description_override" type="Optional[str]" required={false}>
  Custom tool description
</ParamField>

<ParamField query="on_handoff" type="Optional[Callable]" required={false}>
  Callback function executed when handoff is invoked
</ParamField>

<ParamField query="input_type" type="Optional[type]" required={false}>
  Type of input expected by the handoff (for structured data)
</ParamField>

<ParamField query="input_filter" type="Optional" required={false}>
  Function to filter/transform input before passing to target agent
</ParamField>

<ParamField query="config" type="Optional[HandoffConfig]" required={false}>
  HandoffConfig for advanced settings
</ParamField>

<ParamField query="context_policy" type="Optional[str]" required={false}>
  Shorthand for config.context\_policy ("full", "summary", "none", "last\_n")
</ParamField>

<ParamField query="timeout_seconds" type="Optional[float]" required={false}>
  Shorthand for config.timeout\_seconds
</ParamField>

<ParamField query="max_concurrent" type="Optional[int]" required={false}>
  Shorthand for config.max\_concurrent
</ParamField>

<ParamField query="detect_cycles" type="Optional[bool]" required={false}>
  Shorthand for config.detect\_cycles
</ParamField>

<ParamField query="max_depth" type="Optional[int]" required={false}>
  Shorthand for config.max\_depth
</ParamField>

<ParamField query="tool_policy_mode" type="Optional" required={false}>
  Tool boundary mode ("intersect" = secure by default, "passthrough" = legacy)
</ParamField>

<ParamField query="blocked_tools" type="Optional" required={false}>
  List of tool names to always block regardless of intersection
</ParamField>

### Returns

<ResponseField name="Returns" type="Handoff">
  A configured Handoff instance
</ResponseField>

## Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<Card title="View on GitHub" icon="github" href="https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/handoff.py#L1084">
  `praisonaiagents/agent/handoff.py` at line 1084
</Card>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Handoffs Concept" icon="hand-holding" href="/docs/docs/concepts/handoffs" />

  <Card title="Handoffs Feature" icon="arrow-right-arrow-left" href="/docs/docs/features/handoffs" />
</CardGroup>