# Connect an external A2A agent

An external A2A agent is an AI agent hosted by your organization or by a vendor
that speaks the open [A2A (Agent2Agent) protocol](https://a2a-protocol.org).
When you register one, the Mesh assistant can find it, see what it can do, and
send it a message during an investigation — for example, asking an agent in
your ITSM or access-management system to act on a finding.

The agent's response is returned to the assistant for the current request.

This page covers the **outbound** direction: Mesh calling your agents. For the
other direction, where your agents call Mesh, see
[Connect your agent to Mesh](../overview/connect-your-agent-to-mesh.md).

Nothing is connected by default. The assistant uses an agent only after an
administrator registers it.

> **warning**

Connect only an agent that your organization trusts. The assistant sends
messages to the agent using the credentials you provide, and the agent's
response can influence the assistant's answer. The message the assistant
sends can include details from your investigation, such as identity and risk
information. Treat it as data you are sharing with that agent and its operator.
For how Mesh handles data in AI features, see
[AI features and data handling](../overview/ai-features-data-handling.md).

## Before you begin

Prepare the following:

- A Mesh administrator account. The **External agents** page appears only when
  AI features are turned on for your tenant.
- The agent's base URL.
- The credentials the agent requires. See
  [Authentication options](#authentication-options).
- The path to the agent's agent card, if the agent does not publish it at the
  standard path.

## Authentication options

Choose the scheme that your agent expects:

| Scheme | What Mesh sends |
| --- | --- |
| **API key** | Your key in an HTTP header. The header is `X-API-Key` unless you set another name |
| **Bearer token** | Your token as a bearer credential |
| **OAuth 2.0** | A token that Mesh gets from your token URL, using your client ID and client secret. By default Mesh uses the client credentials grant; you can use a refresh token instead. You can add a scope |

## Add an agent

Open the External agents page from the dashboard:

- In the Generative UI dashboard, select **Settings**, then **External agents**.
- In the classic dashboard, select **Settings**, then **Config Management**,
  then **External agents**.

On the External agents page:

1. Select **Add external agent**.
2. Choose the A2A external agent from the list.
3. Fill in the form. See [What you enter](#what-you-enter).
4. Select **Add & connect**.

Mesh does not require a connection test before you save an agent, so check the
base URL, the agent card path and the credentials before you select **Add &
connect**.

### What you enter

| Setting | Required | What to enter |
| --- | --- | --- |
| Agent name | Yes | A display name for the agent |
| Base URL | Yes | The agent's base URL |
| Description | No | What the agent does |
| Agent card path | No | Where the agent publishes its agent card. The default is `/.well-known/agent-card.json`. Set it only if the agent uses a different path |
| Auth scheme | Yes | `apiKey`, `bearer` or `oauth2`. The credential settings below depend on your choice |
| **API Key** | For `apiKey` | The key for the agent. You can also set the header name, which defaults to `X-API-Key` |
| **Bearer Token** | For `bearer` | The token for the agent |
| **Client ID** and **Client Secret** | For `oauth2` | The OAuth 2.0 client credentials |
| Token URL | For `oauth2` | The OAuth 2.0 token endpoint |
| OAuth grant type | For `oauth2` | `client_credentials` (the default) or `refresh_token` |
| **Refresh Token** | For the `refresh_token` grant | The OAuth 2.0 refresh token. Client ID, client secret and token URL are still required |
| OAuth scope | No | A scope to send when Mesh gets a token |
| Skills | No | The skills or capabilities the agent provides |
| Enabled | No | On by default. Turn it off to register the agent without using it yet. The assistant can still see a disabled agent in its list, but cannot call it |
| Timeout | No | How many seconds Mesh waits for the agent. The default is 30. Enter a value from 5 to 300 |

Credential fields are hidden as you type. Do not paste secrets into
descriptions, screenshots, support tickets or chat messages.

## Turn an agent on or off

The agent list has a **Status** toggle for each agent. Turn it off to stop the
assistant from using the agent, and turn it on again when the assistant should
use it. Turning an agent off keeps its configuration.

The assistant cannot call an agent that is turned off, whether you turn it off here or clear **Enabled** in the form.

## Edit an agent

Open the agent's action menu in the list and select **Edit** to change its
settings.

## How the assistant uses your agents

During an investigation, the assistant can:

- **List your agents.** It sees each agent's name, description and skills.
- **Send a message to an agent.** It sends the message and brings the agent's
  response back into the conversation.

> **note**

External agents work only when your Mesh deployment includes A2A support. Exact
labels can depend on the version deployed in your environment, so verify the
target environment before you rely on this workflow.

## Next steps

- Review [AI features and data handling](../overview/ai-features-data-handling.md)
  to understand how Mesh handles data sent to AI features.
- See [Automated external remediation through A2A agents](../concepts/remediation.md#automated-external-remediation-through-a2a-agents)
  for how agents fit into fixing findings.
- Register tools instead of an agent with
  [External MCP servers](./external-mcp-servers.md).
- See [Roles and access](./roles-and-access.md) for administrator permissions.