> 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

{% hint style="info" %}
An external AI agent handoff requires at least one connected AI Agent with [valid credentials](/docs/modules/ai-agents/manage-ai-agents.md#external-ai-agent-handoff) (AI Agent ID, AI Agent secret, and Platform domain) to receive conversations from the originating AI Agent.
{% endhint %}

The External AI Agent Handoff action enables a conversation to move seamlessly from one AI (for example, **AI Agent A**) to another (**AI Agent B**). This is useful when different AIs specialize in different workflows, data sources customer profile, or when referring tickets from different institutions to support collaboration.

***

### Configuration

To connect an external AI agent:

1. Go to the **AI Agents module** and open the **Action** tab.
2. Select Add Trigger and create.
3. Choose add action and locate the **External AI Agent Handoff.**

<figure><img src="/files/CehypvMDju2IpZ9JI7dL" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/NBG4WMScD2ovbOoCr6vg" alt=""><figcaption></figcaption></figure>

1. Copy the following connection details from **AI Agent B** (the receiving agent):

   * **AI Agent ID** – a unique identifier for the agent.
   * **AI Agent Secret** – a secure key used to verify inbound connections.
   * **Platform Domain** – the domain where the agent is hosted (for example, `https://v3-api.proto.cx`)<br>

   <div align="left"><figure><img src="/files/1SVt7BQz1Ti6iQd5mOvC" alt=""><figcaption></figcaption></figure></div>

2. In **AI Agent A**, open the **AI Agent Handoff** action.

3. Select **Connect External AI Agent**.

4. Paste the copied details into the corresponding fields:
   * AI Agent ID
   * AI Agent Secret
   * Platform Domain

5. Click **Verify & Save**.

Once verified, **AI Agent A** can hand off conversations directly to **AI Agent B**.

***

#### Handoff

During the chat session, when an end-user triggers one of the keywords linked to a handoff intent, the conversation continues seamlessly in the same chat window — moving from **AI Agent A** to **AI Agent B**.

When this happens, all relevant session details are automatically carried over to the next AI agent. This means the user’s context — such as name, issue type, and any answers they’ve already provided — remains available, so they never have to repeat information.

The system automatically filters out internal or sensitive details (for example, authentication data or internal notes) to ensure that only the information needed for the handoff is shared.

### Example Setup

* **AI Agent A:** Handles general customer inquiries.
* **AI Agent B:** Specializes in technical support.

When a customer asks a question requiring technical help, AI Agent A automatically transfers the conversation to AI Agent B using the configured credentials.

***

### Security

Each AI agent has a **unique secret key** to ensure all handoffs are authenticated and secure. This prevents unauthorized systems from accessing or intercepting conversations.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.proto.cx/docs/modules/ai-agents/workflows-and-actions/ai-agent-handoff.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.