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

# Connect an agent over A2A

> Let Copilot Studio, ServiceNow, Foundry, Gemini, or your own agent search your endpoint over the Agent-to-Agent protocol.

Every Raily endpoint also speaks the Agent-to-Agent (A2A) protocol. An agent built on another platform, such as Microsoft Copilot Studio or ServiceNow, can send your endpoint a question and get back the same results your MCP clients and SDK apps get. It uses the same sources, the same search config, and the same API key.

Raily supports A2A v1.0 and v0.3.

> [!NOTE]
>
> A2A is available on request. [Contact us](https://www.raily.ai/contact) to turn it on for your Account. Until it is on, the A2A addresses below return `404` and the endpoint page does not show the A2A card.

## Before you begin

* A2A is on for your Account.
* You have an endpoint that serves search. See [AI Endpoints](https://docs.raily.ai/concepts/ai-endpoints.md).
* You have an API key that covers the endpoint. Create one under **API access** on the endpoint page, or on the **API keys** tab in [Access](https://docs.raily.ai/features/access.md).

## Get the agent URL

**1. Open the endpoint**

In **Search Rail**, select the endpoint under **Your audience** to open its **Endpoint settings** page.

**2. Find the A2A card**

The **Connect an agent (A2A)** card shows the agent URL with a copy button. Under it, **Agent card:** shows the agent card URL.

Both are built from the endpoint's address:

| | Address |
| - | - |
| Agent URL | `{endpoint address}/a2a` |
| Agent card | `{endpoint address}/.well-known/agent-card.json` |

The endpoint address is the endpoint URL without the trailing `/mcp`, for example `https://endpoints.app.raily.ai/t/your-workspace/123`.

**3. Paste it into your agent platform**

Click **Where to paste it** on the card for steps in Microsoft Copilot Studio, Microsoft Foundry, ServiceNow AI Agent Fabric, Google Gemini Enterprise and ADK, and frameworks like LangGraph and CrewAI. Some platforms ask for the agent URL, others for the agent card URL.

For the key, send it as `Authorization: Bearer <key>`, or in an `X-API-Key` header when the platform asks for a named header.

If the endpoint has an active [custom domain](https://docs.raily.ai/features/custom-domains.md), the card shows the agent URL on that domain, plus a **Default agent URL (always works)** line. Both reach the same endpoint.

## Sign-in

A2A uses the same credentials as the rest of the endpoint:

* An API key (`rly_...`) that covers this endpoint, sent as `Authorization: Bearer` or in `X-API-Key`.
* An OAuth access token from the endpoint's sign-in, sent as `Authorization: Bearer`.

Most A2A platforms take an API key. A request with no valid credentials gets `401`. The agent card itself is public, so platforms can read it before they authenticate.

## Skills

The agent card lists the skills your endpoint offers:

* **Search** is always the default skill. Every message without a skill selection runs it, which covers all chat platforms.
* **Summary** appears when the endpoint also has a summary tool. It returns a written overview of what your content covers, plus the same overview as typed data. The message still needs some text, but the summary ignores it.

A client that can attach metadata selects a skill by its id from the agent card, with `"skill": "<id>"` in the message or request metadata. An unknown id is rejected.

## Try it with curl

Fetch the agent card:

```bash theme={null}
curl https://endpoints.app.raily.ai/t/your-workspace/123/.well-known/agent-card.json
```

The card names the endpoint, lists `supportedInterfaces` (the agent URL for versions `1.0` and `0.3`), the `skills`, and the accepted credentials.

Send a message with A2A v1.0 (`SendMessage`):

```bash theme={null}
curl https://endpoints.app.raily.ai/t/your-workspace/123/a2a \
  -H "Authorization: Bearer $RAILY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "m1",
        "role": "ROLE_USER",
        "parts": [{ "text": "What changed in the 2025 policy?" }]
      }
    }
  }'
```

A v0.3 client sends the same request with `"method": "message/send"`, `"role": "user"`, and parts in the form `{ "kind": "text", "text": "..." }`. You can send the key in `X-API-Key` instead:

```bash theme={null}
curl https://endpoints.app.raily.ai/t/your-workspace/123/a2a \
  -H "X-API-Key: $RAILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "message/send",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "m2",
        "role": "user",
        "parts": [{ "kind": "text", "text": "What changed in the 2025 policy?" }]
      }
    }
  }'
```

To run a different skill, add metadata to the message:

```json theme={null}
"message": {
  "messageId": "m3",
  "role": "ROLE_USER",
  "parts": [{ "text": "What does this archive cover?" }],
  "metadata": { "skill": "<skill id from the agent card>" }
}
```

## What comes back

The reply is one message with two parts:

* A **text** part with the readable answer, the same text an AI agent would see.
* A **data** part (`application/json`) with typed results under `results`. Each result has the same shape as an SDK search result: `id`, `score`, `text`, `fields`, and links where your content has them.

Both parts arrive whether you sign in with an API key or OAuth. To get only one, set `acceptedOutputModes` in the request's `configuration` to `["text/plain"]` or `["application/json"]`.

Every reply is a direct message. Raily does not create long-running tasks or send push notifications.

Calls over A2A appear in the endpoint's activity like any other call. On **Access Overview**, the **Protocols** card counts them under **A2A**.

## Next steps

> [card] [Search from your app](https://docs.raily.ai/connect/sdk.md)
>
> Call an endpoint with an API key

> [card] [Deep research](https://docs.raily.ai/features/deep-research.md)
>
> Give agents multi-step research


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