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

# A2A connections

> Connect an external AI agent over the Agent2Agent (A2A) protocol so your Callers agent can delegate to it during live conversations.

An A2A connection links your Callers agent to an external AI agent that supports the open [Agent2Agent (A2A) protocol](https://a2a-protocol.org). During a conversation, Callers sends the conversation to the external agent, and the external agent's replies guide what your Callers agent says and does. Use it when the reasoning or data lives in an agent you already run, such as a support agent with access to your back office, and you want Callers to handle the voice or chat side.

<ol />

## Requirements

Your external agent must:

* Expose an A2A **agent card** at its base URL. Callers reads the card to get the agent's name, endpoint, and optional input schema.
* Accept A2A requests over JSON-RPC.
* Accept a bearer token. Callers sends `Authorization: Bearer <token>` with every request, including the agent card request.
* Be reachable over the public internet. Requests come from Callers' outbound IP addresses, `35.245.204.86` and `35.221.61.75`.

## Create a connection

**1. Open A2A Connections**

In the left sidebar, under **Resources**, click **A2A Connections**, then **Create New**.

**2. Enter the URL and token**

Enter the agent's base **URL** and the authentication **Token**. Callers fetches the agent card when you save. The agent's name comes from the card.

**3. Adjust additional settings (optional)**

Expand **Additional settings** to change how and when Callers talks to the agent. See the settings table below.

**4. Save**

The connection appears in the list with the agents that use it (**Used by**) and its creation date.

### Connection settings

| Setting | What it does | Default |
| - | - | - |
| **URL** | Base URL of the external agent. The agent card is resolved from here. | Required |
| **Token** | Authentication token, sent as a bearer token | Required |
| **Sync input schema from agent card** | Refreshes the input schema from the agent card each time you save. Turn off to keep manual schema overrides. | On |
| **Override first message** | Sends your own **First message** to the external agent when a conversation starts, instead of the default | Off |
| **Restart response when new A2A input arrives** | If the external agent replies before your agent starts speaking, regenerate the response with the new input. Input that arrives after speaking starts is used on the next turn. This can add response time. | Off |
| **When to send A2A requests** | **On user messages**: buffer agent replies and tool results, and send them with the next contact message. **On every message**: send contact messages, agent messages, and tool results as they happen. | On user messages |
| **Send tool call results to the agent** | Shares the name, request, and response of every tool (action) your agent uses during the conversation | Off |

## Add a connection to an agent

**1. Open the agent's scenarios**

In the agent editor, open **Scenarios**. Click **Connect A2A** in the header.

**2. Select connections**

Select one or more A2A connections. The button changes to **A2A Connected** with the number of connections.

**3. Map metadata (optional)**

Click the edit icon next to a connection to open **Edit mapping**. If the agent card defines an input schema, map each field to an agent [variable](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md) or a fixed value, so the external agent receives structured context with each request. JSON values can include `{{variable}}` placeholders. You can also set a **Context ID** from a contact variable to group conversations on the external agent's side.

**4. Save and test**

Save the agent and place a [test call](https://docs.callers.ai/documentation/build-your-agent/testing-your-agent.md). A2A requests and responses appear in the transcript.

> [!NOTE]
>
> Metadata mappings support contact variables only. Call data, metadata, and action tags aren't supported in mappings.

## Wait for the external agent in the script

By default the conversation keeps flowing while the external agent works. To hold the script until it answers, add a **Wait for results** step and choose the connection under **Wait for** (as a **Connected agent**). A Wait for results step must be the only step in its block.

| Setting | What it does |
| - | - |
| **Wait for** | One or more connected agents or actions to wait on |
| **Continue when** | **All succeed** or **Any succeeds** |
| **Say while waiting** | What the agent says while it waits |
| **Timeout in seconds** | How long to wait before taking the fallback path |
| **Paths** | **Ready** when the results arrive; **Fallback** on timeout or failure |

If the list is empty, the message "Enable an A2A connection for this agent first." means you need to connect the agent on the Scenarios page first.

## Manage connections

* **Edit**: open the connection from the list to change the URL, token, or settings. Changes apply to every agent that uses it.
* **Delete**: removes the connection permanently and from every agent that uses it. Check **Used by** first.

## Best practices

* **Keep the external agent fast.** It's part of a live conversation. Return short, direct guidance and avoid long tool chains on the critical path.
* **Start with On user messages.** It sends fewer requests and gives the external agent complete turns. Switch to **On every message** only if the external agent needs to react to your agent's own replies in real time.
* **Pass identifiers as metadata**, such as a customer ID, instead of relying on the external agent to parse them from speech.
* **Use a Wait for results step with a fallback** where the conversation can't continue without the external agent's answer.

## Troubleshooting

> **Saving the connection fails**
>
> Callers couldn't fetch the agent card. Check that the base URL is correct and public, that the agent card is published, and that the token is valid.

> **The mapping editor shows no fields**
>
> The agent card doesn't define an input schema, or **Sync input schema from agent card** was off when you saved. Turn it on and save the connection again.

> **The agent ignores the external agent's replies**
>
> Check that the connection is selected on the agent's Scenarios page and that the external agent returns a response before the turn ends. Use a Wait for results step if the answer is required.

> **Responses feel slow**
>
> Turn off **Restart response when new A2A input arrives**, reduce the external agent's latency, and send requests **On user messages**.

## Related

> **[Scenarios](https://docs.callers.ai/documentation/build-your-agent/agent-scenarios.md)**
>
> Where you connect A2A agents to an agent.

> **[Steps](https://docs.callers.ai/documentation/build-your-agent/customizing-steps.md)**
>
> The Wait for results step and other step types.

> **[Actions overview](https://docs.callers.ai/documentation/integrations/summary-actions.md)**
>
> Other ways to call your systems during a conversation.

> **[Variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md)**
>
> Values you can map into A2A metadata.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.