Spec gap: recommended transport for A2uiClientAction when surfaces are embedded in a chat (AG-UI / CopilotKit) host

[sunholo-voight-kampff]

Context

A2UI v0.9 defines the A2uiClientAction message shape (name, surfaceId, sourceComponentId, timestamp, context) for user interactions (Button click, form submit, etc.) on a rendered surface.

The spec is explicit about the message shape but — as far as we can find — silent about the transport when A2UI surfaces are embedded inside a chat-style agent (mounted in an AG-UI / CopilotKit host) rather than running as a standalone A2UI app.

What we did

We POST the action to a sibling REST endpoint on the chat backend:

POST /api/sessions/{session_id}/surface-action
{
  "name": "...",
  "surfaceId": "...",
  "sourceComponentId": "...",
  "timestamp": "...",
  "context": { ... }
}

The backend writes the structured action into ADK session state under a namespaced key (a2ui_surface_context.{surfaceId}.lastAction) so the agent's next turn can read it. Gated per-skill via tool_configs.a2ui.allow_surface_context_writes (mirrors the per-server opt-in pattern from MCP Apps), 4 KB cap on the context field.

This works, but every consumer of our template has to follow our convention — there's no spec hook telling them what the "right" transport is.

What we'd like to clarify

1. Is there an implicit recommended transport we missed in the v0.9 spec for the chat-embedded case (vs the standalone A2UI app)?
2. If not, would the spec benefit from a non-normative "Embedded host" section that recommends one of:
   • A sibling REST endpoint pattern (what we did)
   • Riding back on the chat transport's own out-of-band channel (e.g. AG-UI's forwardedProps on the next user message — has the "wait until next user input" tradeoff)
   • A protocol-level "surface action" event so the host transport adopts it explicitly
3. Is there an existing convention used by the A2UI reference implementation or other early adopters we could align with?

Related

• Leveraging A2UI message parts for layout-first, progressive rendering (without spec or transport changes) #470 — Progressive rendering & action routing (touches on the orchestrator-routes-userAction model, but not specifically on embedded transport)

Happy to contribute a docs PR or reference example once the recommended approach is clear.

cc @MarkEdmondson1234