> For the complete documentation index, see [llms.txt](https://documentation.proto.cx/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.proto.cx/docs/modules/ai-agents/workflows-and-actions/ai-agent-handoff.md).

# AI agent handoff

`Action` — Requires the receiving AI agent's ID, secret, and platform domain from its [Network settings](/docs/modules/ai-agents/manage-ai-agents.md#agent-tabs).

## What it does

Moves a conversation from one AI agent (AI agent A) to another (AI agent B), continuing in the same chat window without the person needing to restart.

## When to use it

When different AI agents specialise in different workflows, data sources, or institutions — so the person reaches the right agent without restarting.

## Connecting an AI agent

Copy these details from the receiving AI agent (AI agent B), found in its [Network settings](/docs/modules/ai-agents/manage-ai-agents.md#agent-tabs):

| Field               | Description                                     |
| ------------------- | ----------------------------------------------- |
| **AI agent ID**     | Unique identifier for the receiving agent.      |
| **AI agent secret** | Secure key used to verify inbound connections.  |
| **Platform domain** | The domain where the receiving agent is hosted. |

Then in AI agent A:

{% stepper %}
{% step %}

### Open the action

Open the **AI agent handoff** action in the workflow tree.
{% endstep %}

{% step %}

### Connect the agent

Select **Connect external AI agent**.
{% endstep %}

{% step %}

### Enter credentials

Paste the AI agent ID, secret, and platform domain.
{% endstep %}

{% step %}

### Verify

Select **Verify & save**.
{% endstep %}
{% endstepper %}

## What carries over

Session context transfers automatically so the person does not repeat themselves. Chat variables from the originating chat are passed to the receiving agent in a single `_transferred_context` variable as a JSON structure. Internal or sensitive data is filtered out automatically.

## Security

Each AI agent has a unique secret key. All handoffs are authenticated, preventing unauthorised systems from intercepting conversations.

## Example

```
Message received: "I want to complain about my bank"
├─ Send message: "Transferring you to our complaints agent..."
└─ AI agent handoff
   • AI agent ID, secret, platform domain of the complaints agent
```

The receiving agent's workflow reads carried-over values from `_transferred_context`.

## Related

{% content-ref url="/pages/aLlL00SsNeVzsBT6G7gY" %}
[Live agent handoff](/docs/modules/ai-agents/workflows-and-actions/live-agent-handoff.md)
{% endcontent-ref %}

{% content-ref url="/pages/EBzV3f92cqcYL1yuFMPL" %}
[External handoff](/docs/modules/ai-agents/workflows-and-actions/external-handoff.md)
{% endcontent-ref %}