主题
A2UI
生成式 UI 的声明式层级——智能体从你拥有的组件目录中组装出一个表面。
智能体组装 UI
基于工具的渲染将一个工具映射到一个组件：智能体选择一个组件，你来绘制它。A2UI 是生成式 UI 谱系的声明式层级——智能体不是选择单个组件，而是通过组合你定义的目录中的构建块来组装一个表面。
组件仍然由你拥有。智能体只能使用你的目录中的内容，因此它永远无法渲染你未交付的内容。智能体决定的是布局和数据——这些构建块如何组合成一个面板，以及其中放入什么。
NOTE
A2UI 可与 Flows 配合使用。下面的两种模式——动态模式和固定模式——都作为通过 AG-UI 提供的 Flows 运行，与本节的其余部分完全一样。
目录（每种模式都相同）
无论使用哪种后端模式，前端接线都相同：你在 <CopilotKit> provider 上通过 a2ui prop 注册一个目录。
tsx
import { CopilotKit } from "@copilotkit/react-core";
import { catalog } from "@/a2ui-catalog";
<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}>
{/* ... */}
</CopilotKit>目录（catalog）是以 catalog id 为键的一组 React 组件——一个 FlightCard、一个 HotelCard、一个 Chart，或你的应用需要的任何组件。智能体引用 catalog id；CopilotKit 用智能体提供的数据渲染你的组件。
NOTE
编写目录本身——id 模式、prop 映射和组合规则——比本页涵盖的内容更深入。完整的编写参考见 CopilotKit A2UI 文档。这里我们聚焦于两种后端模式，以及何时该选用哪一种。
两种后端模式
A2UI 后端有两种形态。在 dynamic 模式下，由智能体设计界面；在 fixed-schema 模式下，你预先编写布局，智能体只负责填充数据。
| 模式 | 由谁设计布局 | 后端 | 可预测性 |
|---|---|---|---|
| Dynamic | 智能体，基于对话 | 无 A2UI 工具——自动注入 | 布局新颖，需要 LLM 布局步骤 |
| Fixed-schema | 你，预先设计 | 后端工具返回信封 | 确定性，无布局步骤 |
Dynamic
该 Flow 没有接入任何 A2UI 工具。为该智能体在运行时上启用 A2UI，它就会自动获得一个 generate_a2ui 工具。子智能体基于对话、针对你的目录设计出一个界面，将它逐步流式输出到前端，并通过「先校验、后重试」的恢复流程自愈无效输出。你只需编写一个普通的智能体化对话 Flow；工具会自动注入。
Register the catalog on the provider
与上面相同——通过 a2ui prop 传入你的目录：
tsx
<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}>
{/* ... */}
</CopilotKit>Serve a normal Flow
你的后端就是一个普通的智能体化对话 Flow。你无需定义 A2UI 工具——当为该智能体启用 A2UI 时，运行时会注入 generate_a2ui，子智能体会根据对话自行构思布局。
Let the agent compose
当某一轮需要 UI 时，智能体会从你的目录中组装出一个界面，边设计边把组件流式输出进来，并在任何无效输出到达屏幕之前将其修复。你注册的组件会按智能体选定的布局渲染。
Fixed-schema
当你已经知道布局、每次调用只有数据变化时，预先编写好界面，让智能体去填充。该 Flow 接入后端工具（例如 search_flights、search_hotels）。每个工具返回一个 A2UI 操作信封作为结果——createSurface -> updateComponents -> updateDataModel——由前端渲染出来。没有子智能体、没有生成过程、也没有恢复流程：布局 JSON 由你编写，只有数据在变。
安装提供信封辅助函数的工具包：
bash
pip install ag-ui-a2ui-toolkit用工具包提供的辅助函数构建信封，并将其作为工具结果发出：
python
from ag_ui_a2ui_toolkit import (
A2UI_OPERATIONS_KEY,
create_surface,
update_components,
update_data_model,
)
from ag_ui_crewai.sdk import copilotkit_emit_tool_result, copilotkit_stream该工具把 createSurface -> updateComponents -> updateDataModel 这些操作组装成一个以 A2UI_OPERATIONS_KEY 为键的信封，然后通过 copilotkit_emit_tool_result(...) 交回。由于布局是固定的，同一个工具总是产出相同的形状——只有值在每次调用时不同。
何时使用哪一种
Dynamic
布局事先未知，你希望智能体用你提供的原语组合出全新的界面。你获得了灵活性，代价是多一个 LLM 布局步骤。
Fixed-schema
布局已知，只有数据变化。更可预测、更具确定性——没有生成、没有恢复，布局路径上也没有 LLM。
两种模式共用同一套前端：一个目录，在 provider 上注册一次即可。当你的界面稳定时从 fixed-schema 开始；当你希望智能体设计出你未曾预料到的布局时，再选用 dynamic。