CopilotKit Tool-Based Generative UI 验收指南：Claude Agent SDK（Python）集成下的俳句生成器实战

CopilotKit Tool-Based Generative UI 验收指南Claude Agent SDKPython集成下的俳句生成器实战【免费下载链接】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 展示集成仓库中gen-ui-tool-based演示的 QA 验收文档展开系统讲解“工具型生成式 UITool-Based Generative UI”的完整验收流程从环境就绪检查、基础功能验证到俳句生成、图片展示、多结果堆叠与异常处理并深入源码剖析useComponent/useFrontendTool/useRenderTool的底层协作机制。读完本文你将掌握如何用一份可执行的验收清单 Playwright 端到端测试 源码级原理分析在自己的 CopilotKit 应用中验证并落地 Agent 触发式动态 UI。一、文档定位一份可执行、可回归的生成式 UI 验收清单关联文档 gen-ui-tool-based.md 是 Claude Agent SDKPython集成仓库中的 QA 验收清单属于仓库统一的“分功能验收”文档体系。它面向已部署的演示环境用可勾选的检查项- [ ]逐步验证一个工具型生成式 UI 演示是否达标并给出可度量的预期结果如侧边栏 3 秒内加载、Agent 10 秒内生成俳句。该清单覆盖四个层面基础功能页面可达、侧边栏与占位卡片、基础对话特性级检查建议按钮、俳句生成、图片展示、多俳句堆叠异常处理空消息、控制台错误预期结果时间基线与布局完整性。这与仓库中的 Playwright 端到端测试 gen-ui-tool-based.spec.ts 形成“人工验收 自动化回归”的双轨验证模式。关于“工具型生成式 UI”的定义官方文档 tool-based.mdx 给出精确定义把 React 组件注册为工具Agent 调用该工具时CopilotKit 把工具参数作为类型化 props 直接透传给组件并渲染在对话流中。它没有后端 handler、没有用户交互、没有服务端执行——组件本身就是交付物Agent 决定何时展示、填充什么数据。二、前置条件环境就绪检查清单第一步不是测试而是确认“被测对象可访问、后端健康”Demo 已部署且可访问对应路由为/demos/gen-ui-tool-based见 manifest.yaml 中gen-ui-tool-based演示项的route字段Agent 后端健康访问/api/health应返回健康状态否则后续所有“Agent 响应”类检查都会失败前端与后端均已启动该集成采用 Next.js 前端 Claude Agent SDKPython后端入口见 route.ts 与 agent.py。在仓库中该演示在 manifest.yaml 里的注册信息为字段值idgen-ui-tool-basednameTool-Based Generative UIdescriptionAgent uses tools to trigger UI generation (haiku generator via useFrontendTool useRenderTool)tagsgenerative-uiroute/demos/gen-ui-tool-basedhighlightsrc/agents/agent.py、src/app/demos/gen-ui-tool-based/page.tsx、src/app/api/copilotkit/route.tshighlight字段直接指明理解该演示需要同时看 Python Agent 后端、前端 demo 页面与 API 路由三个文件。三、基础功能验收清单按以下步骤验证最核心的可用性导航到gen-ui-tool-baseddemo 页面验证CopilotSidebar 默认打开标题为“Haiku Generator”验证主区域显示占位俳句卡片通过侧边栏发送一条基础消息验证 Agent 正常回复。这五项检查覆盖“页面可达 → 侧边栏组件挂载 → 初始渲染态 → 对话通路 → Agent 响应”的完整链路。其中“默认打开 固定标题 占位卡片”属于典型的首屏状态验证用于快速暴露路由、Provider 配置或组件默认渲染的错误。需要说明的是QA 清单描述的“侧边栏 俳句生成器”形态来源于录制夹具showcase/aimock/d6/claude-sdk-python/gen-ui-tool-based.json对应的目标行为而当前claude-sdk-python仓库源码中同一路由还提供了一个居中的CopilotChat变体见下文源码剖析。两种形态共享同一底层机制——Agent 通过工具调用触发前端组件渲染——这正是工具型生成式 UI 的本质。验收时以实际部署形态为准机制验证点完全通用。四、建议按钮Suggestions验收验证“Nature Haiku”建议按钮可见验证“Ocean Haiku”建议按钮可见验证“Spring Haiku”建议按钮可见。建议按钮suggestion pills是降低用户输入门槛的常用交互。自动化测试侧同样覆盖了这一点gen-ui-tool-based.spec.ts 中第一条用例通过[data-testidcopilot-suggestion]定位器逐一断言建议按钮可见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 场景下建议按钮的本质是“提示用户发起会触发工具调用的指令”例如“Nature Haiku”会诱导 Agent 调用俳句生成工具。给建议按钮一个动词化、结果明确的文案能显著提高 Agent 选对工具的命中率。五、俳句生成useFrontendTool / useComponent 驱动的核心链路这是清单中技术含量最高的一节点击 “Nature Haiku” 建议按钮或输入 “Write me a haiku about nature”验证渲染出一张HaikuCarddata-testidhaiku-card并包含三行日文data-testidhaiku-japanese-line三行英文翻译data-testidhaiku-english-line卡片应用了背景渐变样式验证日文文本包含真实的日文字符而非拉丁字符验证英文行为可读的英文翻译。这组断言有两个值得注意的验证思路结构验证通过稳定的data-testid定位组件内部的三个子区域验证结构化输出的完整性日文 3 行 英文 3 行内容验证不只是“有文本”而是验证“日文确实是日文、英文确实可读”——防止模型输出占位符或乱码。从源码机制看这条链路依赖 CopilotKit v2 的三个 API 协同工作useComponent把 React 组件注册为一个“前端工具”。官方文档 tool-based.mdx 说明它接收三个核心参数——工具名name、props 的 Zod schemaparameters、要渲染的组件render。name会作为工具名暴露给 Agent文档建议使用render_bar_chart、show_weather这类动词短语让 LLM 在用户提出可视化诉求时稳定命中useFrontendTool注册由前端浏览器执行的处理函数其 schema 会通过 AG-UI 消息转发给后端 Agent见 frontend_tools.py 的注释说明CopilotKit 在运行时把前端注册的工具 schema 转发给 Agenthandler 在浏览器端执行useRenderTool把工具名映射到 React 组件demo 自述文档 README.md 中说明useRenderTool将get_weather之类的工具名映射到天气卡片。Zod schema 是关键防线LLM 产生的工具参数先经过 Zod 校验再作为类型化 props 进入组件。以同目录的图表组件为例bar-chart.tsx 中 schema 的写法如下export 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;可以推断俳句生成工具的 schema 同样会约束japanese_lines三行字符串、english_lines三行字符串、image_name等字段而 QA 清单对“三行日文 三行英文”的断言正是对 schema 结构与渲染组件契约的端到端验证。六、图片显示image_name 驱动的条件渲染俳句生成后如果 Agent 提供了image_name验证渲染出一张图片data-testidhaiku-image验证图片src指向/images/且文件名来自预定义列表。这一节体现了工具型生成式 UI 的“条件性”设计图片是可选字段Agent 根据生成内容决定是否附带image_name前端组件仅在字段存在时渲染图片且文件名被约束在预定义白名单内避免引用不存在的本地文件。demo 自述文档 README.md 对图片使用给出了两条工程建议值得在验收与实现时同时关注不要从 Agent 生成的内容中引用本地图片文件它们不存在应给img添加onError回退这正解释了为什么 QA 清单要求“src 来自预定义列表 有效文件名”——白名单 onError 双保险防止破图。七、多俳句堆叠状态更新的顺序语义生成第二个俳句例如 “Ocean Haiku”验证新俳句卡片出现在顶部验证之前的俳句卡片仍显示在其下方验证初始占位俳句被移除。这是对消息列表顺序语义的回归验证新结果置顶最新优先、历史结果保留不丢失上下文、占位内容在首个真实结果到达后被清理避免永久残留。从实现侧看这要求渲染组件在收到新的工具结果时正确更新消息数组的头部并在首个结果到达时清除 placeholder 状态。八、异常处理验收发送空消息应被优雅处理不崩溃、不报错、给出合理反馈或直接忽略正常使用过程中控制台无错误。空消息处理通常在前端输入层拦截禁用发送按钮或直接丢弃空提交“无控制台错误”则是 React 渲染、网络请求、组件卸载各环节健康的综合信号。建议在验收时打开浏览器 DevTools 的 Console 面板全程观察尤其关注 React key 警告、网络 4xx/5xx、以及未捕获的 Promise rejection。九、预期结果可量化的验收基线QA 清单给出明确的“通过标准”可作为自动化断言阈值的参考验收项基线侧边栏加载3 秒内Agent 响应并生成俳句10 秒内俳句卡片内容日文 英文双语文案完整俳句堆叠顺序最新在上历史保留布局无 UI 错误、无布局破损仓库中 Playwright 测试的 timeout 设置与此呼应suggestion 可见性断言为 15 秒Agent 消息可见性为 30 秒图表 SVG 渲染为 60 秒gen-ui-tool-based.spec.ts。人工验收的“预期结果”与自动化测试的超时阈值应保持一致口径这是让两种验证模式互相印证的关键。十、源码级剖析demo 页面的完整实现形态当前claude-sdk-python仓库中该 demo 的前端入口 page.tsx 展示了工具型生成式 UI 的完整接线方式use client; import React from react; import { CopilotChat, CopilotKit, useComponent, } from copilotkit/react-core/v2; import { BarChart, barChartPropsSchema } from ./bar-chart; import { PieChart, pieChartPropsSchema } from ./pie-chart; import { useSuggestions } from ./suggestions; function Chat() { 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, }); useSuggestions(); return ( 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 ); } export default function ControlledGenUiDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentgen-ui-tool-based Chat / /CopilotKit ); }从源码可以提炼出工具型生成式 UI 的三层结构Provider 层CopilotKit runtimeUrl/api/copilotkit agentgen-ui-tool-based绑定后端运行时与默认 Agent注册层组件树内调用useComponent({ name, description, parameters, render })把图表组件注册为render_bar_chart、render_pie_chart两个前端工具description帮助 LLM 理解工具的用途展示层CopilotChat agentIdgen-ui-tool-based渲染对话界面Agent 调用工具后结果组件内联出现在消息流中。对应的 Playwright 用例验证了这条链路向输入框填入 “Show me a pie chart of revenue by category” 后断言[data-testidcopilot-assistant-message]内部出现 SVGRecharts 渲染产物超时 60 秒gen-ui-tool-based.spec.ts。这正是 QA 清单中“发送消息 → Agent 响应 → 组件渲染”的自动化等价物。十一、实现与样式注意事项demo 自述文档 README.md 还沉淀了三条在对话流内渲染自定义组件的工程经验对话流内的组件请使用内联样式经useRenderTool/useHumanInTheLoop/useFrontendTool渲染的内容位于 CopilotKit 组件树内部Tailwind v4 无法静态检测到这些类名可能被 purge 掉。应写成// 推荐内联样式 div style{{ padding: 24px, borderRadius: 12px, background: #fff }} // 不推荐Tailwind 可能清除这些类 div classNamep-6 rounded-xl bg-white覆盖 CopilotKit 内部样式时CopilotKit 内部使用cpk:前缀类名覆盖需放在独立的 CSS 文件如copilotkit-overrides.css不要在globals.css中写会被 Tailwind 清理并在layout.tsx中于globals.css之后导入/* copilotkit-overrides.css */ .copilotKitInput { border-radius: 0.75rem; border: 1px solid var(--copilot-kit-separator-color) !important; }图片与图标Agent 生成的内容不要引用本地图片文件加onError回退对话消息内的图标建议用 emoji 而非 SVGfillcurrentColor在对话上下文中渲染不可控。完整的样式指导见 STYLING-GUIDE.md。十二、在 CopilotKit 中复用本验收方法论这份 QA 清单虽然针对单个 demo但其方法论可以直接复用到你自己的工具型生成式 UI 应用中先定义“结构契约”为每个useComponent/useFrontendTool注册的组件设计稳定的data-testid如haiku-card、haiku-japanese-line、haiku-image让人工验收与自动化断言共用同一套定位标识用 Zod 收紧参数边界schema 即契约describe()描述同时服务 LLM 生成与开发者维护把“预期结果”翻译成自动化阈值将“3 秒加载、10 秒响应”这类基线写入 Playwright 的timeout人工验收与 CI 回归保持同一标准显式测试状态迁移占位 → 首个结果 → 追加结果的顺序语义新卡片置顶、历史保留、占位移除是生成式 UI 最容易回归的点务必纳入清单。以上四步与仓库中 QA 文档、e2e 测试、demo 源码 三者一一对应构成“文档定义行为、测试固化行为、源码实现行为”的完整闭环。【免费下载链接】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），仅供参考