Langroid × CopilotKit 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/CopilotKitTool-Based Generative UI 是 CopilotKit 的核心能力之一后端 Agent 通过工具返回结构化数据前端将工具结果渲染为自定义 React 组件而不是普通文本。本文以 CopilotKit 仓库中 Langroid 集成的gen-ui-tool-based演示为对象完整讲解其人工验收QA流程、预期结果标准并结合演示页面、图表渲染组件、Agent 工具定义与 Playwright 端到端测试给出可复现的源码级验证依据。读完本文你将掌握如何系统验收一个工具驱动的生成式 UI演示并理解从 QA 清单到自动化测试的完整闭环。一、验收对象与环境前置条件gen-ui-tool-basedTool-Based Generative UI是 Langroid 集成 showcase 中的演示之一在 manifest.yaml 中登记为- id: gen-ui-tool-based name: Tool-Based Generative UI description: Agent uses tools to trigger UI generation tags: - generative-ui route: /demos/gen-ui-tool-based highlight: - src/agents/agent.py - src/app/demos/gen-ui-tool-based/page.tsx - src/app/api/copilotkit/route.ts演示的运行原理可概括为参见 gen-ui-tool-based/README.mdAgent 调用后端工具返回结构化数据前端把工具结果渲染为自定义 React 组件useRenderTool将每个工具名映射到一个渲染器渲染器接收args、result、status三个入参因此 UI 可以同时呈现加载态与完成态。在开始任何验收动作之前需确认以下前置条件这也是 QA 清单 的第一步前置条件验证方式演示已部署且可访问浏览器打开 demo 路由页面正常加载Agent 后端健康请求/api/health返回健康状态无 5xx后端的健康检查与 CopilotKit 运行时路由对应 src/app/api/copilotkit/route.ts页面通过runtimeUrl/api/copilotkit接入该运行时见下文演示源码。二、基础功能验收页面加载与首次交互按 QA 清单基础功能验证包含以下检查点导航到gen-ui-tool-based演示页面确认侧边栏默认打开确认主区域显示了占位卡片placeholder card通过侧边栏发送一条基础消息确认 Agent 正常回复。对应到当前仓库实现页面源码 page.tsx 的布局非常精简——聊天表面即页面本身export default function ControlledGenUiDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentgen-ui-tool-based Chat / /CopilotKit ); }CopilotKit组件声明运行时地址与目标 Agent 名agentgen-ui-tool-basedCopilotChat则直接作为全屏聊天界面agentId与后端 Agent 一一对应。E2E 测试 gen-ui-tool-based.spec.ts 对页面加载 发送消息给出了自动化断言test(sends message and gets assistant response, async ({ page }) { const input page.locator(textarea, [placeholder*message]).first(); await input.fill(Hello); await input.press(Enter); await expect( page.locator([data-testidcopilot-assistant-message]).first(), ).toBeVisible({ timeout: 30000 }); });人工验收与自动化测试相互印证只要textarea输入框可见、回车后 30 秒内出现 assistant 消息节点即可判定基础链路通过。说明QA 清单中Haiku Generator 标题、CopilotSidebar、占位 haiku 卡片等描述源自俳句haiku场景的验收模板当前仓库的gen-ui-tool-baseddemo 实现为图表渲染场景柱状图/饼图但其验证思路与检查点结构完全一致——均围绕侧边栏建议 → 触发工具 → 渲染结构化 UI展开。下文将分别给出 QA 模板检查项与其在图表实现中的对应断言。三、建议Suggestions功能验收QA 清单要求验证建议按钮的可见性。在俳句场景模板中对应 Nature Haiku / Ocean Haiku / Spring Haiku 三个建议按钮在当前图表 demo 中三个建议由 suggestions.ts 通过useConfigureSuggestions注入export function useSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Sales bar chart, message: Show me a bar chart of quarterly sales for Q1, Q2, Q3, Q4., }, { title: Traffic pie chart, message: Show me a pie chart of website traffic by source., }, { title: Market share, message: Show a pie chart of smartphone market share by brand., }, ], available: always, }); }验收要点每个建议都应同时具备title按钮显示文本与message点击后填充/发送的实际消息二者可以不同——title面向展示message是真正发给 Agent 的指令available: always表示建议在任何对话阶段都可用与之相对的是仅在特定上下文出现的条件建议。E2E 对三个建议按钮的可见性断言如下for (const title of [Sales bar chart, Traffic pie chart, Market share]) { await expect( page.locator([data-testidcopilot-suggestion]) .filter({ hasText: title }), ).toBeVisible({ timeout: 15000 }); }人工验收时只需点击建议或手动输入等价指令观察聊天输入框与页面布局是否正常响应。四、核心功能验收工具驱动的 UI 渲染这是本演示的核心验证点。QA 清单要求点击建议或输入生成指令后渲染出带有指定data-testid的卡片如haiku-card卡片内容结构完整俳句模板中为三行日文haiku-japanese-line 三行英文haiku-english-line并应用背景渐变样式内容本身符合语义日文包含真实日文字符而非拉丁字母、英文为可读翻译。在当前图表实现中前端通过useComponent注册工具渲染器见 page.tsxuseComponent({ name: render_bar_chart, description: Display a bar chart with labeled numeric values., parameters: barChartPropsSchema, render: BarChart, }); useComponent({ name: render_pie_chart, description: Display a pie chart with labeled numeric values., parameters: pieChartPropsSchema, render: PieChart, });useComponent的四个关键入参参数作用本 demo 中的取值name工具名必须与后端 Agent 的工具调用名一致是前后端契约的键render_bar_chart/render_pie_chartdescription给 LLM 看的语义描述帮助模型决定何时调用如 Display a bar chart with labeled numeric values.parametersZod schema约束工具参数的形状与字段说明barChartPropsSchema/pieChartPropsSchemarender接收工具结果的 React 渲染组件BarChart/PieChart参数 schema 由 Zod 定义并通过z.infer导出组件 Props 类型见 bar-chart.tsxexport const barChartPropsSchema z.object({ title: z.string().describe(Chart title), description: z.string().describe(Brief description or subtitle), data: z.array( z.object({ label: z.string(), value: z.number(), }), ), }); export type BarChartProps z.infertypeof barChartPropsSchema;前端验收对照图表组件内嵌在 assistant 消息节点中E2E 测试对饼图请求渲染出 SVG的断言是对应卡片渲染 结构完整的检查点const assistantMessage page .locator([data-testidcopilot-assistant-message]) .first(); await expect(assistantMessage.locator(svg).first()).toBeVisible({ timeout: 60000, });同时建议核对图表的空数据分支两个图表组件都实现了data缺失或空数组时的降级 UINo data available这对应 QA 清单中无 UI 错误或布局破损的验收项。后端工具定义Agent 侧在 src/agents/agent.py 中定义同名工具并通过 CopilotKit 运行时将工具调用转发给前端——该文件注释明确说明这一链路intercepts the call and forwards it to the frontendsuseFrontendTool参见 agent.py 附近。也就是说后端工具返回的title/description/data结构化结果最终由前端注册的 React 组件接管渲染这正是Tool-Based Generative UI与纯文本回复的本质区别。五、图片与多结果堆叠验收QA 清单还包含两个交互细节图片显示生成结果后若 Agent 提供了image_name字段应渲染图片节点如data-testidhaiku-image且src应指向/images/下预定义文件列表中的有效文件名——即图片必须是白名单内的资源防止任意路径注入多结果堆叠连续生成第二个结果后新卡片应出现在顶部旧卡片仍在下方可见同时初始的占位卡片被移除——即newest on top的列表语义。这类多条工具结果在会话中累积堆叠的行为本质上是生成式 UI 与对话上下文共存的体现每条工具调用产出一个独立渲染节点随消息流追加。人工验收时应连续触发两次不同建议检查新旧渲染节点是否共存且顺序正确新在上占位/初始状态是否被正确替换每条结果的数据是否与当次请求对应避免串数据。六、错误处理验收QA 清单的错误处理检查点发送空消息应被优雅处理不崩溃、不报错、给出合理反馈正常使用全程无 console 错误。从实现侧可以推断出三处对应的保障机制空数据降级两个图表组件的data.length 0分支渲染占位文案即使后端返回空数据集UI 也不会渲染出破碎的图表见 bar-chart.tsx非法数值容错饼图组件对所有Number(value) || 0做了兜底避免脏数据导致 NaN 或除零见 pie-chart.tsx加载/完成状态useRenderTool的渲染器接收status参数可以在数据到达前展示加载态从而避免点击建议后界面无响应的观感。验收时应同时开启浏览器 DevTools Console 面板全程观察是否有未捕获异常或网络错误。七、预期结果与验收标准汇总QA 清单给出的最终验收标准如下可直接作为发布门禁验收项标准侧边栏加载3 秒内完成Agent 响应与内容生成10 秒内完成卡片内容双语/结构化内容完整日文英文或图表标题数据多结果顺序最新生成的在最上方历史结果保留UI 稳定性无 UI 错误、无布局破损需要说明的是这些时限是经验性验收阈值实际表现受模型延迟、网络与运行时负载影响。若要将其固化为可重复的自动化验证可直接复用仓库中的 Playwright 测试 tests/e2e/gen-ui-tool-based.spec.ts它已覆盖四个核心场景页面加载与建议可见、饼图 SVG 渲染、柱状图 SVG 渲染、消息收发。人工 QA 与 E2E 结合即可对 Tool-Based Generative UI 形成功能 → 渲染 → 错误处理 → 性能的完整验收闭环。八、关键文件索引文件作用qa/gen-ui-tool-based.md本文所依据的 QA 验收清单src/app/demos/gen-ui-tool-based/page.tsx演示页面useComponent注册与聊天界面组装src/app/demos/gen-ui-tool-based/suggestions.ts建议按钮配置src/app/demos/gen-ui-tool-based/bar-chart.tsx柱状图渲染组件Recharts Zod schemasrc/app/demos/gen-ui-tool-based/pie-chart.tsx饼图渲染组件SVG 环形图src/agents/agent.py后端 Agent工具调用经运行时转发至前端useFrontendTooltests/e2e/gen-ui-tool-based.spec.ts对应 QA 清单的 Playwright 自动化测试manifest.yamldemo 在 showcase 中的登记信息【免费下载链接】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），仅供参考