> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# What Are Extensions?

> How A2A extensions are defined, activated, and used across the protocol.

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](https://a2a-protocol.org/latest/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

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

### 2) Activating an extension for a request

```http theme={null}
POST /message:send HTTP/1.1
Host: agent.example.com
Content-Type: application/json
A2A-Extensions: https://docs.aion.to/a2a/extensions/aion/event/1.0.0

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

### 3) Annotating artifacts

```json theme={null}
{
  "artifactId": "summary-001",
  "parts": [{"text": "Summary with references."}],
  "extensions": ["https://docs.aion.to/a2a/extensions/aion/event/1.0.0"],
  "metadata": {
    "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
      "schema": "https://docs.aion.to/a2a/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`.