> For the complete documentation index, see [llms.txt](https://docs.orbitfin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orbitfin.ai/orbit-api-reference/a2a/2.-a2a-setup.md).

# 2. A2A Setup

All A2A services are hosted on the same domain and follow one pattern:

[https://studio.orbitfin.ai/\<service>/a2a](https://studio.orbitfin.ai/<service>/a2a)

Step 1: Obtain API Key

The caller needs an API Key under an Agent Builder account as an identity credential — all actual A2A calls must carry it.

Step 2: Confirm the A2A Service Address

| Service       | A2A endpoint                              |
| ------------- | ----------------------------------------- |
| Agent Builder | <https://studio.orbitfin.ai/builder/a2a>  |
| Agentic Chat  | <https://studio.orbitfin.ai/research/a2a> |

Step 3: Read the Agent Card and Verify Connectivity

The Agent Card is a publicly readable "business card" document — no authentication required. It confirms the service is reachable and lists what it can currently do: the service name, its description, the supported authentication methods, and the full set of capabilities (Skills).

Append `/.well-known/agent-card.json` to any endpoint above:

| Service       | Agent Card URL                                                                                                                                       |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent Builder | <https://studio.orbitfin.ai>[/builder/a2a/.well-known/agent-card.json](https://orbit-api-agent.orbitfin.ai/builder/a2a/.well-known/agent-card.json)  |
| Agentic Chat  | <https://studio.orbitfin.ai/research/a2a>[/.well-known/agent-card.json](https://orbit-api-agent.orbitfin.ai/builder/a2a/.well-known/agent-card.json) |

If the document comes back, this step is configured correctly. Note that each service publishes its own card with its own Skill list — read both if you plan to call both.

**Step 4 — Authenticate your calls**

Each Agent Card declares two accepted authentication methods. Either one is sufficient — do not send both.

| Method       | Usage                                               |
| ------------ | --------------------------------------------------- |
| API Key      | Request header `X-API-Key: YOUR_API_KEY`            |
| Bearer Token | Request header `Authorization: Bearer YOUR_API_KEY` |

```
curl -X POST https://studio.orbitfin.ai/builder/a2a \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

Calls without a valid credential will be rejected; reading the Agent Card itself does not require authentication.

Protocol Version

This endpoint accepts A2A v1.0 only (PascalCase method names: SendMessage / SendStreamingMessage / GetTask / CancelTask). Legacy v0.3 method names such as message/send are not supported. As a matter of standard practice, include the following request header:

A2A-Version: 1.0