# A2A — the Agent2Agent protocol

A2A is a protocol for one autonomous agent to discover another and ask it something in natural language, over JSON-RPC. Version 1.0.0 publishes a card at `/.well-known/agent-card.json` describing the agent's skills. Connect implements it at `POST /a2a` with five public documentation skills and no authenticated extended card.

- **Status:** Reference
- **Audience:** developer
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/protocols/a2a/

## What A2A is for, and what MCP is for

The two protocols are often presented as rivals, which misreads both. MCP connects a *client* to *capabilities*: a model client holds the connection, reads a list of tools and calls them with arguments it constructs. A2A connects an *agent* to *another agent*: the caller does not know the callee's internals, does not construct a function call, and asks a question in words that the callee's own reasoning answers.

|  | MCP | A2A |
|---|---|---|
| Caller | A model client | Another agent |
| Unit of work | A named tool with typed arguments | A message in natural language |
| Discovery | The client is configured with a URL | A card at a well-known URI |
| Who reasons | The caller | Both ends |
| Connect's endpoint | `POST /mcp` | `POST /a2a` |

A useful test: if you already know which function you want, you want MCP. If you have a question and are looking for someone able to answer it, you want A2A. Connect offers both, over the same documentation corpus, so the answers cannot diverge.

## The exchange, end to end

1. Fetch `/.well-known/agent-card.json` from the domain you are interested in.
   - Result: A JSON document naming the agent, its protocol version, the URL to send messages to, its declared capabilities and its skills.
2. POST a JSON-RPC `message/send` to the URL the card gives, with a message whose `parts` contain a text part.
   - Result: A result of kind `message`, role `agent`, carrying reply parts and a `contextId` you can quote on a follow-up.
3. Name a `skillId` from the card if you know which skill you want.
   - Result: That skill answers. Omit it and Connect chooses from the shape of the question, because an agent that arrived via a well-known URI often has not read the skill list.

```http
POST /a2a HTTP/1.1
Host: connectbyjbrh.com
Content-Type: application/json

{"jsonrpc":"2.0","id":"7","method":"message/send",
 "params":{"skillId":"describe-capability",
           "message":{"parts":[{"kind":"text",
                                "text":"Can Connect record a phone call?"}]}}}
```

A reply carries a text part and, where there is something structured worth handing to a program, a data part beside it — the page URL, the status word, the other candidate pages. `metadata` names the skill that answered and the documentation root the answer came from, so a caller can audit which surface produced what.

## Does Connect use A2A?

Yes, as a server, in production. Protocol version 1.0.0; the card lives at `/.well-known/agent-card.json` and the endpoint is `POST /a2a`. Five skills are published and every one reads the generated public documentation: `explain-connect` answers a question from the closest page, `search-connect-docs` returns matching pages, `describe-capability` reports the status vocabulary and the status of the nearest documented capability, `explain-workflow` returns an end-to-end workflow page, and `explain-integration` answers from the protocol, developer and technology references.

**There is no authenticated extended card.** The card declares `supportsAuthenticatedExtendedCard: false`, and a call to `agent/getAuthenticatedExtendedCard` is answered with `-32004` and a sentence saying the public card is the whole advertised surface. Adding a private one would be a real decision about exposing workspace capability to other agents, and pretending it exists would be worse than not having it.

Streaming is not offered either. The card declares `streaming: false` and `message/stream` returns `-32004` pointing at `message/send`. Push notifications are likewise declared false. Every skill answers from generated files, so there is nothing to stream.

Connect is not an A2A *client*: it does not go out and call other agents' cards.

## Limits and refusals

| Condition | Answer |
|---|---|
| More than 60 requests a minute from one address | `429` |
| Body over 128 KB | `413`, before parsing |
| A method other than `message/send` or `tasks/send` | `-32601` |
| `message/stream` | `-32004` — the card declares streaming false |
| `agent/getAuthenticatedExtendedCard` | `-32004` — no such card exists |
| A `skillId` not on the card | `-32004`, listing the five real ones |
| A message with no text part | `-32602` |

One thing worth planning for: this endpoint answers about the public documentation, so a question about a specific business's mail, calls or customers has no useful answer here and will come back as documentation about that subject. That is not a failure to be retried — it is the boundary of the surface.

## Questions

### Do I have to read the card before sending a message?

You should, because the card names the URL and the skills. But Connect does not require it: a message with no `skillId` is routed by the shape of the question, which is a deliberate concession to agents that found the well-known URI and went straight to it.

### Can another agent do anything to my workspace over A2A?

No. Every skill reads the generated public documentation, holds no session and touches no workspace. There is no authenticated variant of this endpoint and no credential that would unlock one.

### Is A2A a replacement for an API?

No, and treating it as one produces a slow, vague API. A2A is for the case where the caller does not know the shape of the answer in advance. When you do know it, [the public API](/developers/public-api/) or the MCP tools give you typed results without a natural-language round trip.

## Related

- [The A2A Agent Card](https://connectbyjbrh.com/docs/protocols/agent-card/)
- [A2A agent discovery](https://connectbyjbrh.com/docs/protocols/a2a-discovery/)
- [Model Context Protocol](https://connectbyjbrh.com/docs/protocols/mcp/)
- [Interoperating over A2A](https://connectbyjbrh.com/developers/a2a-integration/)
- [JSON-RPC 2.0](https://connectbyjbrh.com/docs/protocols/json-rpc/)

## What this page is based on

- https://a2a-protocol.org/latest/specification/
- `backend/app/a2a_server.py` — SKILLS, the routing table and the refusals
- `docs-source/facts.py` — PROTOCOLS['a2a'], re-verified 2026-09-10