# Connect your agent to Mesh

Axiad Mesh exposes its AI agent over the open
[A2A (Agent2Agent) protocol](https://a2a-protocol.org), so your own AI agents
and orchestration platforms can talk to Mesh the same way they talk to any other
A2A-compatible agent. Your agent asks Mesh a question in natural language — "what
are the top risky identities?", "show me expiring certificates" — and Mesh
answers from your tenant's data, under your permissions.

This page covers the **inbound** direction: an external agent connecting *to*
Mesh. For the other direction — the Mesh AI assistant calling *your* registered
agents during an investigation — see
[Agent-to-agent integrations](./ai-features-data-handling.md#agent-to-agent-a2a-integrations).

## Discover the agent card

Every A2A agent publishes an **agent card**: a JSON document that describes who
the agent is, what it can do, and how to authenticate. Mesh serves its card at
the standard well-known path, and no authentication is required to read it:

```
GET https://<your-mesh-host>/.well-known/agent-card.json
```

The card advertises the agent's identity (name, description, provider, and
version), its transport endpoints, its capabilities, its skills, and its
supported authentication schemes. An A2A client library discovers all of this
automatically from the card, so your agent doesn't hard-code any of it.

## What Mesh can do (skills)

The card declares the **skills** the Mesh agent offers. Each skill has a name,
a description, tags, and example prompts your agent can use to decide when to
call Mesh:

| Skill | What you can ask |
| --- | --- |
| **Identity Search** | Find and discover identities across your systems by name, email, or other attributes. |
| **Risk Assessment** | Analyze identity and user risk scores, breakdowns, and the factors driving them. |
| **Asset Analysis** | List and analyze software, certificate, and machine assets — for example, expiring certificates. |
| **Correlation Management** | Review the identity correlations Mesh has drawn, and confirm or reject them. |
| **FAIR Risk Analysis** | Run quantitative [FAIR](../concepts/risk-scoring.md#from-scores-to-loss-estimates) analysis, filtered by provider, risk profile, or risk source. |

These map to the same capabilities the Mesh AI assistant uses inside the
dashboard, so an external agent reaches the same answers a person would — bounded
by the same permissions and tenant isolation.

## Capabilities

The card also declares how the agent communicates:

- **Streaming** — Mesh streams its response back as it is produced, so your agent
  can show progress rather than waiting for the full answer.
- **Push notifications** — for longer-running work, Mesh can call a webhook you
  register when a task changes state, so your agent doesn't have to poll. Push
  payloads carry only task status, never message content.

## Authenticate

Reading the card is open; **sending a message requires authentication**. Mesh
supports two inbound schemes, both declared in the card:

- **API key** — send your key in the `X-API-Key` request header.
- **Bearer token** — send a signed JWT in the `Authorization: Bearer <token>`
  header; Mesh verifies it against your identity provider's signing keys.

Either way, the credential carries the **tenant** the call belongs to, so every
message your agent sends is scoped to your organization's data and isolated from
every other tenant — exactly like any other access to Mesh. Credentials are
issued by your administrator; nothing is connected by default.

## Send a message

Mesh exposes the standard A2A interfaces, so any A2A client library works out of
the box:

- **JSON-RPC 2.0** at `POST /a2a/rpc` — the `message/send` and streaming
  `message/stream` methods.
- **REST** under `/a2a/v1/` for clients that prefer plain HTTP.

A typical exchange:

1. Your agent reads the agent card and picks a skill.
2. It sends a message — natural-language text, optionally with structured data —
   authenticated with your API key or bearer token.
3. Mesh opens a **task**, streams status updates as it works, and returns the
   answer as the task's result.

### Task lifecycle

A message creates a task that moves through the standard A2A states —
**submitted → working → completed** (or **failed**, or **canceled** if you cancel
it). Your agent can send a message and stream the result in one call, or send a
message and fetch or list tasks later. Results come back as A2A artifacts, so any
compliant client renders them the same way.

## Data handling

An inbound A2A call is subject to the same protections as every other use of the
Mesh AI assistant: it only reaches data your credential is permitted to see,
personal data is tokenized before any AI request leaves the platform, and the
interaction is recorded in the audit trail. See
[AI features and data handling](./ai-features-data-handling.md) for the full
picture.

## Related

- [AI features and data handling](./ai-features-data-handling.md) — where AI
  appears in Mesh and how data is protected.
- [Risk scoring](../concepts/risk-scoring.md) — the scores and FAIR analysis the
  agent returns.
- [A2A protocol](https://a2a-protocol.org) — the open standard Mesh implements.