CopilotKit × CrewAI 会话流Beautiful Chat 旗舰演示的生成式 UI 全景验证指南【免费下载链接】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/CopilotKitBeautiful Chat 是 CopilotKit 仓库中crewai-conversational-flows集成列showcase/integrations/crewai-conversational-flows的旗舰展示单元一个由 CrewAI 后端驱动的生成式 UI 聊天应用在同一页面里把受控生成式 UIControlled Generative UI、人工介入Human In The Loop、A2UI 固定/动态 Schema、开放式生成式 UIOpen Generative UI、前端工具Frontend Tools与共享状态Shared State六类能力一次性串起来。本文以仓库 QA 清单 qa/beautiful-chat.md 为骨架逐条拆解 10 个验证步骤并结合前端页面、运行时路由与 CrewAI 后端源码讲清楚每一步在代码层面如何落地、验证信号是什么帮助读者在本地复现并深入理解这套对话即界面的完整调用链。一、Beautiful Chat 是什么一个页面装下全部生成式 UI 能力在 CopilotKit 的展示体系中Beautiful Chat 承担的是旗舰示例角色它把项目中最具代表性的交互范式集中到一个 demo 里验证Agent 通过工具调用直接驱动前端渲染这条主链路。在crewai-conversational-flows列中它的前端与 LangGraph 参考实现逐字对齐页面头部注释说明其由 4084 reference clone 移植而来但后端换成了 CrewAI 会话流执行方式。从代码结构看这个 demo 是三层协作Next.js 前端src/app/demos/beautiful-chatpage.tsx挂载 CopilotKit Provider 与主题 Providerhome-page.tsx组装聊天与画布布局运行时端点src/app/api/copilotkit-beautiful-chat/route.ts为这个单元单独开辟/api/copilotkit-beautiful-chat避免把openGenerativeUI、a2ui等全局开关泄漏给共享/api/copilotkit的其他单元CrewAI 后端src/agents/beautiful_chat.py、src/agents/beautiful_chat_flow.py以 FastAPI 挂载在/conversational_flows/beautiful-chat执行后端工具并回流事件。验证入口固定为/demos/beautiful-chat。根据 PARITY_NOTES.md本列钉住ag-ui-crewai0.3.0与crewai1.15.11所有模型路径使用gpt-5.4本地 D6 验证走crewai-conversational-flowscompose 服务端口 3120后端即 src/agent_server.py 暴露的 FastAPI 应用。二、页面骨架验证布局、主题切换与根标记QA 清单的前两个检查点是页面级冒烟测试页面根节点data-testidbeautiful-chat-root正常渲染ExampleLayout左聊天、右画布与主题切换组件存在。对应前端组装逻辑在 home-page.tsxexport function HomePage() { useGenerativeUIExamples(); useExampleSuggestions(); return ( ExampleLayout chatContent{CopilotChat attachments{{ enabled: true }} /} appContent{ExampleCanvas /} / ); }ExampleLayoutcomponents/example-layout/index.tsx维护chat | app双模式状态聊天模式下左侧聊天区占满宽度、右侧画布宽度收缩为 0应用模式下聊天区收窄为 1/3、右侧画布展开到 2/3移动端各自全屏切换。右下角固定悬浮的 Chat/App 胶囊切换按钮由 mode-toggle.tsx 实现。注意一个值得留意的细节QA 清单中的data-testidbeautiful-chat-root在当前源码中未作为静态标记出现实际 e2e 冒烟测试tests/e2e/beautiful-chat.spec.ts 的第一个用例改用三个等价信号断言左上角 CopilotKit logoimg[altCopilotKit]、右上角 Chat/App 模式切换按钮、以及聊天输入框占位符 Type a message。在人工 QA 时可以任选其一作为页面挂载成功的判定。主题切换组件由 hooks/use-theme.tsx 的ThemeProvider提供它维护light | dark | system三态并通过操作document.documentElement上的 class 生效——这正是后文Toggle Theme验证信号的来源。三、建议胶囊九大能力入口与验证清单useExampleSuggestionshooks/use-example-suggestions.tsx通过useConfigureSuggestions预置了 9 个建议胶囊suggestion pills每个胶囊对应一类演示能力。QA 清单要求逐一验证这些胶囊渲染并可点击触发对应界面。下表把胶囊、能力类型与验证预期对应起来建议胶囊标题能力类别验证预期Pie Chart (Controlled Generative UI)受控生成式 UI对话流内渲染品牌化饼图Bar Chart (Controlled Generative UI)受控生成式 UI对话流内渲染柱状图Schedule Meeting (Human In The Loop)人工介入渲染会议时间选择器选择结果回显到聊天Search Flights (A2UI Fixed Schema)A2UI 固定 Schema对话流内渲染航班卡片Sales Dashboard (A2UI Dynamic)A2UI 动态 Schema渲染含指标 饼图 柱状图的仪表盘Calculator App (Open Generative UI)开放式生成式 UI沙箱 iframe 内渲染计算器Toggle Theme (Frontend Tools)前端工具页面主题翻转Task Manager (Shared State)共享状态应用模式画布出现三条待办每个胶囊的message就是发送给 Agent 的提示语例如饼图胶囊的完整消息是Show me a pie chart of our revenue distribution by category. Use the query_data tool to fetch the data first, then render it with the pieChart component.——注意它显式规定了工具调用顺序先query_data取数再调用前端pieChart组件这是受控生成式 UI 的典型交互契约。QA 清单特别提示LangGraph 参考实现中的Excalidraw Diagram (MCP App) 胶囊在 CrewAI 列被有意排除原因是ag-ui-crewai没有 MCP SSE 客户端管线CrewAI crew 使用 Pydantic-schema 的BaseTool列表而非 MCP 多路复用器详见 beautiful_chat.py 头部注释与 route.ts 注释。从源码看该胶囊在前端use-example-suggestions.tsx中仍然存在且不参与高亮showcase.json的showcase字段为default见 showcase.jsone2e 也只把它纳入渲染断言而非点击可用范围人工 QA 时应对该胶囊不做功能预期。四、Controlled Generative UI饼图与柱状图受控生成式 UI 的含义是组件由前端开发者预先注册schema React 实现Agent 只能按注册的协议点菜不能自由生成 DOM。Beautiful Chat 通过useGenerativeUIExampleshooks/use-generative-ui-examples.tsx注册了两个图表组件useComponent({ name: pieChart, description: Controlled Generative UI that displays data as a pie chart., parameters: PieChartProps, render: PieChart, }); useComponent({ name: barChart, description: Controlled Generative UI that displays data as a bar chart., parameters: BarChartProps, render: BarChart, });PieChartProps/BarChartProps是 Zod schemapie-chart.tsx 与 bar-chart.tsx接收title、description与{label, value}[]数据。饼图实现是一个自绘 SVG 环形图circlestroke-dasharray计算弧长附图例与百分比柱状图基于 recharts 并带新增柱的滑入动画。后端侧beautiful_chat.py 的 backstory对 Agent 的约束是先调用query_data取数再把聚合结果交给前端pieChart/barChartaction不得为这些已注册图表调用generate_a2ui。这正是 QA 中点击胶囊后对话流内渲染图表的驱动逻辑——图表是注册组件的直出而非 LLM 生成的 HTML。验证要点饼图应出现环形图 SVG背景环 每片数据一个circle与带百分比图例e2e 对svg circle数量与/\d%/文本做断言。柱状图应出现.recharts-responsive-container与至少两个.recharts-bar-rectangle。若图表渲染为空数据组件会回退为 No data available 占位卡片两种图表都有此分支。五、Human In The Loop会议时间选择器人工介入能力由useHumanInTheLoop注册的scheduleTime前端 action 承担use-generative-ui-examples.tsx。它声明了两个参数reasonForScheduling5 词以内的预约原因与meetingDuration分钟数渲染组件为MeetingTimePicker。MeetingTimePicker 有三种状态inProgress显示加载 SpinnerFinding available times...executing列出默认三个时间槽Tomorrow 2:00 PM / Friday 10:00 AM / Next Monday 3:00 PM时长取自meetingDuration参数默认 30 分钟选择或拒绝后进入确认态/拒绝态卡片。QA 清单要求选择槽位后回显到聊天其实现是选择回调把结果拼成一句自然语言回传const handleSelectSlot (slot: TimeSlot) { setSelectedSlot(slot); respond?.( Meeting scheduled for ${slot.date} at ${slot.time}${slot.duration ? (${slot.duration}) : }., ); };respond把用户的选择作为该人工介入工具的最终结果送回 AgentAgent 据此继续对话。有意思的是后端 backstory 明确要求当scheduleTime前端 action 可用时调用它而不是后端的schedule_meeting工具——这体现了能由用户界面决策的就不让模型武断决定的设计取向。六、A2UI Fixed Schema航班卡片A2UIAG-UI 生态的声明式 UI 协议固定 Schema 路径演示数据模型绑定 预定义组件目录后端工具返回结构化数据前端按 schema 把数据绑定到目录组件上。后端SearchFlightsTooltools/custom_tool.py是固定的 mock无论输入如何都返回两条 canonical 航班——United $349UA231与 Delta $289DL412包含航班号、起降时间、航程、状态等字段。数据通过search_flights工具的 A2UI 操作a2ui_operations容器回流前端。前端目录注册在 declarative-generative-ui/renderers.tsxexport const demonstrationCatalog createCatalog( demonstrationCatalogDefinitions, demonstrationCatalogRenderers, { catalogId: copilotkit://app-dashboard-catalog, includeBasicCatalog: true, // 合并基础 A2UI 原语以支持结构性 children 展开 }, );FlightCardrenderer同文件FlightCard定义把航司 logo、价格、航班号、时间轴、状态色点与Select按钮渲染成品牌卡片definitions.ts中FlightCard的所有字段airline、price 等被定义为DynString——即字面字符串或数据模型路径绑定二选一渲染期由 GenericBinder 解析。QA 中点击 Search Flights 胶囊后出现航班卡片在 e2e 里以航司名与价格文本United Airlines、$349、$289作为稳定断言目标这些文本来自 aimock fixture而非不稳定的 LLM 输出。七、A2UI Dynamic销售仪表盘动态 Schema 路径演示Agent 按需生成整个 UI 树由GenerateA2uiTooltools/custom_tool.py触发——它调用一个二级 LLM系统提示为Generate a dynamic A2UI dashboard based on the conversation强制该 LLM 调用render_a2ui工具产出 UI 结构与数据再由 A2UI 中间件交给前端目录渲染。QA 预期仪表盘包含指标卡Metrics 饼图 柱状图这些组件全部来自 renderers.tsx 的Metric、PieChart、BarChart渲染器。一个关键的运行时配置在 route.tsconst runtime new CopilotRuntime({ agents, openGenerativeUI: true, a2ui: { injectA2UITool: false, // 后端 crew 自己持有 generate_a2ui 工具避免重复注入 defaultCatalogId: copilotkit://app-dashboard-catalog, }, });defaultCatalogId的注释解释了它的来由模型生成的组件省略catalogId时中间件会回退到未注册的 spec 基础目录从而出现 Catalog not found 渲染错误因此这里把页面注册的目录固定为默认目录。e2e 测试beautiful-chat.spec.ts 的 Sales Dashboard 用例以此为回归守卫断言不出现 Catalog not found 与 Cannot create component ... without a type且 recharts 容器不超过 2 个1 饼 1 柱。八、Open Generative UI沙箱计算器开放式生成式 UI 与受控式相反Agent 不限于注册组件而是调用generateSandboxedUi工具生成完整 UIHTML/JS在运行时提供的沙箱 iframe 中渲染。该能力的开关就是 page.tsx 中的openGenerativeUI{{}}与运行时的openGenerativeUI: true。QA 验证的Calculator App胶囊消息要求 AgentUsing the generateSandboxedUi tool, build a modern calculator with standard buttons plus labeled metric shortcut buttons that insert their values into the display when clicked.使用示例公司数据。点击后应在沙箱 iframe 中出现可交互计算器——它不经过前端目录而是由运行时直接把 Agent 生成的 UI 封闭在 iframe 里运行。值得一提的取舍page.tsx的注释说明本单元之所以使用专属运行时端点/api/copilotkit-beautiful-chat正是为了能同时开启openGenerativeUI、a2ui且injectA2UITool: false而不会把全局开关污染给共享主端点的其他单元。这是理解该 demo 运行时架构的关键能力组合越复杂越需要端点隔离。九、Frontend Tools主题切换前端工具是 CopilotKit 让 Agent 直接操作浏览器状态的机制。toggleTheme的注册在 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); }, });代码注释里还记录了一个有价值的坑handler 的依赖数组不能包含[theme, setTheme]否则每次主题翻转都会导致 hook 重新注册可能与飞行中的工具结果竞争在多轮探测时暴露为渲染层错误——所以这里用无依赖写法直接读document。QA 验证信号非常干净html元素上的darkclass 翻转。e2e 用expect.poll轮询 class 直到与初始值相反同时断言往返成立Agent 响应 前端工具都生效。后端 backstory 还要求浏览器返回后回复固定文本 Theme toggled保持演示的UI 说话风格。十、Shared State任务管理器画布共享状态演示Agent 状态与前端画布双向同步。整条链路包含三层后端写入ManageTodosToolbeautiful_chat.py接收完整待办列表并原样返回 JSON。注意它与 LangGraph 参考实现的差异记录在文件头与 PARITY_NOTESLangGraph 用Command直接补丁状态CrewAI 没有等价原语因此工具返回{todos: [...]}由前端接管状态维护。前端读取ExampleCanvascomponents/example-canvas/index.tsx通过useAgent({ agentId: beautiful-chat })读取agent.state?.todos用agent.setState回写模式切换enableAppMode前端工具注册在 example-layout/index.tsx把布局切到 App 模式让右侧画布展开。QA 的Task Manager胶囊会要求 Agent Enable app mode and add three todos about learning CopilotKit。e2e 断言画布中section[aria-labelTo Do column]可见且三条特定文本Read the CopilotKit docs、Build a CopilotKit prototype、Explore shared agent state逐条出现——这些也是 aimock fixture 文本。TodoListtodo-list.tsx把待办按 pending/completed 分成两列支持勾选、删除、内联改标题/描述/emoji并且 Agent 运行时禁用新增任务按钮以防状态竞争。十一、后端纵深会话流执行与工具分流理解 Beautiful Chat 的验证结果需要看清后端 beautiful_chat_flow.py 的执行循环。其核心是BeautifulChatFlow(Flow[CopilotKitState])每轮把self.state.copilotkit.actions前端注册的 action 的 schema与 6 个后端工具get_weather、query_data、schedule_meeting、search_flights、generate_a2ui、manage_todos合并成工具列表交给acompletion流式调用 LLM最多 8 次迭代直到模型不再发起工具调用关键分流若工具名不在BACKEND_TOOLS_BY_NAME中即浏览器拥有的 action如pieChart、scheduleTime、toggleThemeFlow 直接return把执行权交还 CopilotKit 运行时在前端执行之后再带着真实结果恢复 Agentresume——这就是受控生成式 UI / 人工介入 / 前端工具在协议层的落点后端工具的结果通过copilotkit_emit_tool_result(tool_call_id, content)回流为权威事件parallel_tool_callsFalse保证顺序。Flow 的会话化包装在 conversational_flows.py_conversational_type(BeautifulChatFlow)生成带conversationalTrue的会话 Flow 类型暴露 CrewAI 公开的stream_turn并以 AG-UI 的threadId作为 CrewAI 会话session_idagent_server.py 遍历CONVERSATIONAL_FLOW_TYPES为每个 feature 注册/conversational_flows/{feature}端点其中beautiful-chat映射到BeautifulChatFlow。前端运行时则用HttpAgent指向${AGENT_URL}/conversational_flows/beautiful-chatAGENT_URL默认http://localhost:8000并给beautiful-chat与default两个 agentId 注册了同一 agent保证useAgent()无参调用也能解析。十二、E2E 自动化验证与回归守卫QA 清单对应着完整的 Playwright 套件 tests/e2e/beautiful-chat.spec.ts共 8 个用例其断言策略值得在人工 QA 时复用渲染信号前置beforeEach先等 Toggle Theme (Frontend Tools) 胶囊可见15 秒超时因为 9 个胶囊在同一渲染批次挂载任意一个可见即代表水合完成避免点击竞态以 fixture 文本而非 LLM 输出断言航班、仪表盘、待办文本全部来自 aimock fixture如 showcase/aimock/d6/crewai-conversational-flows 下的记录保证跨运行稳定副作用优先主题切换不等待聊天气泡而是轮询html的darkclass这是因为该 demo 的工具调用在对话流内直出渲染、不产生独立文本气泡回归守卫Sales Dashboard 用例显式断言 Catalog not found 与 Cannot create component ... without a type 不出现对应defaultCatalogId修复的线上回归并限制 recharts 容器 ≤ 2防止重复渲染超时预算涉及二级 LLM 的用例仪表盘 90 秒、任务管理器 120 秒预留冷启动余量。小结Beautiful Chat 的价值在于它是一份生成式 UI 能力地图从受控图表、人工介入、A2UI 固定/动态 Schema到开放式沙箱 UI、前端工具与共享状态九颗胶囊对应九条可验证的链路。做 QA 时建议按渲染信号 → 交互信号 → 回归守卫三层递进先确认胶囊与页面骨架再逐一触发并核对组件级指纹SVG circle、recharts 容器、iframe、class 翻转、待办文本最后对已知回归点catalog 丢失、重复渲染、MCP 缺失做负向断言。理解后端 Flow 的前端 action 让权 后端工具回流分流机制后任何一步验证失败都能快速定位到协议层、运行时层还是组件层。【免费下载链接】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 旗舰演示的生成式 UI 全景验证指南
CopilotKit × CrewAI 会话流Beautiful Chat 旗舰演示的生成式 UI 全景验证指南【免费下载链接】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/CopilotKitBeautiful Chat 是 CopilotKit 仓库中crewai-conversational-flows集成列showcase/integrations/crewai-conversational-flows的旗舰展示单元一个由 CrewAI 后端驱动的生成式 UI 聊天应用在同一页面里把受控生成式 UIControlled Generative UI、人工介入Human In The Loop、A2UI 固定/动态 Schema、开放式生成式 UIOpen Generative UI、前端工具Frontend Tools与共享状态Shared State六类能力一次性串起来。本文以仓库 QA 清单 qa/beautiful-chat.md 为骨架逐条拆解 10 个验证步骤并结合前端页面、运行时路由与 CrewAI 后端源码讲清楚每一步在代码层面如何落地、验证信号是什么帮助读者在本地复现并深入理解这套对话即界面的完整调用链。一、Beautiful Chat 是什么一个页面装下全部生成式 UI 能力在 CopilotKit 的展示体系中Beautiful Chat 承担的是旗舰示例角色它把项目中最具代表性的交互范式集中到一个 demo 里验证Agent 通过工具调用直接驱动前端渲染这条主链路。在crewai-conversational-flows列中它的前端与 LangGraph 参考实现逐字对齐页面头部注释说明其由 4084 reference clone 移植而来但后端换成了 CrewAI 会话流执行方式。从代码结构看这个 demo 是三层协作Next.js 前端src/app/demos/beautiful-chatpage.tsx挂载 CopilotKit Provider 与主题 Providerhome-page.tsx组装聊天与画布布局运行时端点src/app/api/copilotkit-beautiful-chat/route.ts为这个单元单独开辟/api/copilotkit-beautiful-chat避免把openGenerativeUI、a2ui等全局开关泄漏给共享/api/copilotkit的其他单元CrewAI 后端src/agents/beautiful_chat.py、src/agents/beautiful_chat_flow.py以 FastAPI 挂载在/conversational_flows/beautiful-chat执行后端工具并回流事件。验证入口固定为/demos/beautiful-chat。根据 PARITY_NOTES.md本列钉住ag-ui-crewai0.3.0与crewai1.15.11所有模型路径使用gpt-5.4本地 D6 验证走crewai-conversational-flowscompose 服务端口 3120后端即 src/agent_server.py 暴露的 FastAPI 应用。二、页面骨架验证布局、主题切换与根标记QA 清单的前两个检查点是页面级冒烟测试页面根节点data-testidbeautiful-chat-root正常渲染ExampleLayout左聊天、右画布与主题切换组件存在。对应前端组装逻辑在 home-page.tsxexport function HomePage() { useGenerativeUIExamples(); useExampleSuggestions(); return ( ExampleLayout chatContent{CopilotChat attachments{{ enabled: true }} /} appContent{ExampleCanvas /} / ); }ExampleLayoutcomponents/example-layout/index.tsx维护chat | app双模式状态聊天模式下左侧聊天区占满宽度、右侧画布宽度收缩为 0应用模式下聊天区收窄为 1/3、右侧画布展开到 2/3移动端各自全屏切换。右下角固定悬浮的 Chat/App 胶囊切换按钮由 mode-toggle.tsx 实现。注意一个值得留意的细节QA 清单中的data-testidbeautiful-chat-root在当前源码中未作为静态标记出现实际 e2e 冒烟测试tests/e2e/beautiful-chat.spec.ts 的第一个用例改用三个等价信号断言左上角 CopilotKit logoimg[altCopilotKit]、右上角 Chat/App 模式切换按钮、以及聊天输入框占位符 Type a message。在人工 QA 时可以任选其一作为页面挂载成功的判定。主题切换组件由 hooks/use-theme.tsx 的ThemeProvider提供它维护light | dark | system三态并通过操作document.documentElement上的 class 生效——这正是后文Toggle Theme验证信号的来源。三、建议胶囊九大能力入口与验证清单useExampleSuggestionshooks/use-example-suggestions.tsx通过useConfigureSuggestions预置了 9 个建议胶囊suggestion pills每个胶囊对应一类演示能力。QA 清单要求逐一验证这些胶囊渲染并可点击触发对应界面。下表把胶囊、能力类型与验证预期对应起来建议胶囊标题能力类别验证预期Pie Chart (Controlled Generative UI)受控生成式 UI对话流内渲染品牌化饼图Bar Chart (Controlled Generative UI)受控生成式 UI对话流内渲染柱状图Schedule Meeting (Human In The Loop)人工介入渲染会议时间选择器选择结果回显到聊天Search Flights (A2UI Fixed Schema)A2UI 固定 Schema对话流内渲染航班卡片Sales Dashboard (A2UI Dynamic)A2UI 动态 Schema渲染含指标 饼图 柱状图的仪表盘Calculator App (Open Generative UI)开放式生成式 UI沙箱 iframe 内渲染计算器Toggle Theme (Frontend Tools)前端工具页面主题翻转Task Manager (Shared State)共享状态应用模式画布出现三条待办每个胶囊的message就是发送给 Agent 的提示语例如饼图胶囊的完整消息是Show me a pie chart of our revenue distribution by category. Use the query_data tool to fetch the data first, then render it with the pieChart component.——注意它显式规定了工具调用顺序先query_data取数再调用前端pieChart组件这是受控生成式 UI 的典型交互契约。QA 清单特别提示LangGraph 参考实现中的Excalidraw Diagram (MCP App) 胶囊在 CrewAI 列被有意排除原因是ag-ui-crewai没有 MCP SSE 客户端管线CrewAI crew 使用 Pydantic-schema 的BaseTool列表而非 MCP 多路复用器详见 beautiful_chat.py 头部注释与 route.ts 注释。从源码看该胶囊在前端use-example-suggestions.tsx中仍然存在且不参与高亮showcase.json的showcase字段为default见 showcase.jsone2e 也只把它纳入渲染断言而非点击可用范围人工 QA 时应对该胶囊不做功能预期。四、Controlled Generative UI饼图与柱状图受控生成式 UI 的含义是组件由前端开发者预先注册schema React 实现Agent 只能按注册的协议点菜不能自由生成 DOM。Beautiful Chat 通过useGenerativeUIExampleshooks/use-generative-ui-examples.tsx注册了两个图表组件useComponent({ name: pieChart, description: Controlled Generative UI that displays data as a pie chart., parameters: PieChartProps, render: PieChart, }); useComponent({ name: barChart, description: Controlled Generative UI that displays data as a bar chart., parameters: BarChartProps, render: BarChart, });PieChartProps/BarChartProps是 Zod schemapie-chart.tsx 与 bar-chart.tsx接收title、description与{label, value}[]数据。饼图实现是一个自绘 SVG 环形图circlestroke-dasharray计算弧长附图例与百分比柱状图基于 recharts 并带新增柱的滑入动画。后端侧beautiful_chat.py 的 backstory对 Agent 的约束是先调用query_data取数再把聚合结果交给前端pieChart/barChartaction不得为这些已注册图表调用generate_a2ui。这正是 QA 中点击胶囊后对话流内渲染图表的驱动逻辑——图表是注册组件的直出而非 LLM 生成的 HTML。验证要点饼图应出现环形图 SVG背景环 每片数据一个circle与带百分比图例e2e 对svg circle数量与/\d%/文本做断言。柱状图应出现.recharts-responsive-container与至少两个.recharts-bar-rectangle。若图表渲染为空数据组件会回退为 No data available 占位卡片两种图表都有此分支。五、Human In The Loop会议时间选择器人工介入能力由useHumanInTheLoop注册的scheduleTime前端 action 承担use-generative-ui-examples.tsx。它声明了两个参数reasonForScheduling5 词以内的预约原因与meetingDuration分钟数渲染组件为MeetingTimePicker。MeetingTimePicker 有三种状态inProgress显示加载 SpinnerFinding available times...executing列出默认三个时间槽Tomorrow 2:00 PM / Friday 10:00 AM / Next Monday 3:00 PM时长取自meetingDuration参数默认 30 分钟选择或拒绝后进入确认态/拒绝态卡片。QA 清单要求选择槽位后回显到聊天其实现是选择回调把结果拼成一句自然语言回传const handleSelectSlot (slot: TimeSlot) { setSelectedSlot(slot); respond?.( Meeting scheduled for ${slot.date} at ${slot.time}${slot.duration ? (${slot.duration}) : }., ); };respond把用户的选择作为该人工介入工具的最终结果送回 AgentAgent 据此继续对话。有意思的是后端 backstory 明确要求当scheduleTime前端 action 可用时调用它而不是后端的schedule_meeting工具——这体现了能由用户界面决策的就不让模型武断决定的设计取向。六、A2UI Fixed Schema航班卡片A2UIAG-UI 生态的声明式 UI 协议固定 Schema 路径演示数据模型绑定 预定义组件目录后端工具返回结构化数据前端按 schema 把数据绑定到目录组件上。后端SearchFlightsTooltools/custom_tool.py是固定的 mock无论输入如何都返回两条 canonical 航班——United $349UA231与 Delta $289DL412包含航班号、起降时间、航程、状态等字段。数据通过search_flights工具的 A2UI 操作a2ui_operations容器回流前端。前端目录注册在 declarative-generative-ui/renderers.tsxexport const demonstrationCatalog createCatalog( demonstrationCatalogDefinitions, demonstrationCatalogRenderers, { catalogId: copilotkit://app-dashboard-catalog, includeBasicCatalog: true, // 合并基础 A2UI 原语以支持结构性 children 展开 }, );FlightCardrenderer同文件FlightCard定义把航司 logo、价格、航班号、时间轴、状态色点与Select按钮渲染成品牌卡片definitions.ts中FlightCard的所有字段airline、price 等被定义为DynString——即字面字符串或数据模型路径绑定二选一渲染期由 GenericBinder 解析。QA 中点击 Search Flights 胶囊后出现航班卡片在 e2e 里以航司名与价格文本United Airlines、$349、$289作为稳定断言目标这些文本来自 aimock fixture而非不稳定的 LLM 输出。七、A2UI Dynamic销售仪表盘动态 Schema 路径演示Agent 按需生成整个 UI 树由GenerateA2uiTooltools/custom_tool.py触发——它调用一个二级 LLM系统提示为Generate a dynamic A2UI dashboard based on the conversation强制该 LLM 调用render_a2ui工具产出 UI 结构与数据再由 A2UI 中间件交给前端目录渲染。QA 预期仪表盘包含指标卡Metrics 饼图 柱状图这些组件全部来自 renderers.tsx 的Metric、PieChart、BarChart渲染器。一个关键的运行时配置在 route.tsconst runtime new CopilotRuntime({ agents, openGenerativeUI: true, a2ui: { injectA2UITool: false, // 后端 crew 自己持有 generate_a2ui 工具避免重复注入 defaultCatalogId: copilotkit://app-dashboard-catalog, }, });defaultCatalogId的注释解释了它的来由模型生成的组件省略catalogId时中间件会回退到未注册的 spec 基础目录从而出现 Catalog not found 渲染错误因此这里把页面注册的目录固定为默认目录。e2e 测试beautiful-chat.spec.ts 的 Sales Dashboard 用例以此为回归守卫断言不出现 Catalog not found 与 Cannot create component ... without a type且 recharts 容器不超过 2 个1 饼 1 柱。八、Open Generative UI沙箱计算器开放式生成式 UI 与受控式相反Agent 不限于注册组件而是调用generateSandboxedUi工具生成完整 UIHTML/JS在运行时提供的沙箱 iframe 中渲染。该能力的开关就是 page.tsx 中的openGenerativeUI{{}}与运行时的openGenerativeUI: true。QA 验证的Calculator App胶囊消息要求 AgentUsing the generateSandboxedUi tool, build a modern calculator with standard buttons plus labeled metric shortcut buttons that insert their values into the display when clicked.使用示例公司数据。点击后应在沙箱 iframe 中出现可交互计算器——它不经过前端目录而是由运行时直接把 Agent 生成的 UI 封闭在 iframe 里运行。值得一提的取舍page.tsx的注释说明本单元之所以使用专属运行时端点/api/copilotkit-beautiful-chat正是为了能同时开启openGenerativeUI、a2ui且injectA2UITool: false而不会把全局开关污染给共享主端点的其他单元。这是理解该 demo 运行时架构的关键能力组合越复杂越需要端点隔离。九、Frontend Tools主题切换前端工具是 CopilotKit 让 Agent 直接操作浏览器状态的机制。toggleTheme的注册在 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); }, });代码注释里还记录了一个有价值的坑handler 的依赖数组不能包含[theme, setTheme]否则每次主题翻转都会导致 hook 重新注册可能与飞行中的工具结果竞争在多轮探测时暴露为渲染层错误——所以这里用无依赖写法直接读document。QA 验证信号非常干净html元素上的darkclass 翻转。e2e 用expect.poll轮询 class 直到与初始值相反同时断言往返成立Agent 响应 前端工具都生效。后端 backstory 还要求浏览器返回后回复固定文本 Theme toggled保持演示的UI 说话风格。十、Shared State任务管理器画布共享状态演示Agent 状态与前端画布双向同步。整条链路包含三层后端写入ManageTodosToolbeautiful_chat.py接收完整待办列表并原样返回 JSON。注意它与 LangGraph 参考实现的差异记录在文件头与 PARITY_NOTESLangGraph 用Command直接补丁状态CrewAI 没有等价原语因此工具返回{todos: [...]}由前端接管状态维护。前端读取ExampleCanvascomponents/example-canvas/index.tsx通过useAgent({ agentId: beautiful-chat })读取agent.state?.todos用agent.setState回写模式切换enableAppMode前端工具注册在 example-layout/index.tsx把布局切到 App 模式让右侧画布展开。QA 的Task Manager胶囊会要求 Agent Enable app mode and add three todos about learning CopilotKit。e2e 断言画布中section[aria-labelTo Do column]可见且三条特定文本Read the CopilotKit docs、Build a CopilotKit prototype、Explore shared agent state逐条出现——这些也是 aimock fixture 文本。TodoListtodo-list.tsx把待办按 pending/completed 分成两列支持勾选、删除、内联改标题/描述/emoji并且 Agent 运行时禁用新增任务按钮以防状态竞争。十一、后端纵深会话流执行与工具分流理解 Beautiful Chat 的验证结果需要看清后端 beautiful_chat_flow.py 的执行循环。其核心是BeautifulChatFlow(Flow[CopilotKitState])每轮把self.state.copilotkit.actions前端注册的 action 的 schema与 6 个后端工具get_weather、query_data、schedule_meeting、search_flights、generate_a2ui、manage_todos合并成工具列表交给acompletion流式调用 LLM最多 8 次迭代直到模型不再发起工具调用关键分流若工具名不在BACKEND_TOOLS_BY_NAME中即浏览器拥有的 action如pieChart、scheduleTime、toggleThemeFlow 直接return把执行权交还 CopilotKit 运行时在前端执行之后再带着真实结果恢复 Agentresume——这就是受控生成式 UI / 人工介入 / 前端工具在协议层的落点后端工具的结果通过copilotkit_emit_tool_result(tool_call_id, content)回流为权威事件parallel_tool_callsFalse保证顺序。Flow 的会话化包装在 conversational_flows.py_conversational_type(BeautifulChatFlow)生成带conversationalTrue的会话 Flow 类型暴露 CrewAI 公开的stream_turn并以 AG-UI 的threadId作为 CrewAI 会话session_idagent_server.py 遍历CONVERSATIONAL_FLOW_TYPES为每个 feature 注册/conversational_flows/{feature}端点其中beautiful-chat映射到BeautifulChatFlow。前端运行时则用HttpAgent指向${AGENT_URL}/conversational_flows/beautiful-chatAGENT_URL默认http://localhost:8000并给beautiful-chat与default两个 agentId 注册了同一 agent保证useAgent()无参调用也能解析。十二、E2E 自动化验证与回归守卫QA 清单对应着完整的 Playwright 套件 tests/e2e/beautiful-chat.spec.ts共 8 个用例其断言策略值得在人工 QA 时复用渲染信号前置beforeEach先等 Toggle Theme (Frontend Tools) 胶囊可见15 秒超时因为 9 个胶囊在同一渲染批次挂载任意一个可见即代表水合完成避免点击竞态以 fixture 文本而非 LLM 输出断言航班、仪表盘、待办文本全部来自 aimock fixture如 showcase/aimock/d6/crewai-conversational-flows 下的记录保证跨运行稳定副作用优先主题切换不等待聊天气泡而是轮询html的darkclass这是因为该 demo 的工具调用在对话流内直出渲染、不产生独立文本气泡回归守卫Sales Dashboard 用例显式断言 Catalog not found 与 Cannot create component ... without a type 不出现对应defaultCatalogId修复的线上回归并限制 recharts 容器 ≤ 2防止重复渲染超时预算涉及二级 LLM 的用例仪表盘 90 秒、任务管理器 120 秒预留冷启动余量。小结Beautiful Chat 的价值在于它是一份生成式 UI 能力地图从受控图表、人工介入、A2UI 固定/动态 Schema到开放式沙箱 UI、前端工具与共享状态九颗胶囊对应九条可验证的链路。做 QA 时建议按渲染信号 → 交互信号 → 回归守卫三层递进先确认胶囊与页面骨架再逐一触发并核对组件级指纹SVG circle、recharts 容器、iframe、class 翻转、待办文本最后对已知回归点catalog 丢失、重复渲染、MCP 缺失做负向断言。理解后端 Flow 的前端 action 让权 后端工具回流分流机制后任何一步验证失败都能快速定位到协议层、运行时层还是组件层。【免费下载链接】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），仅供参考