基于工具调用Tool-Based的生成式 UI 端到端验收指南CopilotKit × CrewAI Conversational Flows【免费下载链接】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本文以仓库内 QA 文档 showcase/integrations/crewai-conversational-flows/qa/gen-ui-tool-based.md 为主体面向在 CopilotKit 生态中搭建 CrewAI Conversational Flows 演示的开发者与测试人员。文档给出了一套完整的「工具型生成式 UI」人工验收流程从前置环境检查、基础聊天功能、建议按钮与前端工具渲染、到错误处理与性能预期逐项给出可勾选的验收动作、断言锚点data-testid与超时阈值。读完本文你将能够照此清单对任意useFrontendTool/useComponent类型的生成式 UI 演示执行标准化验收并理解仓库中对应源码与端到端测试是如何验证同一套行为的。一、这份 QA 文档在验证什么该 QA 文档是 CopilotKit 仓库中CrewAI Conversational Flows 集成演示showcase/integrations/crewai-conversational-flows下的验收用例其主题是Tool-Based Generative UIAgent 不是直接吐出 UI 数据而是通过调用前端注册的「工具」让浏览器端组件负责最终渲染。仓库中该演示的实际实现位于 src/app/demos/gen-ui-tool-based/page.tsx页面注册了render_bar_chart与render_pie_chart两个组件后端 Flow 收到用户消息后强制调用其中一个图表工具浏览器随后渲染出 Recharts 柱状图或 SVG 环形图。QA 文档中描述的场景Haiku Generator侧边栏、俳句卡片与图片是同一验收方法论在俳句生成器形态上的应用仓库源码中已给出图表版的完整对照实现两者验证的核心机制一致前端注册组件 → 运行时将其注入为 Agent 工具 → 模型调用 → 浏览器渲染并回传结果。这一点在 src/agents/gen_ui_tool_based.py 的模块注释中有明确说明该 Flow 镜像自langgraph-python/src/agents/gen_ui_tool_based.py。二、验收前置条件Prerequisites在开始任何验收动作之前QA 文档要求确认两项环境前提演示已部署且可访问确保gen-ui-tool-based演示页面通过路由正常加载Agent 后端健康检查/api/health健康检查接口返回正常保证运行时runtime与 CrewAI Flow 之间的流式通道可用。仓库中该演示通过 src/app/api/copilotkit/route.ts 暴露/api/copilotkit运行时端点前端入口则在 page.tsx 中以CopilotKit runtimeUrl/api/copilotkit agentgen-ui-tool-based将页面绑定到对应 Agent。前置检查的意义在于将「环境故障」与「功能缺陷」隔离开避免在后端未就绪时把网络错误误判为 UI 缺陷。三、第一关基础功能验收Basic FunctionalityQA 文档将基础功能作为第一组测试步骤共 5 项全部通过勾选框- [ ]记录执行结果导航到 gen-ui-tool-based 演示页面验证CopilotSidebar默认打开标题为 Haiku Generator验证主区域显示一个占位的俳句卡片通过侧边栏发送一条基础消息验证 Agent 正常回复这组用例验证的是「最小可用闭环」页面能加载、预置 UI 能展示、消息能发出、Agent 能应答。在仓库的图表版实现中对应的预置 UI 是三条建议 pill见下文而 Agent 应答路径由 GenUiToolBasedFlow.chat() 驱动——它通过copilotkit_stream(acompletion(...))完成一次流式模型调用并把助手消息追加到状态。四、第二关功能特性专项检查Feature-Specific Checks这是整份 QA 文档的核心章节围绕生成式 UI 的三个关键能力展开建议按钮、前端工具渲染、多卡片堆叠。4.1 Suggestions建议按钮可见性验证 Nature Haiku 建议按钮可见验证 Ocean Haiku 建议按钮可见验证 Spring Haiku 建议按钮可见建议按钮用于降低用户输入门槛把高频意图固化为一条可点击的消息。仓库图表版通过 src/app/demos/gen-ui-tool-based/suggestions.ts 的useConfigureSuggestions注册了三条建议Sales bar chart、Traffic pie chart、Market share并设置available: always表示建议在会话全程常驻每条建议由title按钮文案与message点击后实际发送的消息组成。端到端测试 tests/e2e/gen-ui-tool-based.spec.ts 正是通过[data-testidcopilot-suggestion]定位器逐条断言这三个按钮可见与 QA 文档的勾选动作一一对应。4.2 Haiku 生成前端工具useFrontendTool渲染点击 Nature Haiku 建议按钮或输入 Write me a haiku about nature验证HaikuCard渲染data-testidhaiku-card并检查三行日文文本data-testidhaiku-japanese-line三行英文翻译data-testidhaiku-english-line卡片应用了背景渐变样式验证日文文本包含真实日文字符而非拉丁字母验证英文行是通顺可读的英文翻译这组用例是「工具型生成式 UI」的精髓UI 内容不是聊天文本而是由 Agent 调用的前端工具渲染出的组件。QA 文档通过data-testid锚点验证渲染结果的结构三行日文 三行英文 渐变背景并通过内容断言日文须为真日文、英文须可读验证模型输出质量。仓库图表版中对应机制由useComponent完成。以柱状图为例page.tsx 中注册useComponent({ name: render_bar_chart, description: Display a bar chart with labeled numeric values., parameters: barChartPropsSchema, render: BarChart, });组件参数用 Zod schema 声明见 bar-chart.tsx 中的barChartPropsSchematitle、description、data: {label, value}[]这为模型提供了结构化的工具契约。后端侧 gen_ui_tool_based.py 把state.copilotkit.actions直接作为toolsactions传入模型并在系统提示词中约束「用户要求图表时必须调用render_bar_chart或render_pie_chart数据不足时自行编造示例值并说明绝不反问用户」。4.3 Image Display图片渲染俳句生成后若 Agent 提供了image_name验证渲染出图片data-testidhaiku-image验证图片src指向/images/下、且文件名来自预定义列表该用例验证的是「条件渲染」分支工具返回参数中带有image_name时卡片额外渲染图片且图片来源被白名单约束仅允许预定义列表中的文件名这是对安全性与数据合法性的验收要求。4.4 Multiple Haikus多卡片堆叠生成第二条俳句例如 Ocean Haiku验证新俳句卡片出现在顶部验证之前的俳句卡片仍然显示在其下方验证初始占位俳句被移除该组用例验证会话内的状态累积与顺序语义新卡片置顶、旧卡片保留、占位卡片在首条真实结果出现后让位。这正是生成式 UI 与普通聊天流在状态管理上的差异点——Agent 多次工具调用产生的多份 UI 快照需要以「最新在上」的栈式布局呈现而不是互相覆盖。五、第三关错误处理与健壮性Error Handling发送空消息应被优雅处理正常使用过程中控制台无错误输出空消息与控制台报错是两类最常见的回归风险。QA 文档把它们单列为独立关卡说明验收不仅覆盖「Happy Path」还要覆盖输入边界与运行时稳定性。仓库端到端测试中与之对等的做法是每次交互后对助手消息容器[data-testidcopilot-assistant-message]做可见性断言确保即便异常输入也不会导致消息区挂起或白屏。六、预期结果与验收判定标准Expected ResultsQA 文档给出了明确的量化验收标准验收人员逐条对照判定通过与否验收项判定标准侧边栏加载3 秒内加载完成Agent 应答与俳句生成10 秒内完成俳句卡片内容同时显示日文与英文文本多俳句堆叠最新生成的俳句在顶部UI 稳定性无 UI 错误或布局破坏需要说明的是这些阈值是该项目针对自身环境的验收目标演示部署与模型响应延迟的综合预期并非框架层面的硬性承诺在复用此 QA 模板时应结合自己的部署环境校准超时。仓库 e2e 测试中使用了更长且分级的超时页面加载 10s、建议按钮 15s、图表 SVG 60s从侧面印证了「手工验收阈值」与「CI 自动化阈值」应分别设定的做法。七、从人工清单到自动化仓库中的可验证证据QA 文档是人工验收的执行脚本而仓库同时提供了自动化版本的对应实现两者断言的是同一套行为可以互相印证1. Playwright 端到端测试tests/e2e/gen-ui-tool-based.spec.ts 覆盖了 QA 文档的三大场景页面加载出聊天输入框与三条建议 pill对应「基础功能」「Suggestions」发送 Show me a pie chart of revenue by category断言助手消息中出现 SVG对应「工具渲染」发送 Show me a bar chart of monthly expenses断言柱状图 SVG对应「工具渲染」发送 Hello断言助手消息可见对应「Agent 响应」。2. 后端 Flow 注册src/agents/conversational_flows.py 中CONVERSATIONAL_FLOW_TYPES字典将gen-ui-tool-based映射到_conversational_type(GenUiToolBasedFlow)说明该演示由 CrewAI 原生会话式 Flow 变体承载并通过_AGUIConversationalBehavior将公开轮次路由到 Flow 的既有入口。3. 渲染组件bar-chart.tsx 与 pie-chart.tsx 定义了工具参数 schema 与渲染实现。它们都内置了「无数据」兜底卡片No data available这与 QA 文档「错误处理」关卡中「空消息应被优雅处理」的验收哲学一致组件在任何输入下都不应崩溃或产生布局破坏。4. 关联文档映射docs-links.json 将gen-ui-tool-based特性对接到 CopilotKit 官方文档的「Generative UI / Your Components / Display-Only」主题可作为理解该演示设计意图的入口。八、复用这份 QA 清单的实操建议按模块拆分执行基础功能第三节、特性专项第四节、健壮性第五节建议分轮执行避免一轮点击过多导致状态互相污染以data-testid为准绳所有 UI 断言都应落到文档给出的稳定锚点haiku-card、haiku-japanese-line、haiku-english-line、haiku-image等不要依赖视觉位置或样式类名这与仓库 e2e 使用copilot-suggestion、copilot-assistant-message的做法一致把人工清单「翻译」成自动化用例每个勾选项都可转换为一条 Playwright 断言——可见性、内容匹配、时序新卡片置顶与兜底分支无数据、空消息校准超时阈值手工验收的 3s/10s 阈值适合作为开发自测目标CI 中建议像仓库 e2e 那样为不同阶段设置分级的宽松超时页面 10s、交互 15s、渲染 60s环境先行任何一轮验收前先确认演示可访问、/api/health健康否则先修复环境再开始勾选避免无效的缺陷记录。将这套清单套用到仓库中其他生成式 UI 演示如 frontend-tools 的背景色切换工具时只需替换组件断言锚点与预期结果即可复用整套验收流程这也正是该 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），仅供参考