CopilotKit × CrewAI 集成的 Tool-Based Generative UI 端到端 QA 验证指南
CopilotKit × CrewAI 集成的 Tool-Based Generative UI 端到端 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本指南围绕 CopilotKit 仓库中 crewai-crews 集成的 Tool-Based Generative UI QA 文档 展开系统讲解由 Agent 通过工具Frontend Tool触发前端渲染这一生成式 UI 模式的完整验收流程从前置环境检查、三步测试清单基本功能 → 特性验证 → 错误处理到可量化的预期结果。读完本文你将能够独立执行这套 QA 流程并理解每个断言背后对应的源码实现链路React 端渲染器注册、建议按钮注入、CrewAI Flow 后端与 AG-UI 代理。前置条件QA 可复现的环境基线执行任何测试步骤之前需要先确认两条硬性前置条件缺一不可Demo 已部署且可通过浏览器访问即gen-ui-tool-based演示页面路由/demos/gen-ui-tool-based处于可访问状态。Agent 后端健康检查/api/health返回正常。这两条条件在当前仓库中都有对应的代码证据。前端运行时路由 src/app/api/copilotkit/route.ts 提供了GET /api/copilotkit健康探针它会以 3 秒超时探测后端AGENT_URL默认http://localhost:8000的/health并返回agent_url与agent_statusreachable/unreachable/error。后端侧src/agent_server.py 中的HealthMiddleware为/health单独返回{status: ok}与任何 Agent 端点解耦保证健康检查不会被具体业务端点拖累。建议在执行测试前先访问健康探针确认agent_status为reachable否则后续所有断言都会因后端不可达而失败。测试步骤总览QA 文档将验收拆解为三个递进阶段基本功能页面加载、Sidebar 默认打开、消息往返是否正常特性验证建议按钮、俳句卡片渲染、图片显示、多卡片堆叠行为错误处理空消息等边界输入、控制台是否有异常。下面按阶段逐条展开每条对应一个可勾选的检查项。阶段一基本功能验证导航到gen-ui-tool-baseddemo 页面验证 CopilotSidebar 默认打开标题为Haiku Generator验证主区域显示一张占位的俳句卡片通过 Sidebar 发送一条基础消息验证 Agent 正常回复。这一阶段验证的是能聊起来的最小闭环。需要注意的是本 QA 文档是多个集成仓库共享的通用验收模板langgraph-python、pydantic-ai、mastra、claude-sdk-python等集成目录下均有同名 qa/gen-ui-tool-based.md因此它以俳句生成器Haiku Generator作为示例业务。而当前 crewai-crews 集成中实际落地的是数据可视化形态Demo 页面使用居中的CopilotChat而非 Sidebar见 src/app/demos/gen-ui-tool-based/page.tsx。验证时可把文档中的俳句卡片对应替换为当前 Demo 的图表卡片验收逻辑完全一致——都是Agent 调用工具后前端把工具参数渲染成结构化 UI。阶段二特性验证这是整套 QA 的核心验证 Tool-Based Generative UI 区别于普通聊天的关键能力。Suggestions建议按钮页面上可见 Nature Haiku 建议按钮可见 Ocean Haiku 建议按钮可见 Spring Haiku 建议按钮。建议按钮由前端通过useConfigureSuggestions声明式注入。crewai-crews 集成中的对应实现位于 src/app/demos/gen-ui-tool-based/suggestions.ts它注册了 Sales bar chart、Traffic pie chart、Market share 等建议项每项包含title按钮文案与message点击后发送的消息。e2e 测试 tests/e2e/gen-ui-tool-based.spec.ts 正是通过[data-testidcopilot-suggestion]定位并断言这些按钮逐个可见。Haiku 生成useFrontendTool点击 Nature Haiku 建议或输入 Write me a haiku about nature验证渲染出 HaikuCarddata-testidhaiku-card且包含三行日文文本data-testidhaiku-japanese-line三行英文翻译data-testidhaiku-english-line卡片应用了背景渐变样式验证日文文本包含真实日文字符而非拉丁字符验证英文行是可读的英文翻译。这一节的本质是验证前端工具结果被渲染成 React 组件这一核心链路Agent 侧调用前端注册的工具useFrontendTool工具结果流回浏览器后由前端组件把结构化参数渲染为卡片。三个data-testid是渲染器与测试之间的契约——验证时必须同时断言结构3 行日文 3 行英文、内容语义日文真实非拉丁、英文可读与视觉样式渐变背景。在 crewai-crews 的当前 Demo 中等价断言对象是render_bar_chart/render_pie_chart两个注册的渲染器及其渲染出的 SVG 图表bar-chart.tsx 与 pie-chart.tsxe2e 测试通过[data-testidcopilot-assistant-message]内部出现svg来断言图表渲染成功。图片显示俳句生成后若 Agent 提供了image_name验证渲染出图片data-testidhaiku-image验证图片src指向/images/路径且文件名来自预定义列表。该检查项验证可选字段的渲染能力image_name并非每次工具调用都会返回因此是条件断言。测试人员需要核对src是否落在预定义的白名单文件列表内防止 Agent 编造不存在的图片路径。多张俳句卡片堆叠生成第二首俳句例如 Ocean Haiku验证新卡片出现在顶部验证上一张卡片仍在其下方可见验证初始的占位俳句卡片已被移除。这条验证的是列表状态管理语义最新生成的卡片以置顶newest on top方式插入历史卡片保留占位卡在首张真实卡片出现后即被替换删除。这与普通聊天消息流向下追加的直觉不同是生成式 UI 应用中常见的数据展示模式需要作为独立断言单独验证避免只测单次渲染就放行。阶段三错误处理发送一条空消息应被优雅处理不产生报错正常使用过程中浏览器控制台无报错。空消息属于客户端输入校验范畴应在发送前被拦截或静默处理控制台无报错则是对整条链路前端渲染器、AG-UI 事件流、后端响应解析的全局兜底检查。建议在阶段一和阶段二的全过程中保持控制台打开把错误观察贯穿始终而不是最后才单独检查。预期结果可量化的验收标准QA 文档给出了四组可量化的验收标准验收项指标Sidebar 加载3 秒内完成Agent 响应并生成俳句10 秒内完成俳句卡片显示同时包含日文与英文文本卡片堆叠行为最新卡片在最上方界面健壮性无 UI 错误、无布局破损这组指标既是对阶段二、阶段三所有检查项的汇总也是性能与健壮性的最低门槛。值得说明的是e2e 测试实际给了更宽松的超时余量Playwright 测试中页面加载等待 10 秒、建议按钮等待 15 秒、消息往返等待 30 秒、SVG 图表渲染等待 60 秒见 tests/e2e/gen-ui-tool-based.spec.ts。QA 文档的 3 秒 / 10 秒可视为体感目标e2e 的超时则是避免 flaky 测试的工程余量两者并不矛盾。从源码看实现QA 断言背后的调用链理解 QA 断言背后为什么这样验证才能在执行中准确判断失败原因。当前仓库中这条链路共三层第一层前端渲染器注册。page.tsx 中通过useComponent({ name, description, parameters, render })注册render_bar_chart与render_pie_chartname是暴露给 Agent 的工具名description指导模型何时调用parameters是 JSON SchemabarChartPropsSchema/pieChartPropsSchemarender是真正的 React 渲染组件。QA 中的data-testidhaiku-card即对应这类渲染器在测试中的锚点。第二层建议按钮注入。suggestions.ts 通过useConfigureSuggestions一次性注入多条建议对应 QA 中的 Nature Haiku 等建议按钮断言。第三层CrewAI Flow 后端。该 Demo 没有复用中立的/chatFlow而是拥有专属后端 src/agents/gen_ui_tool_based.py。它的关键设计是系统提示词把 Agent 定位为数据可视化助手指导它在用户请求图表时直接调用render_bar_chart/render_pie_chart并自行生成示例数据绝不反问用户要数据同时通过tool_choicerequired当上一条消息来自用户且存在可用工具时强制第一轮必须调用图表工具待浏览器返回渲染结果后的后续轮次再回到auto进行纯叙述收尾——这正是 QA 中Agent 必须在 10 秒内生成俳句卡片这一断言得以成立的后端保障。前端与后端的桥接则依赖 route.ts 中agents[gen-ui-tool-based] createAgent(/gen-ui-tool-based)的 AG-UI 代理注册后端端点由 agent_server.py 的add_crewai_flow_fastapi_endpoint(app, gen_ui_tool_based_flow, /gen-ui-tool-based)挂载。小结如何复用这套 QA 清单这份 QA 文档的价值在于它是一套可移植的生成式 UI 验收模板无论业务是俳句生成还是图表渲染验证维度都是固定的五件事——入口加载、建议按钮、工具触发的组件渲染含结构 / 语义 / 样式断言、可选字段渲染、多卡片堆叠更新。对 crewai-crews 集成而言把文档中的 HaikuCard 断言替换为图表 SVG 断言即可与本仓库的 e2e 测试 以及 manifest.yaml 中声明的gen-ui-tool-basedTool-Based Generative UIDemo 能力一一对应。将文档化 QA 与自动化 e2e 结合使用就能在发布前同时覆盖人工体验验收与回归防线两条路径。【免费下载链接】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），仅供参考