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

# Human Handoff

> Configure channels, routing, manual triggers, and delegates for escalating conversations to humans or peer agents.

<Info>
  **Field reference:** [`handoff_settings`](/reference/handoff_settings) — every field, type, default, and tier for this page.
</Info>

Human Handoff lets your agent escalate a conversation to a real person — or to another agent — when it cannot, or should not, handle the request itself. When a handoff is triggered, the agent notifies the operator via the configured channel and optionally pauses further automated replies until the human has responded.

To enable handoff, turn on the `handoff_request` tool on the [Tools](/sidebar-menu/tools) page, then configure at least one channel below.

For the protocol-level comparison of the three peer-agent patterns (delegate / bridge / drop-out), see [Agent-to-agent patterns](/peer-patterns).

## How handoff works

1. The agent decides to escalate — via the `handoff_request` tool, an auto-escalation rule, or an explicit operator trigger from this page.
2. Agentheya sends a structured summary (and optionally the recent transcript) to the operator via the configured handoff channel.
3. The operator reads the context and replies — by email, in Telegram, Slack, Discord, WhatsApp, or the dashboard **Inbox**.
4. For sibling/external Agent channels, every subsequent visitor message is bridged to the peer until you release the bridge (or the receiving agent calls `handoff_release`).
5. **Optional structured return data:** if the agent declared an `expected_return` schema on the request, the recipient is shown a fillable form (humans via a signed-URL link in the dispatch; sibling agents via the `[EXPECTED RETURN SCHEMA]` block in their initial context). The filled values come back to the originator on the `[Bot resumed]` system message as a `Returned data:` block, ready for the LLM to act on. Validation is best-effort — missing required fields are recorded in the audit trail but do **not** block the release; the originator's LLM sees what came back and what was missing and decides how to respond. See [handoff\_request → expected\_return](/builtin-tools/handoff_request#expected_return-schema) for the field shape.

## The Handoff page

The page is split into four collapsible sections:

### 1. Channels & Routing

The configuration surface. Pick a channel kind, give it a label, fill in the platform-specific fields, and toggle it ON.

| Channel kind    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Email**       | Sends an escalation email to the operator address you specify, with the conversation context. Pair with an inbound [Email Address](/sidebar-menu/email-addresses) to receive replies back into the conversation.                                                                                                                                                                                                                                                                                                           |
| **Telegram**    | Sends a message to a Telegram chat using a bot you create via [@BotFather](https://t.me/BotFather). Paste the bot token + chat id; click **Register webhook** to start receiving the chat's replies back.                                                                                                                                                                                                                                                                                                                  |
| **Slack**       | Posts the escalation to a Slack channel via a Slack app you create. Paste the app's **Bot User OAuth token** (`xoxb-…`, needs the `chat:write` scope) and the destination **Channel ID** (right-click the channel → Copy link → the trailing path segment, then invite the bot to it). To route a human's Slack reply back into the conversation, also paste the app's **Signing secret** and set the **Event Subscriptions** Request URL that Agentheya shows for this channel; without both, the channel is notify-only. |
| **Discord**     | Posts the escalation to a Discord channel via a bot you create in the Discord Developer Portal. Paste the **bot token** and the **Channel ID** (enable Developer Mode, then right-click the channel → Copy Channel ID). Enable the privileged **Message Content Intent** on the bot so a human's reply in that channel routes back to the user — and `/release` hands control back to the bot.                                                                                                                             |
| **WhatsApp**    | Sends the escalation over WhatsApp. Enter the **recipient phone** in E.164 format (leading `+`, no spaces), then **pair the sending account** by scanning a QR code (WhatsApp → Settings → Linked devices → Link a device) with the phone or WhatsApp Business app that should send the messages. The channel's **status** moves from *not paired* → `qr_pending` → `connected` once paired (or `error` if it fails); dispatch requires `connected`.                                                                       |
| **Owner inbox** | Escalation lands in the dashboard **Inbox**. You read the transcript there and reply as yourself — the message goes back to the user on their original channel. No extra config needed.                                                                                                                                                                                                                                                                                                                                    |
| **Agent**       | Bridge the conversation to a peer agent — either a sibling (one of your other agents) or an external A2A-compatible peer (URL + API key). The peer takes over, and you can release the bridge from the Inbox at any time. Siblings call in-process (no key needed); for external peers the bearer token is encrypted at rest, and **Refresh agent card** in the channel card fetches and caches the peer's `/.well-known/agent-card.json`.                                                                                 |

Each channel has a **Description for agent** field — a short note the LLM uses when deciding between channels — and an **Idle timeout** (1–1440 minutes) after which an unresponded handoff is considered stale.

#### Context policy and extraction

* **Context policy** controls what gets sent to the recipient: include transcript yes/no, max turns to include (0–200), optional PII redaction.
* For **Agent** channels with a sibling target, you can also configure **Context extraction** (mode: `none`, `deterministic`, or `llm`) to populate up to 20 named fields the peer agent should receive alongside the transcript.

#### Routing instructions and auto-escalation

A free-text **Routing instructions** field at the bottom lets you tell the LLM which channel to pick in plain English. Below it, the **Auto-escalation** toggle enables structured rules that fire a handoff without an LLM tool call:

* **Keyword** rules — list patterns; any match in a user message triggers the rule's channel.
* **Consecutive unresolved turns** — triggers after N consecutive turns where the agent failed to resolve the issue (N from 2 to 20).

Each rule has a target channel and urgency (`low` / `normal` / `high`); up to 20 rules total.

### 2. Manual Handoff

Lets you trigger a handoff yourself on an active conversation, without waiting for the bot to decide.

Pick the conversation, pick a destination channel, write a summary of at least 20 characters (max 2000), pick an urgency, and toggle **Include recent transcript** on or off. Click **Start handoff**.

Conversations that already have an active handoff are marked `[bridge active]` in the picker and cannot be re-triggered until you release the existing handoff (see the [Inbox](/sidebar-menu/inbox)).

### 3. Delegates

A separate list of peer agents for single-shot sub-tasks via the `delegate_to_agent` tool. Unlike Agent-kind handoff channels, delegates do **not** take over the conversation — the visitor stays talking to your agent, and the LLM folds the delegate's answer into its own reply.

For each delegate target, set:

* **Kind** — *Sibling* (in-process call to another agent you own) or *External A2A* (URL + bearer API key for any A2A-compatible peer).
* **Label** — shown to the LLM.
* **Description for the LLM** — when this peer should be used. The model picks `target_id` based on this text.

Delegates have their own ON/OFF toggle and live in a separate table from handoff channels. They are a separate dimension from handoff channels and are **not** selectable as `handoff_request` targets.

#### Internal Agents (same-owner caller allowlist)

<Info>
  **Business plan.** The **Internal Agents** card is only available on the Business plan (it's part of A2A peer routing). On lower plans it's replaced by an upgrade prompt. This card moved here from the Details page.
</Info>

Directly below Delegates, the **Internal Agents** card controls which of *your own other agents* are allowed to call this agent. Add agents from the dropdown to build an allowlist, then press **Save allowed agents**. It is same-owner only and never grants access to agents owned by other users. An **empty allowlist means no other agent may call this one**.

### 4. Incoming (A2A)

How *other* agents reach this one. This section shows the agent's A2A endpoint URL, a link to its discovery (agent) card, a cross-owner **drop-out consent** toggle, and a feed of recent peer activity (delegate calls, bridge relays, retargets). Inbound callers authenticate with keys from the [API Keys](/sidebar-menu/api-keys) page. See [Agent-to-agent patterns](/peer-patterns) for the protocol details.

<Info>
  Subscribers have their own handoff page on the subscriber dashboard, where they manage their personal escalation channels (email, Telegram, or an external A2A agent of their own); your owner channels appear there read-only.
</Info>

## Inbox takeover and bridge release

Once an escalation fires, the operator can open the **Inbox** page:

* For *Email* / *Telegram* / *Owner inbox* channels — read the transcript and **Take over** the conversation. While taken over, the bot stops auto-replying and your messages go to the user on their original channel.
* For *Agent* channels — see the **Bridge active** pill and click **Release bridge** to end the relay. The bot resumes on the next visitor turn. Visitors can also type `/release` to end a bridge.

## Examples

**Hello world — escalate to email.** Add an **Email** handoff channel pointing at `support@yourco.com`. When the agent can't help, it escalates; you get the transcript by email and can take over from the Inbox. The simplest safety net.

**Medium — tiered escalation.** Add two channels: an **Owner inbox** channel for general escalations and a **Telegram** channel for urgent ones. Guide the agent (via rules or context) to use Telegram only for time-sensitive issues, so routine escalations land in the Inbox and urgent ones ping your phone.

**Complex — agent-to-agent bridging.** Add an **Agent** handoff channel pointing at a specialist sibling agent (e.g. a billing agent). When a general support conversation turns into a billing question, your agent bridges the visitor to the billing agent, which handles the thread directly and can hand back. The visitor stays in one conversation while it's relayed to the right specialist — release the bridge (or let the visitor type `/release`) to return control.

## Testing handoff

Use the **Preview** chat to simulate a conversation and verify the agent escalates correctly under the conditions you defined.

## Manage via the Management MCP

This area is managed through the [Management MCP](/manage-mcp) at `https://manage.agentheya.com/mcp`.

|          |                                                                      |
| -------- | -------------------------------------------------------------------- |
| Endpoint | `https://manage.agentheya.com/mcp`                                   |
| Tools    | `list_handoff_channels, add_handoff_channel, remove_handoff_channel` |

All tools take `owner_id` + `agent_id` as required arguments. See the [Management MCP guide](/manage-mcp) for authentication and the full tool catalogue.