A2A extension

An A2A extension is an addition to the core A2A protocol, identified by a URI and defined in its own specification, that an agent declares in its Agent Card and a client activates for a request. Extensions let a domain add data, rules or methods without changing the core standard, and anyone can define one.

Declaring. Agents list extensions in capabilities.extensions as AgentExtension objects with a uri, a description, a required flag and optional params for extension-specific configuration (a2a.proto).

Illustrative:

{
  "capabilities": {
    "streaming": false,
    "extensions": [
      {
        "uri": "https://example.com/extensions/geolocation/v1",
        "description": "Accepts the caller's location to rank nearby results",
        "required": false
      }
    ]
  }
}

Activating. Extensions are inactive by default. Over HTTP-based bindings the client sends an A2A-Extensions header with a comma-separated list of extension URIs, and gRPC carries the same value as metadata (section 3.2.6). The Extensions guide says the agent should echo the extensions it activated in its response. Extension data travels in the metadata maps of messages and artifacts, keyed by the extension URI, and those objects list the URI in their extensions field (section 4.6.2).

Required extensions. If a card marks an extension required: true and the client does not declare support for it, the agent must return ExtensionSupportRequiredError, JSON-RPC code -32008 (section 3.3.4).

Versioning. The URI should include a version, and a breaking change must use a new URI. If a client asks for a version the agent does not support, the agent should ignore it unless the extension is required, and must not fall back to an older version (section 4.6.3).

Scope and limits. The Extensions guide describes data-only, profile and method extensions. Extensions should not change core data structures or add enum values; extra meaning goes in metadata. Official extensions use the https://a2a-protocol.org/extensions/ URI prefix. The core specification also points to extensions as one place to define what it leaves open, such as the meaning of a credential obtained under TASK_STATE_AUTH_REQUIRED.