Skip to main content
Extensions are the A2A mechanism for layering new capabilities onto the base protocol without fragmenting it. They can introduce new data, requirements, RPC methods, and even state-machine changes. Extensions are identified by a URI and defined by their own specification. Agents declare supported extensions in their Agent Card, and clients opt in per request. For the full A2A Protocol Reference, see the A2A Protocol Specification.

​
Extension Types

The A2A documentation highlights four common patterns you’ll see in the wild:
  • Data-only extensions: expose structured data in the Agent Card without altering request/response flow.
  • Profile extensions: constrain or enrich existing message/task semantics (for example, requiring specific DataPart schemas or metadata-based sub-states).
  • Method extensions (extended skills): add new RPC methods beyond the core protocol.
  • State machine extensions: add new states or transitions to the task state machine.

​
Where Extensions Are Used in the Protocol

Extensions plug into A2A in a few standardized places:
  1. Agent Card declaration: Agents list AgentExtension entries inside AgentCapabilities.extensions, including a URI, description, and whether it is required.
  2. Request activation (service parameters): Clients indicate which extensions they want to use via the A2A-Extensions service parameter (e.g., an HTTP header with a comma-separated list of URIs).
  3. Message extensions: Messages can include an extensions list and extension-specific metadata. This allows strongly typed context on message sends and on TaskStatus messages.
  4. Artifact extensions: Artifacts can also include an extensions list and extension-specific metadata to describe generated content.
Extensions are also the recommended way to strongly type metadata values.

​
Activation and Negotiation

Extensions are off by default. A client activates them per request (for HTTP bindings, this is the A2A-Extensions header). Agents activate the subset they support and should echo the activated set in the response. Unsupported extensions can be ignored for that request. If an agent marks an extension as required, clients must activate and follow it; otherwise the agent should reject the request.

​
Versioning and Compatibility

  • Extension URIs should include a version identifier.
  • Breaking changes require a new URI.
  • If an unsupported version is requested, the agent should ignore it unless the extension is required, and it must not silently fall back to another version.

​
Limits and Design Rules

Extensions must not change core data structures or add new enum values. Put additional attributes in metadata and annotate semantics there. Extension specs should document:
  • The canonical URI(s)
  • Schemas for AgentExtension.params
  • Schemas for any extension data passed in messages or artifacts
  • New RPC methods or request/response flows (if any)
  • Dependencies on other extensions (and whether they are required)

​
Idiomatic Usage Patterns (Examples)

​
1) Declaring support in the Agent Card

{
  "name": "Aion Distribution Agent",
  "description": "Routes messages to external networks",
  "version": "1.0.0",
  "capabilities": {
    "extensions": [
      {
        "uri": "https://docs.aion.to/extensions/aion/distribution/1.0.0",
        "description": "A2A Distribution integration",
        "required": false,
        "params": {
          "networks": ["email", "telegram"]
        }
      }
    ]
  }
}

​
2) Activating an extension for a request

POST /message:send HTTP/1.1
Host: agent.example.com
Content-Type: application/json
A2A-Extensions: https://docs.aion.to/extensions/aion/event/1.0.0

{
  "message": {
    "role": "user",
    "parts": [{"text": "Send a notification"}],
    "extensions": ["https://docs.aion.to/extensions/aion/event/1.0.0"],
    "metadata": {
      "https://docs.aion.to/extensions/aion/event/1.0.0": {
        "type": "to.aion.notifications.1.0.0",
        "source": "aion://distributions/demo",
        "id": "evt_123"
      }
    }
  }
}

​
3) Annotating artifacts

{
  "artifactId": "summary-001",
  "parts": [{"text": "Summary with references."}],
  "extensions": ["https://docs.aion.to/extensions/aion/event/1.0.0"],
  "metadata": {
    "https://docs.aion.to/extensions/aion/event/1.0.0": {
      "schema": "https://docs.aion.to/extensions/aion/event/1.0.0#Sources"
    }
  }
}

​
4) Profile-style metadata on TaskStatus

Profile extensions often express “sub-states” or stricter semantics by adding metadata to the TaskStatus.message.