Human Handoff

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

Field reference: handoff_settings — every field, type, default, and tier for this page.

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

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 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 to receive replies back into the conversation.
Telegram	Sends a message to a Telegram chat using a bot you create via @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).

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)

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.

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 page. See Agent-to-agent patterns for the protocol details.

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.

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 [e-mail]. 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 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 for authentication and the full tool catalogue.