Extensions

Extensions in A2A

A2A defines a strong, interoperable baseline for agent-to-agent communication. For domain-specific requirements or advanced interaction patterns, A2A supports extensions: an opt-in mechanism to layer additional capabilities on top of the base protocol without fragmenting the core standard.

Extensions can introduce new structured data, request requirements, optional RPC methods, or additional state machine semantics. An extension is identified by a URI and defined by its own specification.

Common extension scopes

• Data-only extensions: add structured metadata (e.g. compliance attributes) without changing request flow.
• Profile extensions: impose stricter structure on messages (e.g. require DataPart with a specific schema).
• Method extensions (extended skills): add new RPC methods beyond the core set.
• State machine extensions: refine or annotate task states via metadata.

Limitations

To preserve core compatibility, extensions should not:

• change core object schemas (use metadata for custom fields),
• add new enum values (use metadata to convey additional semantics).

Declaring extensions

Agents declare supported extensions in their AgentCard capabilities. Example:

{
  "name": "Magic 8-ball",
  "description": "An agent that can tell your future... maybe.",
  "version": "0.1.0",
  "url": "https://example.com/agents/eightball",
  "capabilities": {
    "streaming": true,
    "extensions": [
      {
        "uri": "https://example.com/ext/konami-code/v1",
        "description": "Provide cheat codes to unlock new fortunes",
        "required": false,
        "params": {
          "hints": ["When your sims need extra cash fast"]
        }
      }
    ]
  }
}

Activating extensions

Clients opt in to extensions per request. One common pattern is an HTTP header listing activated extension URIs, plus extension-specific metadata in the request body.

Example request:

POST /agents/eightball HTTP/1.1
Host: example.com
Content-Type: application/json
X-A2A-Extensions: https://example.com/ext/konami-code/v1

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "1",
  "params": {
    "message": {
      "kind": "message",
      "messageId": "1",
      "role": "user",
      "parts": [{ "kind": "text", "text": "Oh magic 8-ball, will it rain today?" }]
    },
    "metadata": {
      "https://example.com/ext/konami-code/v1/code": "motherlode"
    }
  }
}

Example response echoing activated extensions:

HTTP/1.1 200 OK
Content-Type: application/json
X-A2A-Extensions: https://example.com/ext/konami-code/v1

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "kind": "message",
    "messageId": "2",
    "role": "agent",
    "parts": [{ "kind": "text", "text": "That's a bingo!" }]
  }
}

Required extensions

If an AgentCard marks an extension as required: true, clients must follow that extension’s rules (or the agent should reject requests). Avoid marking data-only extensions as required.

Implementation considerations

• Versioning: include a version in the URI and use a new URI for breaking changes.
• Publishing: host the extension specification at the URI when possible.
• Security: validate all extension-provided inputs and ensure extension methods are subject to the same authz/authn controls as core methods.