clarify docs on a2ui metadata being on the message

agent_sdks/python/a2ui_agent/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:
 

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
 {

docs/guides/renderer-development.md

@@ -131,6 +131,7 @@ This section details the fundamental mechanics of the A2UI protocol. A compliant
     - **Client-to-Server**:
         - Generate and include an `actionId` inside `action` payloads.
         - Support `wantResponse: true` on actions when the client expects a response.
+        - If using A2A, every A2A `Message` sent to the server must include an `a2uiClientCapabilities` object in the `metadata` field of the A2A `Message`.
     - **Capabilities**:
         - Expose `surfaceProperties` in place of `theme` during capabilities exchange.
 

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
 

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`.

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` 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`.
 

specification/v0_9/docs/a2ui_protocol.md

@@ -103,7 +103,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

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:**
 

specification/v1_0/docs/a2ui_protocol.md

@@ -104,8 +104,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