Skip to content

remove a2a extension activation entirely in v1.0 #2033

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wrenj wants to merge 1 commit into
base: main
Choose a base branch
from
+5 −58
Open

remove a2a extension activation entirely in v1.0 #2033

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions specification/v1_0/docs/evolution_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ Version 1.0 differs from 0.9 in the following ways:

### 2.6. Agent card and transport metadata

- Removed the A2A extension activation mechanism entirely. Clients and agents now rely purely on A2A metadata to negotiate supported A2UI version and catalogs.

@gemini-code-assist gemini-code-assist Bot Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Grammar/phrasing suggestion: "negotiate supported A2UI version and catalogs" should be "negotiate the supported A2UI version and catalogs" or "negotiate supported A2UI versions and catalogs" for proper parallel structure and article usage.

- Standardized the official MIME type to `application/a2ui+json` to conform to IANA media type guidelines.
- Updated capabilities namespace in transport metadata and A2A metadata parameters from `v0.9`/`v0.9.1` to `v1.0`.

Expand All @@ -79,6 +80,7 @@ This section outlines the steps required to migrate existing applications and co

### For agents and servers

- Stop parsing or requiring the A2A extension activation header (e.g., `X-A2A-Extensions`). Use A2A metadata for capability negotiation instead.

@gemini-code-assist gemini-code-assist Bot Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

While the evolution guide correctly instructs agents to stop parsing or requiring the A2A extension activation header, the Python SDK implementation in agent_sdks/python/a2ui_agent/src/a2ui/a2a/extension.py still contains the activation logic (such as try_activate_a2ui_extension and its helper functions). Please ensure the Python SDK implementation is updated or removed to align with this specification change.

- Set the `version` field in all streamed JSON envelopes to `"v1.0"`.
- Change the MIME type of A2UI payloads in transport layers from `application/json+a2ui` to `application/a2ui+json`.
- Rename the `theme` field in `createSurface` messages to `surfaceProperties` and remove `primaryColor`. You can also pass initial `components` and `dataModel` directly in the `createSurface` payload.
Expand All @@ -91,6 +93,7 @@ This section outlines the steps required to migrate existing applications and co

### For renderers and clients

- Stop sending the A2A extension activation header (e.g., `X-A2A-Extensions`). Use A2A metadata for capability negotiation instead.
- Implement function execution by adding support for parsing `callFunction` messages, checking boundary definitions in the catalog (`callableFrom`), rejecting invalid calls with `INVALID_FUNCTION_CALL`, and returning `functionResponse` messages.
- Support synchronous action responses by generating `actionId` for actions with `wantResponse: true` and writing returned values from `actionResponse` messages into the data model.
- Support simultaneous version handling during session initialization by inspecting the `version` property (e.g., `"v1.0"`) to route payloads to version-specific controllers.
Expand Down
60 changes: 2 additions & 58 deletions specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

This document is intended for developers implementing the A2UI A2A extension. The extension adds A2UI v1.0 support to A2A, a format for agents to send streaming, interactive user interfaces to clients.

Note that A2UI extension activation is optional as clients and agents can negotiate A2UI support using A2A `message.metadata["a2uiClientCapabilities"]` which is attached to every A2A message from the client and contains the supported protocol version and catalogs. Agents advertising A2UI support in their AgentCard is encouraged as clients may rely on it to determine if they should send `message.metadata["a2uiClientCapabilities"]`, however it is not explicitly required.
A2UI does not use A2A extension activation, and only uses the AgentCard part of A2A Extensions. Clients and agents negotiate supported A2UI version and catalogs using A2A `message.metadata["a2uiClientCapabilities"]` which is attached to every A2A message from the client. Agents advertising A2UI support in their AgentCard is encouraged as clients may rely on it to determine if they should send `message.metadata["a2uiClientCapabilities"]`, however it is not explicitly required.

@gemini-code-assist gemini-code-assist Bot Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

There is a minor grammatical/phrasing issue in this line:

  • "negotiate supported A2UI version and catalogs" should be "negotiate the supported A2UI version and catalogs" or "negotiate supported A2UI versions and catalogs".
  • "Agents advertising A2UI support in their AgentCard is encouraged" has a subject-verb agreement issue. It should be "Advertising A2UI support in the AgentCard is encouraged" or "Agents are encouraged to advertise A2UI support in their AgentCard".
  • "however it is not explicitly required" should have a semicolon or comma before/after "however".

Suggested Phrasing:

A2UI does not use A2A extension activation, and only uses the AgentCard part of A2A Extensions. Clients and agents negotiate the supported A2UI version and catalogs using A2A `message.metadata['a2uiClientCapabilities']` which is attached to every A2A message from the client. Advertising A2UI support in the AgentCard is encouraged as clients may rely on it to determine if they should send `message.metadata['a2uiClientCapabilities']`; however, it is not explicitly required.

Additionally, please clarify in the documentation that the client determines a function's execution boundary (e.g., clientOnly status) at runtime by reading its configuration from the active catalog definition.

References
  1. In A2UI protocol documentation and implementation, clarify that the client determines a function's execution boundary (e.g., clientOnly status) at runtime by reading its configuration from the active catalog definition.


## Extension URI

Expand Down Expand Up @@ -48,63 +48,7 @@ The `params` object corresponds to the `v1.0` object in the `server_capabilities

## A2A Extension activation

Activating the A2UI extension is optional. Clients and agents can negotiate A2UI support using `message.metadata["a2uiClientCapabilities"]` A2A `DataPart.data.metadata["mimeType"] = "application/a2ui+json"`.

Specifically:

- If a client includes `message.metadata["a2uiClientCapabilities"]`, the agent can use this object to determine the supported A2UI protocol version and catalogs.
- If an agent returns A2A A2A `DataPart.data.metadata["mimeType"] = "application/a2ui+json"`, the client knows the payload contains A2UI messages.

While explicit activation is not required, clients can still explicitly activate the extension using the transport-defined A2A extension activation mechanism. The [A2A Extensions Guide](https://a2a-protocol.org/latest/topics/extensions/) defines this process.

Note: You should not use `accepted_output_modes: ['a2ui']` (which is not an A2UI standard) to trigger A2UI.

### JSON-RPC and HTTP transports

To activate the A2UI A2A Extension, the `X-A2A-Extensions` HTTP header includes the extension URI.

**Example HTTP `SendMessageRequest`:**

```http
POST /v1/messages HTTP/1.1
Host: agent.example.com
X-A2A-Extensions: https://a2ui.org/a2a-extension/a2ui/v1.0
Content-Type: application/json

{
"message": {
"parts": [
{
"text": "Hello, show me the dashboard"
}
]
}
}
```

To see how the agent parses the extension URI, see [`extension.py`](../../../../../agent_sdks/python/a2ui_agent/src/a2ui/a2a/extension.py).

### GRPC transport

To activate the A2UI A2A Extension, the client adds the extension URI to A2A `sendMessageParams.metadata["X-A2A-Extensions"]`.

**Example gRPC `SendMessageRequest`:**

```json
{
"metadata": {
"X-A2A-Extensions": "https://a2ui.org/a2a-extension/a2ui/v1.0"
},
"message": {
"parts": [
{
"text": "Hello, show me the dashboard"
}
]
}
}
}
```
A2UI does not use A2A extension activation. Clients advertise supported A2UI version and catalogs by attaching `message.metadata["a2uiClientCapabilities"]` to their messages. Agents use A2UI by sending payloads with `DataPart.data.metadata["mimeType"] = "application/a2ui+json"` to clients.

@gemini-code-assist gemini-code-assist Bot Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For better grammatical correctness, "Clients advertise supported A2UI version and catalogs" should be "Clients advertise the supported A2UI version and catalogs" or "Clients advertise supported A2UI versions and catalogs".

Suggested Phrasing:

A2UI does not use A2A extension activation. Clients advertise the supported A2UI version and catalogs by attaching `message.metadata['a2uiClientCapabilities']` to their messages. Agents use A2UI by sending payloads with `DataPart.data.metadata['mimeType'] = 'application/a2ui+json'` to clients.


## A2A Client to Server Metadata

Expand Down
Loading