diff --git a/specification/v1_0/docs/evolution_guide.md b/specification/v1_0/docs/evolution_guide.md index 5cf4b05a18..b7e34eed0f 100644 --- a/specification/v1_0/docs/evolution_guide.md +++ b/specification/v1_0/docs/evolution_guide.md @@ -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 the supported A2UI version and catalogs. - 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`. @@ -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. - 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. @@ -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. diff --git a/specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md b/specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md index 7e061c4cca..e88c9f75f8 100644 --- a/specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md +++ b/specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md @@ -4,7 +4,8 @@ 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 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. + ## Extension URI @@ -48,63 +49,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 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