Authoring generative UI over AG-UI

Authoring generative UI over AG-UI

CAO exposes an AG-UI stream (GET /agui/v1/stream) that any dashboard — CopilotKit, the AG-UI Dojo, or a plain EventSource — renders without CAO-specific code. As an agent you can push a declarative UI intent onto that stream with the emit_ui MCP tool. The operator sees a rendered card, not raw text — and because every provider's intents render uniformly, they can't tell (and don't need to) which CLI agent produced which card.

The surface must be enabled on the server (CAO_AGUI_ENABLED=true or CAO_MCP_APPS_ENABLED=true — the two surfaces share one event source). When it is disabled, emit_ui returns {"ok": false, "reason": "AG-UI surface disabled…"} — treat that as a no-op, not an error.

Safety model (why this is always safe to call)

You may emit only a closed allow-list of named components with JSON props. There is no HTML, no script, no eval, no iframe. The intent is validated server-side against the allow-list before it reaches the stream:

• An off-list component (e.g. iframe, script) is refused — the tool raises a ValueError; nothing is rendered.
• props must be JSON-serializable and are bounded to 8 KB — an oversized or non-serializable payload is rejected at the emit_ui boundary (HTTP 400, the tool raises a ValueError), so a bad payload never reaches the bus.
• If the AG-UI surface is disabled on the server, the tool degrades gracefully (no error) — so calling it is never fatal.
• The AG-UI stream is metadata-only by contract: never put message bodies, credentials, or file contents in props. Reference paths, not contents.

The tool

emit_ui(component: str, props: dict) -> {"ok", "event_id", "component"}

component must be one of: approval_card, choice_prompt, diff_summary, progress, metric, agent_card.

When to use which component