AG-UI + A2UI Integration Skill
Overview
Use this skill to add A2UI rendering to an AG-UI application. Treat AG-UI as
the transport and agent integration layer, @ag-ui/a2ui-middleware as the
server-side bridge that detects and paints A2UI operations, and A2UI as the UI
payload format that the client renderer displays.
This is a developer-facing skill artifact. It is meant to be loaded by coding
agents and used against a real app or repo, not published as a docs page.
When to Use
- Adding A2UI rendering to an existing AG-UI app.
- Creating an AG-UI quickstart that should display A2UI surfaces.
- Connecting any AG-UI-supported framework or custom AG-UI agent to an
A2UI-capable frontend.
- Adding or extending an A2UI component catalog.
- Debugging why an A2UI surface does not render or why a user action does not
flow back to the agent.
When NOT to Use
- For AG-UI protocol event semantics only, use the AG-UI protocol skill or
protocol docs.
- For A2UI renderer internals outside an AG-UI app, use the A2UI renderer
docs or renderer-specific skills.
- For generic CopilotKit frontend work without A2UI, use CopilotKit-specific
setup and React skills.
Workflow
- Inspect the app shape: framework adapter, AG-UI agent endpoint, runtime
host, frontend shell, and any existing A2UI renderer/catalog.
- Decide the A2UI mode before editing code:
- Fixed schema: backend tools return an
a2ui_operations envelope with
createSurface, updateComponents, and updateDataModel.
- Dynamic schema: a framework A2UI tool (
generate_a2ui) delegates to a
sub-agent that streams render_a2ui args through A2UIMiddleware.
- Select framework-specific wiring from
references/framework-adapters.md, or use that reference to find the
closest AG-UI integration pattern. Preserve the app's existing agent
architecture.
- Wire server middleware/runtime and client renderer using
references/a2ui-runtime-and-renderer.md. Avoid double-applying
A2UIMiddleware; use either runtime-level A2UI config or per-agent
agent.use(new A2UIMiddleware(...)) for a given agent.
- Register a catalog on the client. With CopilotKit >= 1.61.2, forwarding it to
the provider (
a2ui={{ catalog }}) auto-enables A2UI and auto-derives
defaultCatalogId from the catalog's id. Only when you are not forwarding a
catalog, ensure the middleware or adapter sets a defaultCatalogId matching
the renderer-registered catalog.
- Verify the streaming path with
references/verification.md: AG-UI stream,
a2ui-surface activity snapshots or a2ui_operations, rendered A2UI
surface, and a user interaction flowing back through AG-UI.
AG-UI Framework Support
This skill is not limited to the framework examples below. For any target
framework, first check the AG-UI repository's integrations/ directory, the
AG-UI docs, the framework adapter's A2UI files, and the current CLI source. If
AG-UI supports the framework, use that integration's documented package,
endpoint helper, A2UI tool factory, or scaffold path. If there is no framework
A2UI adapter, implement the custom AG-UI agent path, return a2ui_operations
from backend tools for fixed layouts, and keep the middleware/client wiring the
same.
Common AG-UI CLI Flags
Use the CLI flags that exist in sdks/typescript/packages/cli/src/index.ts.
The table is a quick reference for known scaffold paths, not the full AG-UI
support matrix. Do not invent flags.
| Framework |
CLI flag |
| ADK |
--adk |
| LangGraph Python |
--langgraph-py |
| LangGraph JavaScript |
--langgraph-js |
| CrewAI Flows |
--crewai-flows |
| Mastra |
--mastra |
| Pydantic AI |
--pydantic-ai |
| LlamaIndex |
--llamaindex |
| Agno |
--agno |
| AG2 |
--ag2 |
Strands has AG-UI integration packages and examples, but no Strands CLI flag
is present in the current AG-UI CLI source. Use the Strands integration docs
instead of guessing a scaffold command.
Key Rules
- Keep the integration AG-UI-first for every supported framework. CopilotKit is
a common runtime/renderer path for web apps, but AG-UI owns the middleware,
framework adapters, and wire events.
- Enable A2UI on both sides:
A2UIMiddleware or runtime A2UI config on the
server, and an A2UI-capable renderer/catalog on the client.
- For dynamic schema, prefer the framework adapter's A2UI tool factory or
auto-injection path. The model should call
generate_a2ui; the sub-agent
should stream render_a2ui args so the middleware can progressively paint.
- For fixed schema, return an
a2ui_operations envelope from backend tools
rather than asking the model to invent component trees.
- Emit
createSurface once per surfaceId; use update operations for later
changes.
- Do not let the model invent catalog ids. When the client forwards a catalog to
the provider (CopilotKit >= 1.61.2), its
catalogId is derived automatically;
otherwise the host/middleware/adapter should stamp a defaultCatalogId that
matches the client-registered catalog.
- Preserve AG-UI run boundaries and error events. Do not swallow server or
stream errors.
- Verify with a real browser or client run when possible. A static typecheck is
not enough for streaming UI work.
References
references/framework-adapters.md - framework-specific AG-UI adapter
patterns.
references/a2ui-runtime-and-renderer.md - server/client A2UI wiring and
catalog patterns.
references/verification.md - checks to confirm the integration works.
sources.md - source files and docs used by this skill.
Source: ag-ui-protocol/ag-ui → skills/ag-ui-a2ui-integration/SKILL.md
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."4category: frontend-and-design5source_repo: ag-ui-protocol/ag-ui6source_path: "skills/ag-ui-a2ui-integration/SKILL.md"7source_url: https://github.com/ag-ui-protocol/ag-ui/blob/HEAD/skills/ag-ui-a2ui-integration/SKILL.md8metadata:9 source: https://skillmd.com/skills/ag-ui-protocol/ag-ui-a2ui-integration10---1112# AG-UI + A2UI Integration Skill1314## Overview1516Use this skill to add A2UI rendering to an AG-UI application. Treat AG-UI as17the transport and agent integration layer, `@ag-ui/a2ui-middleware` as the18server-side bridge that detects and paints A2UI operations, and A2UI as the UI19payload format that the client renderer displays.2021This is a developer-facing skill artifact. It is meant to be loaded by coding22agents and used against a real app or repo, not published as a docs page.2324## When to Use2526- Adding A2UI rendering to an existing AG-UI app.27- Creating an AG-UI quickstart that should display A2UI surfaces.28- Connecting any AG-UI-supported framework or custom AG-UI agent to an29 A2UI-capable frontend.30- Adding or extending an A2UI component catalog.31- Debugging why an A2UI surface does not render or why a user action does not32 flow back to the agent.3334## When NOT to Use3536- For AG-UI protocol event semantics only, use the AG-UI protocol skill or37 protocol docs.38- For A2UI renderer internals outside an AG-UI app, use the A2UI renderer39 docs or renderer-specific skills.40- For generic CopilotKit frontend work without A2UI, use CopilotKit-specific41 setup and React skills.4243## Workflow44451. Inspect the app shape: framework adapter, AG-UI agent endpoint, runtime46 host, frontend shell, and any existing A2UI renderer/catalog.472. Decide the A2UI mode before editing code:48 - Fixed schema: backend tools return an `a2ui_operations` envelope with49 `createSurface`, `updateComponents`, and `updateDataModel`.50 - Dynamic schema: a framework A2UI tool (`generate_a2ui`) delegates to a51 sub-agent that streams `render_a2ui` args through `A2UIMiddleware`.523. Select framework-specific wiring from53 `references/framework-adapters.md`, or use that reference to find the54 closest AG-UI integration pattern. Preserve the app's existing agent55 architecture.564. Wire server middleware/runtime and client renderer using57 `references/a2ui-runtime-and-renderer.md`. Avoid double-applying58 `A2UIMiddleware`; use either runtime-level A2UI config or per-agent59 `agent.use(new A2UIMiddleware(...))` for a given agent.605. Register a catalog on the client. With CopilotKit >= 1.61.2, forwarding it to61 the provider (`a2ui={{ catalog }}`) auto-enables A2UI and auto-derives62 `defaultCatalogId` from the catalog's id. Only when you are not forwarding a63 catalog, ensure the middleware or adapter sets a `defaultCatalogId` matching64 the renderer-registered catalog.656. Verify the streaming path with `references/verification.md`: AG-UI stream,66 `a2ui-surface` activity snapshots or `a2ui_operations`, rendered A2UI67 surface, and a user interaction flowing back through AG-UI.6869## AG-UI Framework Support7071This skill is not limited to the framework examples below. For any target72framework, first check the AG-UI repository's `integrations/` directory, the73AG-UI docs, the framework adapter's A2UI files, and the current CLI source. If74AG-UI supports the framework, use that integration's documented package,75endpoint helper, A2UI tool factory, or scaffold path. If there is no framework76A2UI adapter, implement the custom AG-UI agent path, return `a2ui_operations`77from backend tools for fixed layouts, and keep the middleware/client wiring the78same.7980## Common AG-UI CLI Flags8182Use the CLI flags that exist in `sdks/typescript/packages/cli/src/index.ts`.83The table is a quick reference for known scaffold paths, not the full AG-UI84support matrix. Do not invent flags.8586| Framework | CLI flag |87| -------------------- | ---------------- |88| ADK | `--adk` |89| LangGraph Python | `--langgraph-py` |90| LangGraph JavaScript | `--langgraph-js` |91| CrewAI Flows | `--crewai-flows` |92| Mastra | `--mastra` |93| Pydantic AI | `--pydantic-ai` |94| LlamaIndex | `--llamaindex` |95| Agno | `--agno` |96| AG2 | `--ag2` |9798Strands has AG-UI integration packages and examples, but no Strands CLI flag99is present in the current AG-UI CLI source. Use the Strands integration docs100instead of guessing a scaffold command.101102## Key Rules103104- Keep the integration AG-UI-first for every supported framework. CopilotKit is105 a common runtime/renderer path for web apps, but AG-UI owns the middleware,106 framework adapters, and wire events.107- Enable A2UI on both sides: `A2UIMiddleware` or runtime A2UI config on the108 server, and an A2UI-capable renderer/catalog on the client.109- For dynamic schema, prefer the framework adapter's A2UI tool factory or110 auto-injection path. The model should call `generate_a2ui`; the sub-agent111 should stream `render_a2ui` args so the middleware can progressively paint.112- For fixed schema, return an `a2ui_operations` envelope from backend tools113 rather than asking the model to invent component trees.114- Emit `createSurface` once per `surfaceId`; use update operations for later115 changes.116- Do not let the model invent catalog ids. When the client forwards a catalog to117 the provider (CopilotKit >= 1.61.2), its `catalogId` is derived automatically;118 otherwise the host/middleware/adapter should stamp a `defaultCatalogId` that119 matches the client-registered catalog.120- Preserve AG-UI run boundaries and error events. Do not swallow server or121 stream errors.122- Verify with a real browser or client run when possible. A static typecheck is123 not enough for streaming UI work.124125## References126127- `references/framework-adapters.md` - framework-specific AG-UI adapter128 patterns.129- `references/a2ui-runtime-and-renderer.md` - server/client A2UI wiring and130 catalog patterns.131- `references/verification.md` - checks to confirm the integration works.132- `sources.md` - source files and docs used by this skill.133134---135136**Source:** [`ag-ui-protocol/ag-ui`](https://github.com/ag-ui-protocol/ag-ui) → `skills/ag-ui-a2ui-integration/SKILL.md`