CopilotKit × Google ADK 实战：Tool-Based Generative UI（gen-ui-tool-based）端到端 QA 测试指南

CopilotKit × Google ADK 实战Tool-Based Generative UIgen-ui-tool-based端到端 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 仓库中 Google ADK 集成示例的官方 QA 文档showcase/integrations/google-adk/qa/gen-ui-tool-based.md系统讲解 Tool-Based Generative UI工具驱动型生成式 UI演示的完整验收测试流程。文章会逐条拆解 QA 清单中的前置条件、功能测试与预期结果并结合仓库内的 Agent 源码、前端注册代码与 Playwright E2E 测试说明每一步该验证什么、为什么这样验证帮助测试工程师与开发者快速掌握Agent 调用工具 → 前端把工具结果渲染为自定义 React 组件这一核心交互的验收方法。一、被测对象gen-ui-tool-based 演示是什么在开始执行 QA 清单之前先理解被测页面。gen-ui-tool-basedTool-Based Generative UI是 Google ADK 集成演示之一其核心思想是Agent 调用一个后端工具工具返回结构化数据前端把工具结果渲染为自定义 React 组件而不是普通文本。仓库的展示清单 manifest.yaml 中对该演示的定义如下名称Tool-Based Generative UI描述Agent uses tools to trigger UI generationAgent 使用工具触发 UI 生成标签controlled-generative-ui路由/demos/gen-ui-tool-based高亮源码文件src/agents/gen_ui_tool_based_agent.py后端 Agentsrc/app/demos/gen-ui-tool-based/page.tsx前端页面src/app/api/copilotkit/route.ts运行时代理从源码结构看该演示的工具驱动体现在两个层面前端page.tsx通过copilotkit/react-core/v2的useComponent注册了两个前端工具useComponent({ 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, });后端gen_ui_tool_based_agent.py是一个基于 Google ADKLlmAgent的数据可视化助手gen_ui_tool_based_agent LlmAgent( nameGenUiToolBasedAgent, modelget_model(), instruction_INSTRUCTION, tools[AGUIToolset()], after_model_callbackstop_on_terminal_text, )其中的AGUIToolset()会把前端注册的工具注入到模型的每次请求中让 Agent 在运行时看得到、调得动这些渲染工具after_model_callbackstop_on_terminal_text则是防止 Gemini 在工具调用成功后无限循环重发同一工具调用的终止保护详见 shared_chat.py。Agent 的指令_INSTRUCTION对图表工具的使用做了明确约定用户请求图表时调用render_bar_chart或render_pie_chart传入简短的标题、描述以及{label, value}形式的数据数组小规模类别间的比较用柱状图整体构成 / 占比用饼图若用户只给了图表主题而没有具体数字例如按来源展示网站流量饼图不要反问用户要数据而是自行编造合理的示意性样例值立即渲染图表并在回复中注明数据是示意性的保持聊天回复简短让图表本身说话。也就是说QA 清单验证的本质是前端注册的工具声明 → ADK 中间件注入 → 模型调用工具 → 前端按工具名渲染对应 React 组件这条完整链路是否通畅。二、前置条件演示部署与后端健康检查QA 文档要求执行测试前满足两个前置条件Demo 已部署且可访问即能打开/demos/gen-ui-tool-based页面。Agent 后端健康检查/api/health。这两个条件在仓库中都有对应的实现依据。/api/health端点在 src/app/api/copilotkit/route.ts 中实现它返回{ status: ok, agent_url: http://localhost:8000, agent_status: reachable, agent_count: 47, env: { GOOGLE_API_KEY: set, NODE_ENV: development } }其中agent_status是对后端AGENT_URL/health的实际探活结果超时 3 秒GOOGLE_API_KEY字段用于确认 Gemini 凭据是否已配置。如果GOOGLE_API_KEY显示为NOT SET或agent_status为unreachable则测试不会通过应先修复后端。后端健康检查还有一层Python 侧 agent_server.py 通过HealthMiddleware在路由解析前直接短路返回/health确保即使某个 Agent 挂载异常健康探针依然可达。建议在浏览器中打开/api/health确认上述 JSON 返回后再开始执行功能测试这能提前隔离前端问题与后端问题。三、基础功能测试页面加载与基本对话QA 文档的第一步是验证页面基础功能导航到 gen-ui-tool-based 演示页面验证 CopilotSidebar 默认打开标题为 Haiku Generator验证主区域显示占位俳句卡片通过侧边栏发送一条基础消息验证 Agent 有响应需要特别说明的是QA 文档中关于 Haiku Generator 侧边栏、占位俳句卡片的描述与当前仓库源码已不一致。从源码看该演示页面如今没有侧边栏而是渲染一个居中的CopilotChat聊天组件见 page.tsxreturn ( div classNameflex justify-center items-center h-screen w-full div classNameh-full w-full max-w-4xl CopilotChat agentIdgen-ui-tool-based classNameh-full rounded-2xl / /div /div );同时仓库中的共享探针测试 d5-gen-ui-custom.test.ts 明确记载旧版的generate_haiku/ HaikuCard 路径已被移除全部 21 个 gen-ui-tool-based 页面现在统一注册render_bar_chartrender_pie_chart共享契约就是饼图契约。因此执行本条测试时应按当前实现验证打开/demos/gen-ui-tool-based页面加载一个居中的CopilotChat聊天界面无侧边栏/无页头装饰消息输入框可见textarea 或含 message placeholder 的输入控件发送一条基础消息如 Hello验证 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 }); });四、特性专项检查4.1 Suggestions建议提示QA 文档要求验证 Nature Haiku、Ocean Haiku、Spring Haiku 三个建议按钮可见。当前实现中建议按钮由 suggestions.ts 通过useConfigureSuggestions配置主题已从俳句替换为图表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, });对应测试步骤按当前实现调整验证 Sales bar chart 建议按钮可见验证 Traffic pie chart 建议按钮可见验证 Market share 建议按钮可见E2E 测试 gen-ui-tool-based.spec.ts 对建议按钮的断言使用选择器[data-testidcopilot-suggestion]并按标题文本过滤可作为手工测试时定位元素的参考。4.2 工具驱动的图表生成核心链路QA 文档的本节标题为 Haiku Generation (useFrontendTool)期望点击建议按钮后渲染一张data-testidhaiku-card的卡片内含三行日文haiku-japanese-line与三行英文haiku-english-line。与 4.1 同理当前实现已从俳句生成演化为图表渲染Agent 通过工具调用返回结构化数据前端将其渲染为 SVG 图表组件。点击 Traffic pie chart 建议或直接输入 Show me a pie chart of revenue by category后应当验证助理消息内渲染出 SVG 可视化饼图/环形图图表包含标题与描述文本图例区域展示各分片的标签、数值与百分比Agent 的随附文字简述了图表结论例如哪个类别占比最大两个渲染组件的实现细节值得测试时留意饼图 pie-chart.tsx纯 SVG 手绘环形图通过strokeDasharray/strokeDashoffset计算每个扇区颜色取自固定调色板数据为空时展示 No data available 的空态卡片。柱状图 bar-chart.tsx基于 Recharts 的ResponsiveContainer柱体高度 280px带有barSlideIn入场动画——只有新到达的柱子才播放动画通过useRef记录已渲染索引。两组件的 props 均由 zod schema 约束title、description、data: {label, value}[]这就是 Agent 必须返回的结构化数据契约export const pieChartPropsSchema 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(), }), ), });E2E 对图表渲染的断言方式gen-ui-tool-based.spec.tstest(pie chart request renders SVG visualization, async ({ page }) { const input page.locator(textarea, [placeholder*message]).first(); await input.fill(Show me a pie chart of revenue by category); await input.press(Enter); const assistantMessage page .locator([data-testidcopilot-assistant-message]) .first(); await expect(assistantMessage.locator(svg).first()).toBeVisible({ timeout: 60000, }); });4.3 多张图表的堆叠与替换QA 文档要求生成第二首俳句后新卡片出现在顶部、旧卡片仍保留在下方、初始占位卡片被移除。对应到当前图表实现生成第一张图表如 Sales bar chart确认图表卡片出现再生成第二张图表如 Traffic pie chart确认新的图表卡片出现在消息流顶部确认上一条图表消息仍在其下可见历史消息不被清除确认初始的占位内容如果有已被移除这一行为本质上是聊天消息流本身的追加语义——每条工具渲染结果附着在对应助理消息中新消息追加在顶部旧消息保留。手工测试时重点观察消息顺序与组件是否随消息一起持久化。4.4 空消息与错误处理QA 文档的错误处理部分发送空消息应被优雅处理不崩溃、不报错正常使用过程中控制台无报错no console errors执行建议在输入框为空时直接按回车确认界面不抛异常、不出现未捕获的错误打开浏览器 DevTools Console在完成一次完整的发消息 → 生成图表流程后检查是否有红色错误输出服务端侧的错误会被 route.ts 记录为含errorId的结构化日志且不会把内部堆栈回显给客户端——若控制台出现internal runtime error响应可到服务端日志按errorId关联排查。五、预期结果与验收标准QA 文档给出的最终验收标准如下预期结果说明侧边栏 3 秒内加载当前实现为聊天界面可理解为页面与聊天组件在 3 秒内就绪Agent 10 秒内响应并生成俳句当前实现为 10 秒内响应并渲染图表俳句卡片同时显示日文与英文当前实现为图表卡片正确渲染标题/描述/数据生成的俳句按最新在上堆叠当前实现为多条图表消息按最新在上堆叠无 UI 错误或布局破损无报错、无错位、无空态异常其中10 秒内响应与60 秒内图表可见的时间口径在 E2E 测试中也有体现助理消息可见的超时设置为 30000msgen-ui-tool-based.spec.tsSVG 图表可见的超时设置为 60000ms同文件 L41-L43。手工测试时可参考这些阈值判断慢是 Agent 推理慢还是链路故障。六、QA 文档与当前实现的差异说明重要由于 qa/gen-ui-tool-based.md 中多处描述Haiku Generator 侧边栏、Nature/Ocean/Spring 俳句建议、haiku-card、haiku-japanese-line、haiku-english-line、haiku-image、/images/图片渲染与仓库当前源码不一致特此汇总差异清单避免测试者按过时步骤误判QA 文档描述当前源码实现依据CopilotSidebar标题 Haiku Generator居中的CopilotChat聊天界面page.tsxNature/Ocean/Spring 俳句建议Sales bar chart / Traffic pie chart / Market sharesuggestions.tsuseFrontendTool生成俳句卡片Agent 调用render_bar_chart/render_pie_chart前端渲染 SVG 图表gen_ui_tool_based_agent.pyhaiku-image图片渲染无图片渲染逻辑源码无/images/图片引用俳句卡片日文/英文行图表的标题、描述、图例pie-chart.tsx这一差异也得到仓库探针测试的佐证d5-gen-ui-custom.test.ts 明确指出旧generate_haiku路径is GONE所有集成统一走饼图契约且探针断言要求渲染出svg且 SVG 绘制子元素数量健康5 个 circle对应环形图扇区。七、如何复用这套 QA 方法论7.1 自动化层面两条可复用的验证路径仓库为这个演示提供了两层自动化验证手工 QA 之外可以对照使用集成级 E2Etests/e2e/gen-ui-tool-based.spec.tsPlaywright 驱动真实页面验证页面加载、三个建议按钮、饼图/柱状图 SVG 渲染、基础对话四条用例。跨集成探针d5-gen-ui-custom.test.ts作为所有集成的共享契约固定发送 Show me a pie chart of revenue by category断言 SVG 形状与助理回复中的关键 token如提及占比最大的类别防止某个集成在图表渲染上退化。7.2 测试视角本用例覆盖的验收要点从测试设计角度本 QA 清单实际覆盖了工具驱动型生成式 UI 的五个关键风险点工具注册与注入前端useComponent注册的工具名能否被后端AGUIToolset()注入到模型请求对应 4.1/4.2 的建议与生成用例结构化参数契约zod schema 定义的{title, description, data}能否被 Agent 正确填满对应 4.2 的图表内容校验渲染状态工具结果从调用中到渲染完成的状态切换是否正确README 提到useRenderTool会把args、result、status传给渲染器以展示加载与完成态参见 gen-ui-tool-based/README.md消息流语义多轮工具渲染结果的堆叠与顺序对应 4.3健壮性空输入、异常路径不产生崩溃与控制台错误对应 4.4。对于想要在自建项目上复刻该模式的开发者后端设置可参考 docs/setup/frontend-tools-setup.mdx其中给出了AGUIToolset()的接入方式与完整的stop_on_terminal_text终止回调实现——这是让 Gemini 在工具调用后正确结束 agentic loop 的关键一环前端则只需像本文 4.1/4.2 所示用useComponent注册工具并绑定 React 渲染组件即可。结语Tool-Based Generative UI 是 CopilotKit 生成式 UI 体系中最经典的一条实现路径Agent 不直接生成界面而是调用工具、返回结构化数据由前端把数据渲染成丰富的自定义组件。本文以 Google ADK 集成的官方 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），仅供参考