A2A agent cards

The Agent-to-Agent (A2A) protocol lets an autonomous agent find another autonomous agent and call it over JSON-RPC. Discovery hinges on a single well-known file: /.well-known/agent-card.json. Relevant whenever your service exposes agentic behaviour another agent might want to delegate to.

What it is #

The Agent-to-Agent (A2A) protocol is an open standard for one autonomous agent to discover and call another. It was originally proposed by Google in 2025 and donated to the Linux Foundation later that year. It complements the Model Context Protocol: MCP exposes tools an LLM can call; A2A exposes a whole agent another agent can delegate to.

Discovery is deliberately small. An A2A-speaking service hosts a JSON manifest at the well-known URI /.well-known/agent-card.json. The manifest is the agent card — a self-describing document that names the agent, lists its skills, declares its capabilities, and points at one or more transport endpoints that speak the A2A wire protocol (JSON-RPC, gRPC, or HTTP+JSON).

The minimum field set is small and stable. Required fields per the spec are name, description, version, supportedInterfaces (each with url, protocolBinding, protocolVersion), capabilities, defaultInputModes, defaultOutputModes, and skills (each with id, name, description, tags). Optional fields cover provider, documentation URL, security schemes, JWS signatures, and an icon URL.

The card’s version is the version of your agent, not of the protocol. Since 1.0 the protocol version lives on each entry in supportedInterfaces, because one card can now offer several interfaces speaking different protocol versions. There is no top-level protocolVersion any more, and a card that still carries one is following a 0.3-era example.

This site ships such a card as a worked example. The static manifest is at /.well-known/agent-card.json; the JSON-RPC endpoint is at mcp.specification.website/a2a/v1. It is intentionally minimal — one send-message method, no streaming, no task lifecycle — and it wraps the same search and topic-fetch logic the MCP server already exposes. It is not yet fully in line with 1.0: the endpoint answers the pre-1.0 method name message/send rather than SendMessage, and the card still carries a top-level protocolVersion next to the per-interface one.

Why it matters #

• An agent card is the standard way for a calling agent to learn what you do, before any call is made. Without it, the calling agent has to be hard-coded against your service or guess from a UI.
• A2A is transport-agnostic: a single card can advertise JSON-RPC, gRPC, and HTTP+JSON endpoints in priority order. Clients pick the binding they support.
• It composes cleanly with MCP. An MCP server gives an LLM tools; an A2A card lets that whole LLM-plus-tools agent be reached by other agents. The two protocols are not alternatives.
• The card is a contract. Treat changes to skills[].id ,supportedInterfaces[].url , orcapabilities as breaking, and bumpversion accordingly.

Adoption is early but accelerating. The protocol reached version 1.0 in March 2026. Treat A2A as optional for now — useful if your product is itself an agent or wraps one, overkill if it is a static brochure.

How to implement #

• Build the card. Author a JSON document withname ,description ,version ,provider ,supportedInterfaces (each declaring its ownurl ,protocolBinding andprotocolVersion ),capabilities ,defaultInputModes ,defaultOutputModes , andskills . Use theA2A specification as the field reference. Use camelCase keys throughout.
• Pick a transport. JSON-RPC over HTTPS is the lowest-friction option and is what we ship here. gRPC is appropriate when you already speak gRPC; HTTP+JSON when you have an existing REST surface to wrap.
• Serve it at the canonical URI. PerRFC 8615 , publish at/.well-known/agent-card.json withContent-Type: application/json and a sensibleCache-Control (an hour is fine; ETag is better).
• Advertise it. Add aLink: </.well-known/agent-card.json>; rel="service-desc"; type="application/json" response header so clients can discover the card without guessing the path. Add the same link to your/.well-known/api-catalog Linkset entry. SeeHTTP Link headers .
• Ship the endpoint behind it. Do not publish a card that points at a non-existent URL. The first call most validators make is to the endpoint; a 404 there is worse than no card at all. At minimum, implement theSendMessage JSON-RPC method and return method-not-found for the rest.
• Migrate the whole wire format. Version 1.0 renamed JSON-RPC methods:message/send becameSendMessage ,message/stream becameSendStreamingMessage , andtasks/get becameGetTask . It also changed payloads: message roles useROLE_USER andROLE_AGENT , and parts are identified by their fields instead of akind discriminator. Follow the1.0 migration guide for the request, response and agent-card changes. Method aliases alone do not preserve 0.3 compatibility. If you retain 0.3 clients, serve discovery cards and wire formats those clients understand, using a separate endpoint or a version-aware compatibility layer that parses and emits the appropriate format; advertise only versions each interface actually implements.
• Be honest about capabilities. If you do not support streaming, setcapabilities.streaming tofalse . The same goes forpushNotifications andextendedAgentCard . Lying here breaks clients that probe before they call.
• Sign the card if you care about provenance. A2A allows JWS signatures (signatures[] ); useful in curated registries, optional for direct discovery.

Common mistakes #

• Publishing a card that points at a URL that 404s. Discovery validators check the URI; runtime agents check the endpoint. Both matter.
• Mixing up agent-card.json withagent.json . The canonical filename isagent-card.json — pick it, do not invent a redirect.
• Claiming capabilities you do not implement. Setting streaming: true without a workingSendStreamingMessage method is a contract violation, not a polite overstatement.
• Declaring protocolVersion`` 1.0 while answering 0.3 method names. Many early examples and tutorials predate 1.0, so code copied from them answersmessage/send ; a strict 1.0 client sendsSendMessage and gets method-not-found.
• Treating the card as static when the agent evolves. Every change to skills or transports needs a version bump.
• Forgetting the Content-Type . A card served astext/plain will be rejected by stricter clients. Serve it asapplication/json .

Verification #

• curl https://your-site.example/.well-known/agent-card.json returns 200 withContent-Type: application/json and parses as JSON.
• The JSON validates against the A2A schema for each interface’s protocolVersion . Required fields are present;supportedInterfaces[0].url resolves;skills are non-empty.
• curl -X POST againstsupportedInterfaces[0].url with a minimal JSON-RPC body using the method name for that interface’s version (SendMessage for 1.0) returns a JSON-RPC response (not an HTML error page).
• The card appears in your /.well-known/api-catalog Linkset and in theLink response header on/ .
• A live test: connect the agent from a second A2A-speaking client and confirm at least one skill round-trips end-to-end.

Related topics #

Sources & further reading #

- [A2A Protocol — Specification](https://a2a-protocol.org/latest/specification/) — A2A Project (Linux Foundation)
- [A2A Protocol — Agent Discovery](https://a2a-protocol.org/latest/topics/agent-discovery/) — A2A Project (Linux Foundation)
- [A2A Protocol — What's new in v1.0](https://a2a-protocol.org/latest/whats-new-v1/) — A2A Project (Linux Foundation)
- [RFC 8615 — Well-Known URIs](https://www.rfc-editor.org/rfc/rfc8615) — IETF