受控生成式 UI
使用您编写的组件渲染 Agent 输出：组件工具化、工具调用渲染、状态渲染与推理
概述
受控生成式 UI 处于生成式 UI 光谱中由开发者控制的一端。您负责编写组件，而 Agent 决定渲染哪一个组件以及向其传入什么数据。Agent 绝不直接生成标记语言：它只从您构建并测试好的固定界面集合中进行选择。
在所有生成式 UI 方法中，该模式提供了最高的可预测性。因为每个组件均来自您的代码库，所以您可以精确控制品牌规范、布局、无障碍访问（accessibility）和交互行为，并且可以确保 Agent 呈现出的任何内容都已通过您的审核。其权衡在于工程成本：每项新功能都需要您提前编写组件。您的组件库就是边界：Agent 只能渲染您已交付的内容。
何时使用此方法
在流量最高、对品牌至关重要的界面上，请选用受控生成式 UI——在这些场景中，输出集合是预先明确的，且正确性远重于新颖性：例如表单、确认流程以及任何对品牌或无障碍访问有严格要求的界面。当您需要 Agent 针对长尾的次级交互去组合您未曾预料到的布局时，请沿着光谱更进一步，转向声明式生成式 UI。
受控生成式 UI 涵盖四种技术，从 Agent 选择整个界面开始，到前端响应 Agent 内部状态结束。
组件作为工具
您向 Agent 暴露 UI 组件的方式与暴露工具相同。每个组件都具有名称、描述以及一组带类型的属性（properties），Agent 会选择一个组件并在其响应中提供相应的数据。前端将 Agent 的选择映射到您的真实实现上。这使得 Agent 的职责保持轻量——仅需决定当前时刻适合哪一个预先审核批准的界面，而您的代码则全权负责其外观和行为表现。
CopilotKit 将此模式记录为组件作为工具（components as tools）。
工具调用渲染
当 Agent 调用工具时，该调用会经历一个生命周期：挂起（pending），然后完成（complete）或失败（failed）。工具调用渲染将每个阶段转化为专门构建的 UI，例如在搜索执行时显示加载卡片、返回结果时显示结果卡片、调用失败时显示错误状态，而不是直接展示原始 JSON。这使得 Agent 的行为清晰可读，并让用户对当前发生的事情充满信心。
参见工具调用（Tool calling）模式。
状态渲染
除了消息列表之外，Agent 还会暴露持久的、带类型的状态：待办事项（todos）、流水线输出、引用来源、沙箱文件、指标以及自定义业务对象。状态渲染将您的组件绑定到该状态，从而使 UI 成为 Agent 工作的实时动态视图，而不仅仅是一份记录副本。随着 Agent 更新状态，界面也会随之同步更新。
请参阅前端概述中的带类型的 Agent 状态（typed agent state）。 有关将单个带类型的响应载荷（payload）映射到自定义 UI 的内容，请参阅结构化输出（Structured output）。
推理
具备深度思考（extended thinking）能力的模型会产生独立于其最终答案的推理过程。渲染推理过程向用户展示了 Agent 是如何得出结果的，这有助于建立信任、辅助调试并支持审计。您可以控制推理过程展示的方式和时机，例如将其置于独立于最终响应的可折叠区块中。
参见推理 Token（Reasoning tokens）模式。