> ## 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.

## 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]) -> Handoff
```

## Parameters

<ParamField query="agent" type="Agent" required={true}>
  The target agent to hand off to
</ParamField>

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

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

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

<ParamField query="input_type" type="Optional" 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" required={false}>
  HandoffConfig for advanced settings
</ParamField>

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

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

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

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

<ParamField query="max_depth" type="Optional" required={false}>
  Shorthand for config.max\_depth
</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

    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

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

***

## Related Documentation

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

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