尧图网站建设 
CopilotKit CrewAI 集成之 Beautiful Chat 演示完整 QA 验证指南与实现原理剖析【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit本文以仓库内 CrewAICrews集成的旗舰演示单元 Beautiful Chat 的 QA 清单qa/beautiful-chat.md为核心骨架逐项拆解其验证步骤并结合前后端源码React 前端、CopilotKit Runtime、CrewAI 后端 Crew讲解每一项背后的实现机制。读完本文你将掌握该演示从路由入口、布局渲染、建议胶囊suggestion pills到受控生成式 UI、Human-in-the-Loop、A2UI、开放生成式 UI、前端工具与共享状态等全部功能点的验证方法与底层调用链。演示单元概述Beautiful Chat 的定位Beautiful Chat 是 CopilotKit 生态中的旗舰级演示单元在 CrewAICrews集成中位于 showcase/integrations/crewai-crews/src/app/demos/beautiful-chat/。它的核心设计理念是让 UI 自己说话the UI does the talking——后端 Agent 只输出极简文字所有交互能力图表、日程选择、仪表盘、计算器、主题切换、待办列表都通过工具调用驱动前端组件渲染。从页面入口看page.tsx 通过CopilotKitProvider 装配运行时runtimeUrl指向专用的运行时端点/api/copilotkit-beautiful-chatagent为beautiful-chat对应后端 FastAPI 挂载的/beautiful-chatCrewa2ui注册了前端声明的组件目录demonstrationCatalogopenGenerativeUI被启用用于开放生成式 UI沙箱 iframe。值得注意的实现细节该页面注释明确指出useSingleEndpoint默认走单 POST 端点协议即copilotRuntimeNextJSAppRouterEndpoint方式与仓库内其他 4085 shell 单元保持一致。QA 中所有功能验证都应在此运行时配置下进行。验证点 1路由与页面根节点QA 第一步访问/demos/beautiful-chat确认页面根节点data-testidbeautiful-chat-root正常渲染。该路由对应 page.tsx 导出的BeautifulChatPage组件。它依次完成三层装配ThemeProvider来自 hooks/use-theme.tsx提供全局主题状态CopilotKit建立与运行时的连接专用端点 agentbeautiful-chatHomePage /负责渲染实际 UI。由于统一 shell 不提供每个单元独立的layout.tsx原本在参考克隆根布局中的 Provider 被内联到本页面中这是移植自 LangGraph 参考克隆4084时的一项关键重构。验证点 2ExampleLayout 双栏布局与主题切换控件QA 第二步确认左侧聊天、右侧画布的 ExampleLayout 以及主题切换控件均存在。布局实现位于 components/example-layout/index.tsx。它维护一个mode: chat | app状态chat 模式左侧聊天区占据大部分宽度flex-1右侧画布宽度收缩为 0app 模式聊天区收窄为w-1/3右侧画布扩展为w-2/3并显示边框分隔线移动端max-lg下聊天区隐藏、画布占满全宽。ModeToggle控件由用户手动点击切换同时useFrontendTool注册了enableAppMode与enableChatMode两个前端工具供 Agent 在对话中自动切换模式见下文的 Task Manager 验证点。主题切换能力来自 hooks/use-theme.tsx配合 components/example-layout/mode-toggle.tsx 中的控件渲染。验证点 3预置建议胶囊与 CrewAI 上的有意省略QA 第三步验证预置的建议胶囊正常渲染并特别确认 Excalidraw Diagram (MCP App) 胶囊在 CrewAI 上被有意省略见 use-example-suggestions.tsx。建议胶囊通过useConfigureSuggestions注册共 9 条按从最受限固定 UI到最开放自由 UI排序每条由title按钮文案与message发送给 Agent 的指令构成胶囊消息指令演示能力Pie Chart先用query_data取数据再以pieChart组件渲染受控生成式 UIBar Chart先用query_data取数据再以barChart组件渲染受控生成式 UISchedule Meeting使用scheduleTime工具让用户选择时间Human-in-the-LoopSearch Flights查找 SFO 到 JFK 的航班A2UI 固定 SchemaSales Dashboard取销售数据后用 A2UI 展示仪表盘A2UI 动态 SchemaExcalidraw Diagram用 Excalidraw 绘制网络拓扑图MCP AppCrewAI 已省略Calculator App用generateSandboxedUi构建计算器开放生成式 UIToggle Theme用toggleTheme切换主题前端工具Task Manager开启 app 模式并添加三条待办共享状态省略原因在源码中有明确交代后端 beautiful_chat.py 的文档字符串指出ag-ui-crewai没有 MCP SSE 客户端接线CrewAI Crew 使用的是 Pydantic schema 的BaseTool列表而非 MCP 多路复用器因此 Excalidraw 这条依赖 MCP 服务器的建议被从前端胶囊中移除。同理api/copilotkit-beautiful-chat/route.ts 也注释说明 LangGraph 参考克隆中的mcpApps.servers配置在 CrewAI 侧被省略。这是 QA 必须知晓的平台差异不属于回归缺陷。胶囊高亮受 showcase.json 控制showcase: a2ui时高亮 A2UI 两条opengenui时高亮计算器default时不加高亮类。验证点 4Pie Chart受控生成式 UIQA 步骤点击 Pie Chart (Controlled Generative UI)验证对话流中出现带品牌色的饼图。受控生成式 UIControlled Generative UI指组件由前端定义、渲染权在前端Agent 只通过工具调用传入数据参数。注册代码位于 hooks/use-generative-ui-examples.tsxuseComponent({ name: pieChart, description: Controlled Generative UI that displays data as a pie chart., parameters: PieChartProps, render: PieChart, });组件实现在 components/generative-ui/charts/pie-chart.tsx数据形状由PieChartPropszod schema定义。关键约束写入后端 Crew 的 backstorybeautiful_chat.py必须先调用query_data取数再调用前端pieChart/barChart动作且至少要传入两个聚合数据点禁止对这些已注册的图表动作改用generate_a2ui。验证时可通过对话流中依次出现的工具调用卡片确认这一顺序。验证点 5Bar Chart受控生成式 UIQA 步骤点击 Bar Chart (Controlled Generative UI)验证对话流中出现柱状图。与饼图对称注册代码在同一文件中use-generative-ui-examples.tsx渲染组件为 components/generative-ui/charts/bar-chart.tsx。两条图表的建议消息分别要求按收入分布by category与支出分布by category取数QA 时注意核对图表标题与数据的对应关系。验证点 6Schedule MeetingHuman In The LoopQA 步骤点击 Schedule Meeting (Human In The Loop)验证会议时间选择器渲染且选择槽位后能回显到对话中。这是 Human-in-the-Loop 的标准用法需要用户决策的 UI 由前端渲染用户确认结果后通过回调回复给 Agent。注册代码在 use-generative-ui-examples.tsxuseHumanInTheLoop({ name: scheduleTime, description: Use human-in-the-loop to schedule a meeting with the user., parameters: z.object({ reasonForScheduling: z.string().describe(Reason for scheduling, very brief - 5 words.), meetingDuration: z.number().describe(Duration of the meeting in minutes), }), render: ({ respond, status, args }) { return MeetingTimePicker status{status} respond{respond} {...args} /; }, });选择器组件为 components/generative-ui/meeting-time-picker.tsx通过respond回调把用户选择回传给运行时。后端 backstory 明确提示beautiful_chat.py当scheduleTime前端动作已注册时不得再调用后端的schedule_meeting工具否则会出现双 UI 冲突——这是该 QA 项常见失败原因。验证点 7Search FlightsA2UI 固定 SchemaQA 步骤点击 Search Flights (A2UI Fixed Schema)验证画布中渲染出航班卡片。A2UIAgent-to-UI是 AG-UI 协议下的 UI 渲染机制。固定 Schema 场景下后端通过GenerateA2uiTool位于 agents/tools/custom_tool.py返回结构化的 UI 描述前端 A2UI 渲染器将其映射为具体组件。后端 backstory 对该工具有硬性约束beautiful_chat.py必须恰好返回两张标准 mock 航班卡——United $349 与 Delta $289QA 时核对价格即可快速判断数据是否正确。A2UI 的组件目录catalog由前端注册页面传入a2ui{{ catalog: demonstrationCatalog }}目录定义在 declarative-generative-ui/renderers.tsx结构见 definitions.ts。注意验证前提航班卡片渲染在画布右侧面板而非对话流中。验证点 8Sales DashboardA2UI 动态 SchemaQA 步骤点击 Sales Dashboard (A2UI Dynamic)验证仪表盘渲染出指标卡片 饼图 柱状图。动态 Schema 指模型在运行时动态决定 UI 结构。建议消息要求先用query_data取财务销售数据再通过 A2UI 渲染总收入、新客户、转化率三项指标 收入饼图 月度销售柱状图。渲染链路与 Search Flights 相同GenerateA2uiTool→ A2UI 渲染器但 UI 复杂度更高。这里有一个运行时层面的关键配置route.tsconst runtime new CopilotRuntime({ agents, openGenerativeUI: true, a2ui: { injectA2UITool: false, // 后端 Crew 自持 generate_a2ui避免重复注入 defaultCatalogId: copilotkit://app-dashboard-catalog, // 固定目录 }, });injectA2UITool: false保证后端只注入一次generate_a2uidefaultCatalogId固定到页面注册的目录避免模型未指定catalogId时中间件回退到未注册的基础目录而报 Catalog not found 渲染错误。验证点 9Calculator App开放生成式 UIQA 步骤点击 Calculator App (Open Generative UI)验证计算器渲染在沙箱 iframe 内。开放生成式 UIOpen Generative UI通过generateSandboxedUi工具让模型生成完整的前端代码并在沙箱 iframe 中执行与受控/A2UI 的预注册组件模式完全不同。启用开关正是页面与运行时中的openGenerativeUI{}/openGenerativeUI: true。建议消息要求计算器包含标准按钮 可点击插入数值的指标快捷按钮并使用示例公司数据。QA 验证要点iframe 沙箱隔离性——生成代码不得访问外层页面 DOM 或状态同时确认计算器的插入数值功能快捷按钮 → 显示器可用。验证点 10Toggle Theme前端工具QA 步骤点击 Toggle Theme (Frontend Tools)验证主题切换生效。前端工具Frontend Tools允许 Agent 直接调用注册在浏览器端的处理器。注册代码在 use-generative-ui-examples.tsxuseFrontendTool({ name: toggleTheme, description: Frontend tool for toggling the theme of the app., parameters: z.object({}), handler: async () { const isDark document.documentElement.classList.contains(dark); setTheme(isDark ? light : dark); }, });该钩子有意省略了 deps 数组——源码注释use-generative-ui-examples.tsx说明若将[theme, setTheme]加入依赖每次主题翻转都会重新注册处理器可能与运行时的在途工具结果产生竞争在多轮探测中表现为渲染层错误。QA 时若需连续多次切换主题应确认无此竞态。后端 backstory 还要求浏览器返回后Agent 必须回复与可见文本完全一致的句子Theme toggledbeautiful_chat.py验证对话流中的回复文案是否精确匹配。验证点 11Task Manager共享状态QA 步骤点击 Task Manager (Shared State)验证 app 模式画布中出现三条待办。共享状态是该演示最复杂的机制也是CrewAI 与 LangGraph 参考实现的第二大差异点LangGraph 参考通过manage_todos工具返回Command补丁状态CrewAI 没有等价的状态补丁原语因此后端ManageTodosToolbeautiful_chat.py采用整体替换策略接收完整 todos 列表为缺少 id 的项补uuid4然后将{todos: [...]}以 JSON 字符串作为工具结果返回前端 headless chat 包装层读取该返回值并维护本地 todos 状态。class ManageTodosTool(BaseTool): name: str manage_todos description: str ( Manage the current todos. Pass the FULL list of todos; the previous list is replaced. Each todo needs id, title, description, emoji, and status. ) args_schema: Type[BaseModel] ManageTodosInput def _run(self, todos: list[dict]) - str: import uuid for todo in todos: if not todo.get(id): todo[id] str(uuid.uuid4()) return json.dumps({todos: todos})数据形状TodoItemid/title/description/emoji/status与前端Todo类型严格对应beautiful_chat.py。建议消息要求添加三条与学习 CopilotKit 相关的待办但 QA 时应额外验证完整性列表是整体替换而非追加若消息只给出 2 条原有第 3 条会消失——这正是共享状态语义的体现。画布侧的待办 UI 由 components/example-canvas/ 实现todo-list、todo-column、todo-card配合enableAppMode前端工具自动切换到 app 模式。验证时确认点击胶囊后模式自动切换为 app三条待办以列卡片形式出现在右侧画布。验证点 12后端 Crew 与默认工具卡片渲染在逐项点击胶囊之前/之后还有两个贯穿性验证值得一并检查。后端 Crew 装配BeautifulChat适配器beautiful_chat.py符合add_crewai_crew_fastapi_endpoint的接入形状单 Agent 单 Task 顺序 ProcessProcess.sequential并缓存 Crew 实例。Agent 绑定了 6 个工具GetWeatherTool、QueryDataTool、ScheduleMeetingTool、SearchFlightsTool、GenerateA2uiTool来自共享工具模块 agents/tools/custom_tool.pyManageTodosTool本演示新增。Backstory 被刻意调校为精简、专业的短回复1-2 句以维持演示UI 说话的体验preseed_system_prompt为会话注入预置系统提示beautiful_chat.py。注意QA 在探测天气功能时应直接输入天气问题如 Hows the weather in SF?因为胶囊列表中没有对应项。默认工具卡片渲染useDefaultRenderTooluse-generative-ui-examples.tsx将未被专门处理的工具以推理卡片形式渲染在对话流中但明确忽略三个 A2UI 内部工具render_a2ui由 A2UI 流式渲染不显示为工具卡、generate_a2ui由 A2UI 渲染、log_a2ui_event内部事件追踪。QA 时若看到这三个名称的工具卡属于渲染异常。前端与运行时的调用链总结综合以上验证点Beautiful Chat 的完整调用链可归纳为用户点击建议胶囊 → useConfigureSuggestions 发送 message → CopilotKit Runtime (/api/copilotkit-beautiful-chat, single-route 模式) → HttpAgent → FastAPI /beautiful-chat 端点 → CrewAI Crew (beautiful_chat.py) → 工具调用分派 ├─ 前端动作useComponent / useHumanInTheLoop / useFrontendTool 注册 │ → pieChart / barChart / scheduleTime / toggleTheme / enableAppMode ├─ A2UIGenerateA2uiTool→ declarative-generative-ui catalog 渲染 │ → 航班卡 / 销售仪表盘 ├─ 开放生成式 UIgenerateSandboxedUi→ 沙箱 iframe 计算器 └─ 共享状态ManageTodosTool→ JSON 结果 → headless chat → 待办画布 → 结果回显到 CopilotChat 对话流 ExampleCanvas 右侧画布整条链路中前端工具注册hooks/use-generative-ui-examples.tsx、运行时配置api/copilotkit-beautiful-chat/route.ts与后端 Crewagents/beautiful_chat.py三处必须保持工具名称、参数 schema 与目录 id 的严格一致任何一处失配都会导致对应 QA 项失败——这也是该演示单元作为集成冒烟测试的价值所在。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CopilotKit CrewAI 集成之 Beautiful Chat 演示：完整 QA 验证指南与实现原理剖析
CopilotKit CrewAI 集成之 Beautiful Chat 演示完整 QA 验证指南与实现原理剖析【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit本文以仓库内 CrewAICrews集成的旗舰演示单元 Beautiful Chat 的 QA 清单qa/beautiful-chat.md为核心骨架逐项拆解其验证步骤并结合前后端源码React 前端、CopilotKit Runtime、CrewAI 后端 Crew讲解每一项背后的实现机制。读完本文你将掌握该演示从路由入口、布局渲染、建议胶囊suggestion pills到受控生成式 UI、Human-in-the-Loop、A2UI、开放生成式 UI、前端工具与共享状态等全部功能点的验证方法与底层调用链。演示单元概述Beautiful Chat 的定位Beautiful Chat 是 CopilotKit 生态中的旗舰级演示单元在 CrewAICrews集成中位于 showcase/integrations/crewai-crews/src/app/demos/beautiful-chat/。它的核心设计理念是让 UI 自己说话the UI does the talking——后端 Agent 只输出极简文字所有交互能力图表、日程选择、仪表盘、计算器、主题切换、待办列表都通过工具调用驱动前端组件渲染。从页面入口看page.tsx 通过CopilotKitProvider 装配运行时runtimeUrl指向专用的运行时端点/api/copilotkit-beautiful-chatagent为beautiful-chat对应后端 FastAPI 挂载的/beautiful-chatCrewa2ui注册了前端声明的组件目录demonstrationCatalogopenGenerativeUI被启用用于开放生成式 UI沙箱 iframe。值得注意的实现细节该页面注释明确指出useSingleEndpoint默认走单 POST 端点协议即copilotRuntimeNextJSAppRouterEndpoint方式与仓库内其他 4085 shell 单元保持一致。QA 中所有功能验证都应在此运行时配置下进行。验证点 1路由与页面根节点QA 第一步访问/demos/beautiful-chat确认页面根节点data-testidbeautiful-chat-root正常渲染。该路由对应 page.tsx 导出的BeautifulChatPage组件。它依次完成三层装配ThemeProvider来自 hooks/use-theme.tsx提供全局主题状态CopilotKit建立与运行时的连接专用端点 agentbeautiful-chatHomePage /负责渲染实际 UI。由于统一 shell 不提供每个单元独立的layout.tsx原本在参考克隆根布局中的 Provider 被内联到本页面中这是移植自 LangGraph 参考克隆4084时的一项关键重构。验证点 2ExampleLayout 双栏布局与主题切换控件QA 第二步确认左侧聊天、右侧画布的 ExampleLayout 以及主题切换控件均存在。布局实现位于 components/example-layout/index.tsx。它维护一个mode: chat | app状态chat 模式左侧聊天区占据大部分宽度flex-1右侧画布宽度收缩为 0app 模式聊天区收窄为w-1/3右侧画布扩展为w-2/3并显示边框分隔线移动端max-lg下聊天区隐藏、画布占满全宽。ModeToggle控件由用户手动点击切换同时useFrontendTool注册了enableAppMode与enableChatMode两个前端工具供 Agent 在对话中自动切换模式见下文的 Task Manager 验证点。主题切换能力来自 hooks/use-theme.tsx配合 components/example-layout/mode-toggle.tsx 中的控件渲染。验证点 3预置建议胶囊与 CrewAI 上的有意省略QA 第三步验证预置的建议胶囊正常渲染并特别确认 Excalidraw Diagram (MCP App) 胶囊在 CrewAI 上被有意省略见 use-example-suggestions.tsx。建议胶囊通过useConfigureSuggestions注册共 9 条按从最受限固定 UI到最开放自由 UI排序每条由title按钮文案与message发送给 Agent 的指令构成胶囊消息指令演示能力Pie Chart先用query_data取数据再以pieChart组件渲染受控生成式 UIBar Chart先用query_data取数据再以barChart组件渲染受控生成式 UISchedule Meeting使用scheduleTime工具让用户选择时间Human-in-the-LoopSearch Flights查找 SFO 到 JFK 的航班A2UI 固定 SchemaSales Dashboard取销售数据后用 A2UI 展示仪表盘A2UI 动态 SchemaExcalidraw Diagram用 Excalidraw 绘制网络拓扑图MCP AppCrewAI 已省略Calculator App用generateSandboxedUi构建计算器开放生成式 UIToggle Theme用toggleTheme切换主题前端工具Task Manager开启 app 模式并添加三条待办共享状态省略原因在源码中有明确交代后端 beautiful_chat.py 的文档字符串指出ag-ui-crewai没有 MCP SSE 客户端接线CrewAI Crew 使用的是 Pydantic schema 的BaseTool列表而非 MCP 多路复用器因此 Excalidraw 这条依赖 MCP 服务器的建议被从前端胶囊中移除。同理api/copilotkit-beautiful-chat/route.ts 也注释说明 LangGraph 参考克隆中的mcpApps.servers配置在 CrewAI 侧被省略。这是 QA 必须知晓的平台差异不属于回归缺陷。胶囊高亮受 showcase.json 控制showcase: a2ui时高亮 A2UI 两条opengenui时高亮计算器default时不加高亮类。验证点 4Pie Chart受控生成式 UIQA 步骤点击 Pie Chart (Controlled Generative UI)验证对话流中出现带品牌色的饼图。受控生成式 UIControlled Generative UI指组件由前端定义、渲染权在前端Agent 只通过工具调用传入数据参数。注册代码位于 hooks/use-generative-ui-examples.tsxuseComponent({ name: pieChart, description: Controlled Generative UI that displays data as a pie chart., parameters: PieChartProps, render: PieChart, });组件实现在 components/generative-ui/charts/pie-chart.tsx数据形状由PieChartPropszod schema定义。关键约束写入后端 Crew 的 backstorybeautiful_chat.py必须先调用query_data取数再调用前端pieChart/barChart动作且至少要传入两个聚合数据点禁止对这些已注册的图表动作改用generate_a2ui。验证时可通过对话流中依次出现的工具调用卡片确认这一顺序。验证点 5Bar Chart受控生成式 UIQA 步骤点击 Bar Chart (Controlled Generative UI)验证对话流中出现柱状图。与饼图对称注册代码在同一文件中use-generative-ui-examples.tsx渲染组件为 components/generative-ui/charts/bar-chart.tsx。两条图表的建议消息分别要求按收入分布by category与支出分布by category取数QA 时注意核对图表标题与数据的对应关系。验证点 6Schedule MeetingHuman In The LoopQA 步骤点击 Schedule Meeting (Human In The Loop)验证会议时间选择器渲染且选择槽位后能回显到对话中。这是 Human-in-the-Loop 的标准用法需要用户决策的 UI 由前端渲染用户确认结果后通过回调回复给 Agent。注册代码在 use-generative-ui-examples.tsxuseHumanInTheLoop({ name: scheduleTime, description: Use human-in-the-loop to schedule a meeting with the user., parameters: z.object({ reasonForScheduling: z.string().describe(Reason for scheduling, very brief - 5 words.), meetingDuration: z.number().describe(Duration of the meeting in minutes), }), render: ({ respond, status, args }) { return MeetingTimePicker status{status} respond{respond} {...args} /; }, });选择器组件为 components/generative-ui/meeting-time-picker.tsx通过respond回调把用户选择回传给运行时。后端 backstory 明确提示beautiful_chat.py当scheduleTime前端动作已注册时不得再调用后端的schedule_meeting工具否则会出现双 UI 冲突——这是该 QA 项常见失败原因。验证点 7Search FlightsA2UI 固定 SchemaQA 步骤点击 Search Flights (A2UI Fixed Schema)验证画布中渲染出航班卡片。A2UIAgent-to-UI是 AG-UI 协议下的 UI 渲染机制。固定 Schema 场景下后端通过GenerateA2uiTool位于 agents/tools/custom_tool.py返回结构化的 UI 描述前端 A2UI 渲染器将其映射为具体组件。后端 backstory 对该工具有硬性约束beautiful_chat.py必须恰好返回两张标准 mock 航班卡——United $349 与 Delta $289QA 时核对价格即可快速判断数据是否正确。A2UI 的组件目录catalog由前端注册页面传入a2ui{{ catalog: demonstrationCatalog }}目录定义在 declarative-generative-ui/renderers.tsx结构见 definitions.ts。注意验证前提航班卡片渲染在画布右侧面板而非对话流中。验证点 8Sales DashboardA2UI 动态 SchemaQA 步骤点击 Sales Dashboard (A2UI Dynamic)验证仪表盘渲染出指标卡片 饼图 柱状图。动态 Schema 指模型在运行时动态决定 UI 结构。建议消息要求先用query_data取财务销售数据再通过 A2UI 渲染总收入、新客户、转化率三项指标 收入饼图 月度销售柱状图。渲染链路与 Search Flights 相同GenerateA2uiTool→ A2UI 渲染器但 UI 复杂度更高。这里有一个运行时层面的关键配置route.tsconst runtime new CopilotRuntime({ agents, openGenerativeUI: true, a2ui: { injectA2UITool: false, // 后端 Crew 自持 generate_a2ui避免重复注入 defaultCatalogId: copilotkit://app-dashboard-catalog, // 固定目录 }, });injectA2UITool: false保证后端只注入一次generate_a2uidefaultCatalogId固定到页面注册的目录避免模型未指定catalogId时中间件回退到未注册的基础目录而报 Catalog not found 渲染错误。验证点 9Calculator App开放生成式 UIQA 步骤点击 Calculator App (Open Generative UI)验证计算器渲染在沙箱 iframe 内。开放生成式 UIOpen Generative UI通过generateSandboxedUi工具让模型生成完整的前端代码并在沙箱 iframe 中执行与受控/A2UI 的预注册组件模式完全不同。启用开关正是页面与运行时中的openGenerativeUI{}/openGenerativeUI: true。建议消息要求计算器包含标准按钮 可点击插入数值的指标快捷按钮并使用示例公司数据。QA 验证要点iframe 沙箱隔离性——生成代码不得访问外层页面 DOM 或状态同时确认计算器的插入数值功能快捷按钮 → 显示器可用。验证点 10Toggle Theme前端工具QA 步骤点击 Toggle Theme (Frontend Tools)验证主题切换生效。前端工具Frontend Tools允许 Agent 直接调用注册在浏览器端的处理器。注册代码在 use-generative-ui-examples.tsxuseFrontendTool({ name: toggleTheme, description: Frontend tool for toggling the theme of the app., parameters: z.object({}), handler: async () { const isDark document.documentElement.classList.contains(dark); setTheme(isDark ? light : dark); }, });该钩子有意省略了 deps 数组——源码注释use-generative-ui-examples.tsx说明若将[theme, setTheme]加入依赖每次主题翻转都会重新注册处理器可能与运行时的在途工具结果产生竞争在多轮探测中表现为渲染层错误。QA 时若需连续多次切换主题应确认无此竞态。后端 backstory 还要求浏览器返回后Agent 必须回复与可见文本完全一致的句子Theme toggledbeautiful_chat.py验证对话流中的回复文案是否精确匹配。验证点 11Task Manager共享状态QA 步骤点击 Task Manager (Shared State)验证 app 模式画布中出现三条待办。共享状态是该演示最复杂的机制也是CrewAI 与 LangGraph 参考实现的第二大差异点LangGraph 参考通过manage_todos工具返回Command补丁状态CrewAI 没有等价的状态补丁原语因此后端ManageTodosToolbeautiful_chat.py采用整体替换策略接收完整 todos 列表为缺少 id 的项补uuid4然后将{todos: [...]}以 JSON 字符串作为工具结果返回前端 headless chat 包装层读取该返回值并维护本地 todos 状态。class ManageTodosTool(BaseTool): name: str manage_todos description: str ( Manage the current todos. Pass the FULL list of todos; the previous list is replaced. Each todo needs id, title, description, emoji, and status. ) args_schema: Type[BaseModel] ManageTodosInput def _run(self, todos: list[dict]) - str: import uuid for todo in todos: if not todo.get(id): todo[id] str(uuid.uuid4()) return json.dumps({todos: todos})数据形状TodoItemid/title/description/emoji/status与前端Todo类型严格对应beautiful_chat.py。建议消息要求添加三条与学习 CopilotKit 相关的待办但 QA 时应额外验证完整性列表是整体替换而非追加若消息只给出 2 条原有第 3 条会消失——这正是共享状态语义的体现。画布侧的待办 UI 由 components/example-canvas/ 实现todo-list、todo-column、todo-card配合enableAppMode前端工具自动切换到 app 模式。验证时确认点击胶囊后模式自动切换为 app三条待办以列卡片形式出现在右侧画布。验证点 12后端 Crew 与默认工具卡片渲染在逐项点击胶囊之前/之后还有两个贯穿性验证值得一并检查。后端 Crew 装配BeautifulChat适配器beautiful_chat.py符合add_crewai_crew_fastapi_endpoint的接入形状单 Agent 单 Task 顺序 ProcessProcess.sequential并缓存 Crew 实例。Agent 绑定了 6 个工具GetWeatherTool、QueryDataTool、ScheduleMeetingTool、SearchFlightsTool、GenerateA2uiTool来自共享工具模块 agents/tools/custom_tool.pyManageTodosTool本演示新增。Backstory 被刻意调校为精简、专业的短回复1-2 句以维持演示UI 说话的体验preseed_system_prompt为会话注入预置系统提示beautiful_chat.py。注意QA 在探测天气功能时应直接输入天气问题如 Hows the weather in SF?因为胶囊列表中没有对应项。默认工具卡片渲染useDefaultRenderTooluse-generative-ui-examples.tsx将未被专门处理的工具以推理卡片形式渲染在对话流中但明确忽略三个 A2UI 内部工具render_a2ui由 A2UI 流式渲染不显示为工具卡、generate_a2ui由 A2UI 渲染、log_a2ui_event内部事件追踪。QA 时若看到这三个名称的工具卡属于渲染异常。前端与运行时的调用链总结综合以上验证点Beautiful Chat 的完整调用链可归纳为用户点击建议胶囊 → useConfigureSuggestions 发送 message → CopilotKit Runtime (/api/copilotkit-beautiful-chat, single-route 模式) → HttpAgent → FastAPI /beautiful-chat 端点 → CrewAI Crew (beautiful_chat.py) → 工具调用分派 ├─ 前端动作useComponent / useHumanInTheLoop / useFrontendTool 注册 │ → pieChart / barChart / scheduleTime / toggleTheme / enableAppMode ├─ A2UIGenerateA2uiTool→ declarative-generative-ui catalog 渲染 │ → 航班卡 / 销售仪表盘 ├─ 开放生成式 UIgenerateSandboxedUi→ 沙箱 iframe 计算器 └─ 共享状态ManageTodosTool→ JSON 结果 → headless chat → 待办画布 → 结果回显到 CopilotChat 对话流 ExampleCanvas 右侧画布整条链路中前端工具注册hooks/use-generative-ui-examples.tsx、运行时配置api/copilotkit-beautiful-chat/route.ts与后端 Crewagents/beautiful_chat.py三处必须保持工具名称、参数 schema 与目录 id 的严格一致任何一处失配都会导致对应 QA 项失败——这也是该演示单元作为集成冒烟测试的价值所在。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考