CopilotKit Tool-Based Generative UI 功能验证指南：AG2 集成场景下的端到端 QA 清单与实践-北京尧图网络

CopilotKit Tool-Based Generative UI 功能验证指南AG2 集成场景下的端到端 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 在 AG2 集成示例showcase/integrations/ag2中Tool-Based Generative UI功能的专项验证指南。文档以仓库中的 QA 检查清单 gen-ui-tool-based.md 为核心骨架逐一展开前置条件、功能测试步骤与验收标准并结合当前仓库的前端注册、后端工具链与 Playwright 自动化测试说明如何在真实运行环境中验证Agent 调用工具返回结构化数据、前端将其渲染为自定义 React 组件这一完整链路。读完本文你将掌握一套可直接照做的 Tool-Based Generative UI 手动验收流程以及仓库中对应的自动化验证手段。一、被测功能Tool-Based Generative UI 是什么按 demo 目录内的开发说明该功能的定义非常清晰Agent 调用一个后端工具工具返回结构化数据前端不再把结果渲染成纯文本而是将工具结果渲染为自定义 React 组件。也就是说这是一个工具调用驱动 UI 生成Agent uses tools to trigger UI generation见 manifest.yaml 中的 demo 描述的典型场景数据逻辑留在后端工具里展示形态完全由前端组件决定。需要特别指出的是当前仓库中gen-ui-tool-baseddemo 的实际实现是柱状图 / 饼图渲染见下文实现对照章节而 QA 清单文档描述的检查项Haiku 生成器、haiku-card等对应的是该 demo 早期迭代版本的功能形态。因此本文以 QA 清单的骨架为准组织验证流程并同步给出与当前仓库实现一一对应的验证要点确保清单既忠实继承、又能在最新代码上落地。二、前置条件PrerequisitesQA 清单要求的运行前提有两条缺一不可Demo 已部署且可访问/demos/gen-ui-tool-based页面能正常打开侧边栏/聊天界面加载成功。对应路由入口为 gen-ui-tool-based/page.tsx并在 manifest.yaml 中注册路由路径为/demos/gen-ui-tool-based。Agent 后端健康检查/api/health。该健康探针由 copilotkit/route.ts 中的 GET 处理器实现它除了返回status: ok外还会实际请求${AGENT_URL}/health默认http://localhost:8000以 3 秒超时探测 Agent 进程并把agent_statusreachable/error (xxx)/unreachable (...)与OPENAI_API_KEY是否配置一并返回方便定位是前端路由问题还是后端 Agent 失联。网络拓扑提示从 route.ts 注释与初始化代码可知Agent 后端作为独立进程运行在 8000 端口Next.js 的/api/copilotkit路由通过HttpAgentAG-UI 协议客户端将请求代理到该后端。gen-ui-tool-based被注册在共享 Agent 名单sharedAgentNames中见 route.ts 第 35-56 行即它与多数 demo 复用同一个 AG2ConversableAgent后端实例。三、测试步骤详解3.1 基础功能Basic Functionality按清单逐项执行导航到gen-ui-tool-baseddemo 页面当前实现为/demos/gen-ui-tool-based页面是一个居中铺满的聊天界面无额外页头装饰见 page.tsx。验证聊天侧边栏/面板默认打开。在当前实现中聊天区域通过CopilotChat agentIdgen-ui-tool-based /挂载并用CopilotKit外层组件声明runtimeUrl/api/copilotkit、agentgen-ui-tool-basedpage.tsx 第 37-49 行。QA 清单记载的是早期版本行为侧边栏默认打开标题为Haiku Generator主区域显示一个占位 haiku 卡片。当前仓库实现中该标题/占位卡片已被移除验证时应以实际页面渲染为准。通过侧边栏发送一条基础消息。验证 Agent 有响应出现 Assistant 消息气泡。3.2 Suggestions建议按钮清单要求验证三个建议按钮可见。注意QA 文档列出的三个建议是历史版本的Nature Haiku/Ocean Haiku/Spring Haiku当前实现中建议内容已更新为图表场景的三个按钮见 suggestions.tsSales bar chart→ 消息Show me a bar chart of quarterly sales for Q1, Q2, Q3, Q4.Traffic pie chart→ 消息Show me a pie chart of website traffic by source.Market share→ 消息Show a pie chart of smartphone market share by brand.实现方式是通过useConfigureSuggestions注册建议available: always表示常驻展示suggestions.ts 第 6-22 行。点击建议按钮等价于直接发送对应消息可作为后续步骤的快捷入口。3.3 生成验证从工具调用到组件渲染这是 Tool-Based Generative UI 的核心检查点QA 清单要求验证点击建议按钮或手动输入生成请求清单原文示例Write me a haiku about nature当前实现对应为Show me a bar chart of .../Show me a pie chart of ...。验证结构化卡片渲染成功QA 清单历史版本形态HaikuCard渲染成功data-testidhaiku-card内含三行日文原文data-testidhaiku-japanese-line、三行英文译文data-testidhaiku-english-line且卡片应用了背景渐变样式日文必须是真实日文字符不能是拉丁字符英文需为可读的翻译。当前实现形态图表组件渲染进 Assistant 消息内。柱状图/饼图组件各自定义了 Zod schemabarChartPropsSchema/pieChartPropsSchema字段为title、description、data[{label, value}]见 bar-chart.tsx 第 15-24 行与 pie-chart.tsx 第 4-13 行。数据为空时组件会渲染 No data available 占位卡片属于合法的降级表现。验证渲染内容与结构化数据一致数值标签正确、图表可读。底层机制前端通过useComponent注册组件名 → React 组件参数 schema如 page.tsx 第 14-30 行注册了render_bar_chart与render_pie_chart两个组件useComponent({ name: render_bar_chart, description: Display a bar chart with labeled numeric values., parameters: barChartPropsSchema, render: BarChart, });后端侧Agent 通过generate_a2ui工具在对话中生成 A2UI 组件结构与数据agent.py 第 140-219 行它把用户消息作为上下文调用gpt-4.1并强制其输出render_a2ui工具调用再经build_a2ui_operations_from_tool_call组装为 a2ui_operations 容器返回。前端拿到结构化结果后按name匹配到已注册的 React 组件完成渲染。开发说明中提到的useRenderTool按工具名映射渲染器渲染器接收args、result、status以展示 loading 与完成态是同族 API 的另一种形态验证时可根据版本选择。3.4 图片显示Image DisplayQA 清单要求haiku 生成后若 Agent 提供了image_name应渲染一张图片data-testidhaiku-image且src指向/images/下的预置文件名。实现现状说明当前仓库的gen-ui-tool-baseddemo 已不再输出图片字段图像验证点属于历史版本检查项。若你验证的是当前实现可将该检查点替换为图表组件正确渲染 SVG 可视化其自动化断言可参考下文第五节e2e 测试通过assistantMessage.locator(svg)验证图表已渲染。3.5 多卡片堆叠Multiple Haikus / 连续生成清单要求验证多次生成的堆叠行为再次发起一个不同的生成请求如从 Sales bar chart 切换到 Traffic pie chart。验证新卡片出现在顶部最新结果置顶。验证上一条卡片仍保留在下方历史结果不丢失、不清空。验证初始占位卡片已被移除不会与真实结果混在一起。该行为在 e2e 中体现为消息内出现组件每条 Assistant 消息携带自己的结构化卡片手动验证时重点观察消息列表中多条卡片的前后顺序与保留情况。3.6 错误处理Error Handling发送空消息应被优雅处理不报错、不发送、无异常提示。当前实现依赖CopilotChat内置的空消息拦截如有自定义 Composer 则需自行校验。正常使用期间无控制台错误打开浏览器 DevTools Console全程观察确认没有未捕获异常、网络 4xx/5xx 或 React 渲染错误。补充一个后端侧的健壮性细节Agent 配置了max_consecutive_auto_reply15与human_input_modeNEVER防止 LLM 无限循环调用工具导致日志洪峰与实例失联agent.py 第 237-244 行generate_a2ui内部对 LLM 无响应、无 tool_call、JSON 解析失败等路径都做了错误捕获并返回 JSON 错误串agent.py 第 188-219 行。若生成失败可结合这些日志快速定位是模型调用失败还是参数解析失败。四、预期结果Expected ResultsQA 清单给出的验收标准如下全部通过即视为功能正常侧边栏/聊天界面在3 秒内加载完成Agent 在10 秒内响应并完成一次结构化生成结构化卡片同时包含原文/语义描述与可读内容两部分历史版本为日文英文译文当前实现为标题/描述图表数据多次生成的卡片最新置顶、向下堆叠无 UI 错误或布局破损。五、自动化等价验证仓库自带的 Playwright 测试手动清单之外仓库提供了完全自动化的等价验证——gen-ui-tool-based.spec.ts四个用例覆盖了清单的核心检查点清单检查项自动化用例页面加载三个建议按钮可见page loads with chat composer and the three suggestion pills逐个断言data-testidcopilot-suggestion且文本匹配三个标题生成请求 → 结构化组件渲染pie chart request renders SVG visualization发送饼图请求后断言 Assistant 消息内出现 SVG超时 60 秒生成请求 → 结构化组件渲染bar chart request renders SVG visualization同样断言 SVG 渲染基础消息 → Agent 响应sends message and gets assistant response断言 Assistant 消息可见超时 30 秒三个建议标题Sales bar chart/Traffic pie chart/Market share与 suggestions.ts 完全一致e2e 通过选择器textarea, [placeholder*message]定位输入框、以[data-testidcopilot-assistant-message]定位 Assistant 消息。建议做法将第五节的手动用例与 Playwright 测试配套使用——CI 跑自动化回归人工抽检关注视觉与交互细节动画、配色、布局两者结合即构成完整的 Tool-Based Generative UI 验收体系。六、当前实现对照速查表维度QA 清单记载历史版本当前仓库实现页面结构侧边栏主区域占位卡片全屏居中CopilotChat无额外页头建议按钮Nature / Ocean / Spring HaikuSales bar chart / Traffic pie chart / Market share注册 APIuseRenderTool/useFrontendTooluseComponentrender_bar_chart/render_pie_chart渲染产物HaikuCard日文英文渐变可选图片Recharts 柱状图 / 自定义 SVG 环形饼图后端工具—generate_a2uigpt-4.1 次级 LLM 生成 A2UI 结构与数据页面路由/demos/gen-ui-tool-based/demos/gen-ui-tool-based见 manifest.yaml七、总结与注意事项验证链路本质从前端useComponent注册 → 消息经/api/copilotkit代理 → AG2 后端generate_a2ui工具产出结构化 A2UI 数据 → 前端按name匹配组件渲染这就是 Tool-Based Generative UI 的完整闭环。QA 验证的本质是确认这条链路每一环都正确。文档与代码不一致的处理gen-ui-tool-based.md中的 haiku 检查项对应历史版本验证当前代码时以结构化数据 → 自定义组件渲染为不变核心将具体渲染物替换为图表组件即可判定标准3 秒加载、10 秒生成、最新置顶、无控制台错误完全适用。失败排查线索先看/api/copilotkit健康探针返回的agent_status与OPENAI_API_KEY状态再查后端日志中generate_a2ui的错误分支inner LLM call failed / LLM did not call render_a2ui / failed to parse render_a2ui args可快速区分是部署问题、模型问题还是参数解析问题。【免费下载链接】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 Tool-Based Generative UI 功能验证指南：AG2 集成场景下的端到端 QA 清单与实践

相关推荐

基于FastAPI与订单状态机的虚拟商品自动发货系统实践

Ventoy启动盘无法引导？3步排查修复，保留ISO文件的更新方法

基于均值-方差模型的资产配置：Python实现有效前沿与协方差估计

更多资讯

ZLUDA 完整指南：3 步在无 N 卡上跑通 CUDA 程序（附常见报错速查）

给 ArduPilot 加一块“外挂大脑”：用 Lua 自定义指令扩展飞控功能的实战指南

Apache Doris 压缩算法怎么选：ZSTD / LZ4 / Snappy 3 分钟落地指南

Aspen Plus模拟燃煤电厂CO₂液化：Linde-Hampson循环建模与优化

ArduPilot 开源飞控完整指南：一套代码如何让无人机、飞机和潜艇都跑起来

CLI-Anything 3MF 网格几何编辑器：圆柱孔检测、缩放与 3D 打印文件修复实战指南

今日更新

Linux 内核 ARM 虚拟内存布局全解析：从 4GB 地址空间划分到源码级验证

AIGC降重工具测评与教育应用指南

数据容灾核心指标与实战方案解析

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？