A2A-Extensions header

A2A-Extensions is the HTTP request and response header, and in gRPC the a2a-extensions metadata key, that carries a comma-separated list of A2A extension URIs: the ones a client wants to activate on a request, and in the response the ones the agent activated.

Why it exists. Extensions are inactive by default, so a client that knows nothing about them gets the plain protocol. A client opts in per request by naming each extension’s URI in this header.

Negotiation.

1. The agent declares what it supports in the Agent Card, under capabilities.extensions, each with a uri and a required flag.
2. The client sends A2A-Extensions with the URIs it wants.
3. The agent activates the ones it supports and ignores the rest. If the card marks an extension required and the client does not declare support for it, the agent returns ExtensionSupportRequiredError (JSON-RPC -32008).
4. The agent’s response should include A2A-Extensions listing the extensions it actually activated.

Extension data then travels in the payload. A Message or Artifact names the extensions it uses in its extensions list and carries their data in metadata, keyed by the extension URI. Request headers trimmed from the specification’s example:

POST /message:send HTTP/1.1
Host: agent.example.com
Content-Type: application/a2a+json
A2A-Extensions: https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1

Versions. An extension should carry its version in its URI, and a breaking change needs a new URI. If a client asks for a version the agent does not support, the agent should ignore it for that request. If the extension is required, the agent must return an error instead. Either way, it must not fall back to an older version on its own. The v0.3 documentation named this header X-A2A-Extensions. Version 1.0 dropped the X- prefix and gave every A2A service parameter an a2a- prefix instead.

Neighbouring terms. An A2A extension is the thing being activated. A2A-Version is the other standard service parameter.