From dc04e6cbac78e823608761239306d34647bc8c7c Mon Sep 17 00:00:00 2001 From: wrenj Date: Fri, 5 Jun 2026 14:38:12 -0400 Subject: [PATCH 1/3] clarify a2uiClientCapabilities go in message metadata --- agent_sdks/python/agent_development.md | 2 +- docs/concepts/actions.md | 2 +- docs/guides/renderer-development.md | 2 +- specification/v0_10/docs/a2ui_protocol.md | 4 ++-- specification/v0_8/docs/a2ui_extension_specification.md | 2 +- specification/v0_8/docs/a2ui_protocol.md | 2 +- specification/v0_8/docs/custom_catalog_changes.md | 6 +++--- specification/v0_9_1/docs/a2ui_protocol.md | 4 ++-- 8 files changed, 12 insertions(+), 12 deletions(-) diff --git a/agent_sdks/python/agent_development.md b/agent_sdks/python/agent_development.md index de1bf06f54..0a4d7d4de8 100644 --- a/agent_sdks/python/agent_development.md +++ b/agent_sdks/python/agent_development.md @@ -400,7 +400,7 @@ agent_card = AgentCard( #### Setting or Propagating Client Capabilities on Remote A2A Agents -When calling remote A2A agents (such as delegating to a sub-agent or proxying to a backend A2A stubby agent) via ADK `RemoteA2aAgent`, you must ensure that the remote agent receives the client's UI capabilities in its request metadata under `a2uiClientCapabilities`. +When calling remote A2A agents (such as delegating to a sub-agent or proxying to a backend A2A stubby agent) via ADK `RemoteA2aAgent`, you must ensure that the remote agent receives the client's UI capabilities in the `metadata` field of the A2A `Message` under the key `a2uiClientCapabilities`. You can configure an `A2aRemoteAgentConfig` with a `before_request` interceptor (`RequestInterceptor`) to inject this metadata. There are two common scenarios: diff --git a/docs/concepts/actions.md b/docs/concepts/actions.md index 8edd257125..a829858c9a 100644 --- a/docs/concepts/actions.md +++ b/docs/concepts/actions.md @@ -231,7 +231,7 @@ Before an agent can safely send a UI, the renderer must advertise which componen ### Advertising Capabilities -Renderers include an `a2uiClientCapabilities` object in the **metadata** of their messages to the agent (e.g., in the `metadata` field of an A2A envelope). +Renderers include an `a2uiClientCapabilities` object in the **metadata** of their messages to the agent (e.g., in the `metadata` field of an A2A `Message`). ```json { diff --git a/docs/guides/renderer-development.md b/docs/guides/renderer-development.md index 6fd1cf763a..eb52f03cba 100644 --- a/docs/guides/renderer-development.md +++ b/docs/guides/renderer-development.md @@ -112,7 +112,7 @@ Implement the following communication features: - Resolve all data bindings within the `action.context` against the data model. - Send the complete `userAction` object to the server's event handling endpoint. - **Client Capabilities Reporting**: - - In **every** A2A message sent to the server (as part of the metadata), include an `a2uiClientCapabilities` object. + - In **every** A2A `Message`'s `metadata` field sent to the server, include an `a2uiClientCapabilities` object. - This object should declare the component catalog your client supports via `supportedCatalogIds` (e.g., including the URI for the standard 0.8 catalog). - Optionally, if the server supports it, provide `inlineCatalogs` for custom, on-the-fly component definitions. - **Error Reporting**: Implement a mechanism to send an `error` message to the server to report any client-side errors (e.g., failed data binding, unknown component type). diff --git a/specification/v0_10/docs/a2ui_protocol.md b/specification/v0_10/docs/a2ui_protocol.md index 214ac0ae54..4cee0aee6b 100644 --- a/specification/v0_10/docs/a2ui_protocol.md +++ b/specification/v0_10/docs/a2ui_protocol.md @@ -100,8 +100,8 @@ A2A is uniquely capable of handling remote agent communication, and can also pro - **Message mapping**: Each A2UI envelope (e.g., `updateComponents`) corresponds to the payload of a single A2A message Part. - **Metadata**: - - **Data model**: When `sendDataModel` is active, the client's `a2uiClientDataModel` object is placed in the `metadata` field of the A2A message. - - **Capabilities**: The `a2uiClientCapabilities` object is placed in the `metadata` field of every A2A message sent from the client to the server. + - **Data model**: When `sendDataModel` is active, the client's `a2uiClientDataModel` object is placed in the `metadata` field of the A2A `Message`. + - **Capabilities**: The `a2uiClientCapabilities` object is placed in the `metadata` field of every A2A `Message` sent from the client to the server. - **Context**: A2UI sessions typically map to A2A `contextId`. All messages for a set of related surfaces should share the same `contextId`. #### AG UI (Agent to User Interface) binding diff --git a/specification/v0_8/docs/a2ui_extension_specification.md b/specification/v0_8/docs/a2ui_extension_specification.md index f4d35febcc..1e8c512646 100644 --- a/specification/v0_8/docs/a2ui_extension_specification.md +++ b/specification/v0_8/docs/a2ui_extension_specification.md @@ -26,7 +26,7 @@ Server-to-Client Message Schema: The core wire format for messages sent from the Client-to-Server Event Schema: The core wire format for messages sent from the client to the agent (e.g., userAction). -Client Capabilities: The client sends its capabilities to the server in an `a2uiClientCapabilities` object. This object is included in the `metadata` field of every A2A `Message` sent from the client to the server.This object allows the client to declare which catalogs it supports. +Client Capabilities: The client sends its capabilities to the server in an `a2uiClientCapabilities` object. This object is included in the `metadata` field of every A2A `Message` sent from the client to the server. This object allows the client to declare which catalogs it supports. ## Agent Card details diff --git a/specification/v0_8/docs/a2ui_protocol.md b/specification/v0_8/docs/a2ui_protocol.md index 4d64569ccc..b9adb0d186 100644 --- a/specification/v0_8/docs/a2ui_protocol.md +++ b/specification/v0_8/docs/a2ui_protocol.md @@ -207,7 +207,7 @@ Note that this is not a strict contract and purely included as a signal to help #### 2. Client Declares Supported Catalogs -In **every** message sent to the server, the client includes an `a2uiClientCapabilities` object within the A2A `Message` metadata. This object informs the agent server of all catalogs the client can render. +In **every** message sent to the server, the client includes an `a2uiClientCapabilities` object within the A2A `Message`'s `metadata` field. This object informs the agent server of all catalogs the client can render. - `supportedCatalogIds` (array of strings, required): A list of identifiers for all pre-defined catalogs the client supports. The client must explicitly include the standard catalog ID here if it supports the standard catalog. The contents of these catalogs are expected to be compiled into the agent server and not downloaded at runtime, in order to prevent malicious content being injected into the prompt dynamically, and ensure predictable results. - `inlineCatalogs` (array of objects, optional): An array of full Catalog Definition Documents. This allows a client to provide custom, on-the-fly catalogs, typically for use in local development workflows where it is faster to update a catalog in one place on the client. This may only be provided if the server has advertised `acceptsInlineCatalogs: true`. diff --git a/specification/v0_8/docs/custom_catalog_changes.md b/specification/v0_8/docs/custom_catalog_changes.md index 0f83166aab..d10f20befa 100644 --- a/specification/v0_8/docs/custom_catalog_changes.md +++ b/specification/v0_8/docs/custom_catalog_changes.md @@ -9,7 +9,7 @@ The previous mechanism, which involved a single, one-time `clientUiCapabilities` 1. **Agent capability advertisement (`supportedCatalogIds`, `acceptsInlineCatalogs`)**: The agent's role in negotiation has been expanded. It now can declare a list of supported catalog IDs, in addition to whether it is capable of processing catalogs defined "inline" by the client. - **Relevant Doc**: [`a2ui_extension_specification.md`](./a2ui_extension_specification.md) -2. **Client capabilities via A2A metadata**: The client now sends its capabilities in an `a2uiClientCapabilities` object. Crucially, this is no longer a standalone message but is included in the `metadata` field of **every** A2A message sent to the agent. +2. **Client capabilities via A2A metadata**: The client now sends its capabilities in an `a2uiClientCapabilities` object. Crucially, this is no longer a standalone message but is included in the `metadata` field of the A2A `Message` for **every** A2A `Message` sent to the agent. - This object contains `supportedCatalogIds` (an array of known catalog IDs) and an optional `inlineCatalogs` (an array of full catalog definitions). - **Relevant doc**: The new process is explained in the [`a2ui_protocol.md`](./a2ui_protocol.md#catalog-negotiation) section on Catalog Negotiation. - **Relevant schema**: [`a2ui_client_capabilities_schema.json`](../json/a2ui_client_capabilities_schema.json) @@ -31,7 +31,7 @@ Your responsibilities are to process the client's declared capabilities and make 1. **Advertise capability**: In the agent's capability card, add the `supportedCatalogIds` array and the `acceptsInlineCatalogs: true` parameter within the A2UI extension block to declare which catalogs you support and whether you can handle dynamic ones. -2. **Parse client capabilities**: On every incoming A2A message, your library must parse the `metadata.a2uiClientCapabilities` object to determine which catalogs the client supports. You will get a list of `supportedCatalogIds` and potentially a list of `inlineCatalogs`. +2. **Parse client capabilities**: On every incoming A2A `Message`, your library must parse the `a2uiClientCapabilities` object in the `metadata` field of the A2A `Message`'s metadata field to determine which catalogs the client supports. You will get a list of `supportedCatalogIds` and potentially a list of `inlineCatalogs`. 3. **Choose a Catalog**: Before rendering a UI, decide which catalog to use. Your choice must be one of the catalogs advertised by the client in the capabilities object. @@ -43,7 +43,7 @@ Your responsibilities are to process the client's declared capabilities and make Your responsibilities are to accurately declare your capabilities and render surfaces using the catalog selected by the agent. -1. **Declare capabilities on every request**: For every A2A message your application sends, your library must inject the `a2uiClientCapabilities` object into the top-level `metadata` field. +1. **Declare capabilities on every request**: For every A2A `Message` your application sends, your library must inject the `a2uiClientCapabilities` object into the `metadata` field of the A2A `Message`. 2. **Populate `supportedCatalogIds`**: In the capabilities object, populate this array with the string identifiers of all pre-compiled catalogs your renderer supports. If your renderer supports the standard catalog for v0.8, you **should** include its ID: `https://a2ui.org/specification/v0_8/standard_catalog_definition.json`. diff --git a/specification/v0_9_1/docs/a2ui_protocol.md b/specification/v0_9_1/docs/a2ui_protocol.md index 82f45846ee..85fd98a74b 100644 --- a/specification/v0_9_1/docs/a2ui_protocol.md +++ b/specification/v0_9_1/docs/a2ui_protocol.md @@ -104,7 +104,7 @@ A2A is uniquely capable of handling remote agent communication, and can also pro - **Message mapping**: Each A2UI envelope (e.g., `updateComponents`) corresponds to the payload of a single A2A message Part. - **Metadata**: - **Data model**: When `sendDataModel` is active, the client's `a2uiClientDataModel` object is placed in the `metadata` field of the A2A message. - - **Capabilities**: The `a2uiClientCapabilities` object is placed in the `metadata` field of every A2A message sent from the client to the server. + - **Capabilities**: The `a2uiClientCapabilities` object is placed in the `metadata` field of every A2A `Message` sent from the client to the server. - **Context**: A2UI sessions typically map to A2A `contextId`. All messages for a set of related surfaces should share the same `contextId`. #### AG UI (Agent to User Interface) binding @@ -833,7 +833,7 @@ A server (or agent) advertises its capabilities using the [`server_capabilities. #### Client capabilities -The `a2uiClientCapabilities` object in the metadata follows the [`client_capabilities.json`] schema. +The `a2uiClientCapabilities` object in the A2A `Message`'s `metadata` field follows the [`client_capabilities.json`] schema. **Properties:** From 2af23265059e2cbf31355810013641dc042ff7e8 Mon Sep 17 00:00:00 2001 From: wrenj Date: Fri, 5 Jun 2026 14:43:17 -0400 Subject: [PATCH 2/3] update --- docs/guides/renderer-development.md | 2 +- specification/v0_9/docs/a2ui_protocol.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/renderer-development.md b/docs/guides/renderer-development.md index eb52f03cba..73fbc25d42 100644 --- a/docs/guides/renderer-development.md +++ b/docs/guides/renderer-development.md @@ -112,7 +112,7 @@ Implement the following communication features: - Resolve all data bindings within the `action.context` against the data model. - Send the complete `userAction` object to the server's event handling endpoint. - **Client Capabilities Reporting**: - - In **every** A2A `Message`'s `metadata` field sent to the server, include an `a2uiClientCapabilities` object. + - In **every** A2A `Message` sent to the server, include an `a2uiClientCapabilities` object in the `metadata` field of the A2A `Message`. - This object should declare the component catalog your client supports via `supportedCatalogIds` (e.g., including the URI for the standard 0.8 catalog). - Optionally, if the server supports it, provide `inlineCatalogs` for custom, on-the-fly component definitions. - **Error Reporting**: Implement a mechanism to send an `error` message to the server to report any client-side errors (e.g., failed data binding, unknown component type). diff --git a/specification/v0_9/docs/a2ui_protocol.md b/specification/v0_9/docs/a2ui_protocol.md index d214530f80..0fcf0bc150 100644 --- a/specification/v0_9/docs/a2ui_protocol.md +++ b/specification/v0_9/docs/a2ui_protocol.md @@ -104,7 +104,7 @@ A2A is uniquely capable of handling remote agent communication, and can also pro - **Message mapping**: Each A2UI envelope (e.g., `updateComponents`) corresponds to the payload of a single A2A message Part. - **Metadata**: - **Data model**: When `sendDataModel` is active, the client's `a2uiClientDataModel` object is placed in the `metadata` field of the A2A message. - - **Capabilities**: The `a2uiClientCapabilities` object is placed in the `metadata` field of every A2A message sent from the client to the server. + - **Capabilities**: The `a2uiClientCapabilities` object is placed in the `metadata` field of every A2A `Message` sent from the client to the server. - **Context**: A2UI sessions typically map to A2A `contextId`. All messages for a set of related surfaces should share the same `contextId`. #### AG UI (Agent to User Interface) binding From 6c212368065bec627ea0929807736fc526f067ab Mon Sep 17 00:00:00 2001 From: Greg Spencer Date: Mon, 15 Jun 2026 13:54:50 -0700 Subject: [PATCH 3/3] Apply suggestion from @gspencergoog Signed-off-by: Greg Spencer --- specification/v0_8/docs/custom_catalog_changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/v0_8/docs/custom_catalog_changes.md b/specification/v0_8/docs/custom_catalog_changes.md index d10f20befa..2598b2522d 100644 --- a/specification/v0_8/docs/custom_catalog_changes.md +++ b/specification/v0_8/docs/custom_catalog_changes.md @@ -31,7 +31,7 @@ Your responsibilities are to process the client's declared capabilities and make 1. **Advertise capability**: In the agent's capability card, add the `supportedCatalogIds` array and the `acceptsInlineCatalogs: true` parameter within the A2UI extension block to declare which catalogs you support and whether you can handle dynamic ones. -2. **Parse client capabilities**: On every incoming A2A `Message`, your library must parse the `a2uiClientCapabilities` object in the `metadata` field of the A2A `Message`'s metadata field to determine which catalogs the client supports. You will get a list of `supportedCatalogIds` and potentially a list of `inlineCatalogs`. +2. **Parse client capabilities**: On every incoming A2A `Message`, your library must parse the `a2uiClientCapabilities` object in the `metadata` field of the A2A `Message` to determine which catalogs the client supports. You will get a list of `supportedCatalogIds` and potentially a list of `inlineCatalogs`. 3. **Choose a Catalog**: Before rendering a UI, decide which catalog to use. Your choice must be one of the catalogs advertised by the client in the capabilities object.