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

# Agent-to-agent patterns

> Three ways your agent can work with peer agents — delegate-as-call, bridge / relay, and transfer / drop-out. When each applies and how to configure it.

Your agent can work with peer agents in three ways. Picking the right one
matters: they differ in cost, latency, observability, and who stays responsible
for the conversation.

## Quick comparison

| Pattern                 | Who's in the loop?                                                                        | Where you configure it                              |
| ----------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **Delegate-as-call**    | Your agent stays in control; the peer answers a sub-question and exits.                   | **Delegates** page                                  |
| **Bridge / relay**      | Your agent relays every user message to a peer; the peer's replies come back through you. | **Handoff** page, `Agent` channel kind              |
| **Transfer / drop-out** | Your agent steps out; the user's own agent talks to the target directly.                  | Same as bridge, plus a consent toggle on the target |

## Pattern 1 — Delegate-as-call

Use when a peer is better-suited to a specific sub-task and you want to fold its
answer into your own reply. The user never sees the peer — from their point of
view they're still talking to you.

**Configure** on the **Delegates** page. Pick the peer's kind:

* **Sibling** — another agent you own, called directly with no network hop and
  no API key.
* **External** — any A2A-compatible peer. Provide the target URL and a bearer
  token, stored encrypted.

Your agent gets a `delegate_to_agent(target_id, message, conversation_token?)`
tool. It picks the target from the descriptions you wrote, sends a self-contained
question, and folds the response into its reply. To keep talking to the same
peer about the same thread, it passes back the `conversation_token` the tool
returns.

Delegate calls share the same hop limit as handoffs — see [Hop
limit](#hop-limit).

## Pattern 2 — Bridge / relay

Use when the request is fully outside your agent's scope and a peer should take
over the conversation, but you still want to stay in the audit path.

**Configure** on the **Handoff** page: add a channel with kind `Agent`, and pick
a sibling agent or paste an external A2A URL and API key. Your agent offers the
channel as a handoff option and picks it when the routing description matches.
You can also start a bridge manually from the Handoff page — pick a chat, pick a
destination, write a summary, and start.

Once a bridge is active:

* Every user message is relayed to the peer (no model call on your side), and
  the peer's replies come back through you.
* The **Inbox** shows a `Bridge active → <peer>` status.
* The bridge ends when the peer releases it (optionally passing values and
  context back to your agent's next turn), when you click **Release bridge** in
  the Inbox, when the user types `/release`, or on idle timeout.

## Pattern 3 — Transfer / drop-out

Use when two Agentheya agents are bridging a conversation that could be carried
directly between the user's own agent and the target — removing the relay hop.

Drop-out happens only between Agentheya agents. When it fires, the user sees a
brief note in their transcript saying the conversation was retargeted, and from
then on their agent talks to the target directly. Otherwise the experience is
identical to a bridge — but the cost and latency of the middle hop disappear.

**Configure**: on the target agent's **Details** page, toggle **Accept drop-out
from external Agentheya agents** if you want peers from other owners to be able
to drop out to you. Agents owned by the same person need no configuration.
Drop-out is an optimization; a bridge is always a valid fallback.

## Hop limit

All three patterns share a single limit on how deep a chain of agents calling
agents can go — a maximum of **5 hops** — so a loop can't run away. At the
limit, your agent won't open another agent-to-agent call. Human channels
(email, Telegram, owner inbox, and the rest) end the chain and don't count
toward the limit.

## Picking between patterns

* **Sub-question on a specific topic, user stays talking to you**: delegate.
* **Conversation has shifted to a domain another agent owns, and you want
  auditability and the option to take over again**: bridge.
* **Same conversation, both peers are Agentheya, and you want to step out**:
  drop-out.