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

# A2A

> Discover and call AIDA over A2A using three agent-card and per-agent endpoints.

A2A lets external agent runtimes discover and talk to AIDA. Discovery and per-agent calls use the Document Assistant REST surface under `/assistant/api/v1`. Use the same regional base URL and authentication as the rest of the [AI API](/aida-api/introduction).

This page covers the three endpoints most integrators need. Full request and response schemas live in the [OpenAPI](https://document-assistant.us.aodocs.app/openapi.json) playground.

## Agent cards and per-agent A2A

| Endpoint | When to use |
| - | - |
| `GET /assistant/api/v1/.well-known/agent.json` | Host-level agent card for multi-tenant integrators |
| `GET /assistant/api/v1/tenants/{tenant}/.well-known/agent.json` | **Recommended for most customers** — tenant-scoped agent card |
| `GET /assistant/api/v1/tenants/{tenant}/agents/{agent_id}/a2a` | Call a specific AODocs agent |

### Host-level agent card

```http theme={null}
GET /assistant/api/v1/.well-known/agent.json
```

No tenant appears in the path. Use this when you build a **multi-tenant** integrator that discovers a single host-level card and then selects a tenant at runtime.

<Warning>
  The host-level card does not bind a tenant. Your client must choose the tenant itself. If that guess is wrong, AIDA returns no useful answer and the end user cannot correct the tenant from the agent UI. Prefer the tenant-scoped card unless you truly need multi-tenant discovery.
</Warning>

### Tenant-scoped agent card (recommended)

```http theme={null}
GET /assistant/api/v1/tenants/{tenant}/.well-known/agent.json
```

**Recommended for most customers.** Replace `{tenant}` with your AODocs tenant identifier. The card is already scoped to that tenant, so callers do not have to guess which tenant to use.

### Call a specific AODocs agent

```http theme={null}
GET /assistant/api/v1/tenants/{tenant}/agents/{agent_id}/a2a
```

Use this path when you already know the AODocs `agent_id` and want to call that agent directly under the given tenant.

<Info>
  Prefer tenant-scoped discovery (`.../tenants/{tenant}/.well-known/agent.json`) unless you are building a multi-tenant integrator or targeting a known `agent_id`. For MCP tool clients, see [MCP](/aida-api/mcp).
</Info>


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