ag-ui-a2ui-integration

1---2name: ag-ui-a2ui-integration3description: "Use when adding A2UI rendering to any AG-UI-supported framework or custom AG-UI application, scaffolding an AG-UI app that should render A2UI, adapting an AG-UI integration to emit A2UI surfaces, or wiring the AG-UI A2UI middleware/toolkit with a compatible renderer."4version: 1.1.05---6 7# AG-UI + A2UI Integration Skill8 9## Overview10 11Use this skill to add A2UI rendering to an AG-UI application. Treat AG-UI as12the transport and agent integration layer, `@ag-ui/a2ui-middleware` as the13server-side bridge that detects and paints A2UI operations, and A2UI as the UI14payload format that the client renderer displays.15 16This is a developer-facing skill artifact. It is meant to be loaded by coding17agents and used against a real app or repo, not published as a docs page.18 19## When to Use20 21- Adding A2UI rendering to an existing AG-UI app.22- Creating an AG-UI quickstart that should display A2UI surfaces.23- Connecting any AG-UI-supported framework or custom AG-UI agent to an24  A2UI-capable frontend.25- Adding or extending an A2UI component catalog.26- Debugging why an A2UI surface does not render or why a user action does not27  flow back to the agent.28 29## When NOT to Use30 31- For AG-UI protocol event semantics only, use the AG-UI protocol skill or32  protocol docs.33- For A2UI renderer internals outside an AG-UI app, use the A2UI renderer34  docs or renderer-specific skills.35- For generic CopilotKit frontend work without A2UI, use CopilotKit-specific36  setup and React skills.37 38## Workflow39 401. Inspect the app shape: framework adapter, AG-UI agent endpoint, runtime41   host, frontend shell, and any existing A2UI renderer/catalog.422. Decide the A2UI mode before editing code:43   - Fixed schema: backend tools return an `a2ui_operations` envelope with44     `createSurface`, `updateComponents`, and `updateDataModel`.45   - Dynamic schema: a framework A2UI tool (`generate_a2ui`) delegates to a46     sub-agent that streams `render_a2ui` args through `A2UIMiddleware`.473. Select framework-specific wiring from48   `references/framework-adapters.md`, or use that reference to find the49   closest AG-UI integration pattern. Preserve the app's existing agent50   architecture.514. Wire server middleware/runtime and client renderer using52   `references/a2ui-runtime-and-renderer.md`. Avoid double-applying53   `A2UIMiddleware`; use either runtime-level A2UI config or per-agent54   `agent.use(new A2UIMiddleware(...))` for a given agent.555. Register a catalog on the client. With CopilotKit >= 1.61.2, forwarding it to56   the provider (`a2ui={{ catalog }}`) auto-enables A2UI and auto-derives57   `defaultCatalogId` from the catalog's id. Only when you are not forwarding a58   catalog, ensure the middleware or adapter sets a `defaultCatalogId` matching59   the renderer-registered catalog.606. Verify the streaming path with `references/verification.md`: AG-UI stream,61   `a2ui-surface` activity snapshots or `a2ui_operations`, rendered A2UI62   surface, and a user interaction flowing back through AG-UI.63 64## AG-UI Framework Support65 66This skill is not limited to the framework examples below. For any target67framework, first check the AG-UI repository's `integrations/` directory, the68AG-UI docs, the framework adapter's A2UI files, and the current CLI source. If69AG-UI supports the framework, use that integration's documented package,70endpoint helper, A2UI tool factory, or scaffold path. If there is no framework71A2UI adapter, implement the custom AG-UI agent path, return `a2ui_operations`72from backend tools for fixed layouts, and keep the middleware/client wiring the73same.74 75## Common AG-UI CLI Flags76 77Use the CLI flags that exist in `sdks/typescript/packages/cli/src/index.ts`.78The table is a quick reference for known scaffold paths, not the full AG-UI79support matrix. Do not invent flags.80 81| Framework            | CLI flag         |82| -------------------- | ---------------- |83| ADK                  | `--adk`          |84| LangGraph Python     | `--langgraph-py` |85| LangGraph JavaScript | `--langgraph-js` |86| CrewAI Flows         | `--crewai-flows` |87| Mastra               | `--mastra`       |88| Pydantic AI          | `--pydantic-ai`  |89| LlamaIndex           | `--llamaindex`   |90| Agno                 | `--agno`         |91| AG2                  | `--ag2`          |92 93Strands has AG-UI integration packages and examples, but no Strands CLI flag94is present in the current AG-UI CLI source. Use the Strands integration docs95instead of guessing a scaffold command.96 97## Key Rules98 99- Keep the integration AG-UI-first for every supported framework. CopilotKit is100  a common runtime/renderer path for web apps, but AG-UI owns the middleware,101  framework adapters, and wire events.102- Enable A2UI on both sides: `A2UIMiddleware` or runtime A2UI config on the103  server, and an A2UI-capable renderer/catalog on the client.104- For dynamic schema, prefer the framework adapter's A2UI tool factory or105  auto-injection path. The model should call `generate_a2ui`; the sub-agent106  should stream `render_a2ui` args so the middleware can progressively paint.107- For fixed schema, return an `a2ui_operations` envelope from backend tools108  rather than asking the model to invent component trees.109- Emit `createSurface` once per `surfaceId`; use update operations for later110  changes.111- Do not let the model invent catalog ids. When the client forwards a catalog to112  the provider (CopilotKit >= 1.61.2), its `catalogId` is derived automatically;113  otherwise the host/middleware/adapter should stamp a `defaultCatalogId` that114  matches the client-registered catalog.115- Preserve AG-UI run boundaries and error events. Do not swallow server or116  stream errors.117- Verify with a real browser or client run when possible. A static typecheck is118  not enough for streaming UI work.119 120## References121 122- `references/framework-adapters.md` - framework-specific AG-UI adapter123  patterns.124- `references/a2ui-runtime-and-renderer.md` - server/client A2UI wiring and125  catalog patterns.126- `references/verification.md` - checks to confirm the integration works.127- `sources.md` - source files and docs used by this skill.128