Extensions in A2A

The A2A protocol provides a strong foundation for inter-agent communication. But specific domains and advanced use cases often need additional structure, custom data, or new interaction patterns beyond the generic methods. Extensions are A2A’s mechanism for layering new capabilities onto the base protocol.

Extensions can add new data, requirements, RPC methods, and state machines to A2A. Agents declare support for specific extensions in their Agent Card, and clients can opt in to the behavior an extension offers as part of requests to the agent. Extensions are identified by a URI and defined by their own specification. Anyone can define, publish, and implement an extension.

This flexibility allows A2A to be customized without fragmenting the core standard, fostering innovation and domain-specific optimization.

Scope of extensions

The ways extensions can be used are intentionally broad, so A2A can expand beyond known use cases. Foreseeable applications include:

• Data-only extensions: Expose new structured information in the Agent Card that does not affect the request-response flow. For example, an extension could add structured data about an agent’s GDPR compliance.
• Profile extensions: Overlay additional structure and state-change requirements on the core request-response messages. This acts as a profile of the core A2A protocol, narrowing the space of allowed values (for example requiring structured Part.data values to follow a specific schema). It can also augment existing states in the task state machine through metadata. For example, an extension could define a “generating-image” substate when TaskStatus.state is working and TaskStatus.message.metadata["generating-image"] is true.
• Method extensions (extended skills): Add entirely new RPC methods beyond the core set. An extended skill is a capability an agent gains or exposes through an extension that defines new RPC methods. For example, a task-history extension might add a tasks/search RPC method to retrieve a list of previous tasks, effectively giving the agent a new skill.
• State machine extensions: Add new states or transitions to the task state machine.

Example extensions

Extension governance

The A2A organization uses a formal governance framework for how extensions are proposed, developed, promoted, and maintained. Official extensions use the https://a2a-protocol.org/extensions/ URI prefix and are hosted under the a2aproject organization with the ext- repository prefix (experimental extensions use experimental-ext-).

For the full governance process, including tiers, lifecycle, SDK support, and legal requirements, see Extension and Protocol Binding Governance .

Limitations

Some protocol changes are not allowed through extensions, mainly to avoid breaking core type validation:

• Changing the definition of core data structures: for example adding new fields to, or removing required fields from, protocol-defined data structures. Extensions should place custom attributes in the metadata map that core data structures already carry.
• Adding new values to enum types: extensions should use existing enum values and annotate additional meaning in the metadata field.

Extension declaration

Agents declare support for extensions in their Agent Card by including AgentExtension objects in the AgentCapabilities object. AgentExtension has these fields:

Here is an example Agent Card with an extension:

{
  "name": "Magic 8-ball",
  "description": "An agent that can tell your future... maybe.",
  "version": "0.1.0",
  "supportedInterfaces": [
    {
      "url": "https://example.com/agents/eightball",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "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",
            "You might deny it, but we've seen the evidence of those cows."
          ]
        }
      }
    ]
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "fortune",
      "name": "Fortune teller",
      "description": "Seek advice from the mystical magic 8-ball",
      "tags": ["mystical", "untrustworthy"]
    }
  ]
}

Required extensions

Extensions usually offer optional functionality, but some agents have stricter requirements. When an Agent Card declares an extension as required: true, it tells clients that some aspect of the extension affects how requests are structured or processed, and that the client must abide by it. Agents should not mark data-only extensions as required. If a client does not request activation of a required extension, or fails to follow its protocol, the agent should reject the request with an appropriate error.

Extension specification

An extension’s detailed behavior and structure are defined by its specification. The format is not mandated, but it should contain at least:

• The specific URI(s) identifying the extension.
• The schema and meaning of objects specified in the params field of the AgentExtension object.
• Schemas of any additional data structures exchanged between client and agent.
• Details of new request-response flows, additional endpoints, or any other logic needed to implement the extension.

Extension dependencies

Extensions can depend on other extensions, either as a required dependency (the extension cannot function without it) or an optional one (extra functionality is enabled if another extension is present). Extension specifications should document these dependencies. The client is responsible for activating an extension and all its required dependencies as listed in the extension’s specification.

Extension activation

Extensions are inactive by default, giving extension-unaware clients a baseline experience. Clients and agents negotiate which extensions are active for a given request:

1. Client request: The client requests activation by including the A2A-Extensions header in the HTTP request to the agent. Its value is a comma-separated list of the extension URIs the client intends to activate.
2. Agent processing: The agent identifies the supported extensions in the request and performs the activation. Requested extensions the agent does not support can be ignored.
3. Response: Once the agent has identified all activated extensions, the response should include the A2A-Extensions header listing every extension successfully activated for that request.

In sequence: the client reads the extensions declared in the Agent Card, sends its chosen extension URIs in the request header, the server checks which of them it has registered and activates them, and finally returns the activated extension data in its response.

Example request showing extension activation:

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

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

Corresponding response echoing the activated extensions:

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

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

Implementation considerations

The A2A protocol defines what extensions can do; this section gives guidance on implementing them: best practice for authoring, versioning, and distributing extension implementations.

• Versioning: Extension specifications evolve, so a clear versioning strategy is needed to let clients and agents negotiate compatible implementations.
  • Recommendation: use the extension’s URI as the primary version identifier, ideally with a version number (for example https://example.com/ext/my-extension/v1).
  • Breaking changes: a new URI must be used when introducing a breaking change to an extension’s logic, data structures, or required parameters.
  • Handling mismatches: if a client requests a version the agent does not support, the agent should ignore the activation request for that extension; it must not fall back to a different version.
• Discoverability and publication:
  • Specification hosting: the extension specification document should be hosted at the extension’s URI.
  • Permanent identifiers: authors are encouraged to use a permanent identifier service such as w3id.org for extension URIs to prevent broken links.
  • Community registry: A2A’s extension governance framework defines a tiered system for official and experimental extensions hosted under the a2aproject organization, including a lifecycle for proposing and promoting extensions.
• Packaging and reusability (A2A SDKs and libraries): To promote adoption, extension logic should be packaged into reusable libraries that integrate into existing A2A client and server applications. An extension implementation should be distributed as a standard package for its language ecosystem (a PyPI package for Python, an npm package for TypeScript/JavaScript). A well-designed extension package lets a developer add it to a server with minimal code.
• Security: Extensions modify the core behavior of the A2A protocol and therefore introduce new security considerations:
  • Input validation: any new data fields, parameters, or methods introduced by an extension must be rigorously validated. Treat all extension-related data from an external party as untrusted input.
  • Scope of required extensions: be careful when marking an extension required: true. It creates a hard dependency for all clients and should be used only for extensions fundamental to the agent’s core function and security (a message signing extension, for example).
  • Authentication and authorization: if an extension adds new methods, the implementation must ensure they are subject to the same authentication and authorization checks as core A2A methods. An extension must not provide a way to bypass the agent’s primary security controls.

For more, see the Google Developers Blog post A2A Extensions: Empowering Custom Agent Functionality .

Diagnose an extension that appears to be ignored

Compare three separate facts: the URI advertised by the card, the exact URI requested for this call, and the server’s activation response. A declaration alone does not activate an extension. A header requesting v2 does not prove the server accepted it, and an unsupported optional version should not silently be treated as v1.

If the extension is required and your client cannot implement it, reject the integration before submitting business work. If you receive ExtensionSupportRequiredError, inspect the required URI and its dependencies rather than retrying an unchanged request. Adding an arbitrary metadata key is insufficient when the extension specifies validation, signatures, or extra request steps.

Test the base request, the supported extension, an unknown optional URI, and a missing required extension separately. Keep custom metadata parsing within the extension handler so it cannot accidentally bypass the base request’s authentication or change a core enum. These are implementation review cases; they do not claim that the example agent on this page has been run by this site.

Source: Official A2A documentation: Extensions