CopilotKit 工具渲染Tool Rendering端到端 QA 指南Claude Agent SDK TypeScript 集成实战【免费下载链接】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 仓库中showcase/integrations/claude-sdk-typescript/qa/tool-rendering.md这份 QA 测试计划为骨架完整讲解在 CopilotKit 的 Claude Agent SDKTypeScript集成中如何对后端 Agent 工具调用渲染为聊天内 React 组件这一核心能力进行系统化验证。你将掌握工具渲染演示的环境准备、逐项功能测试步骤、基于useRenderTool/useDefaultRenderTool的渲染契约含data-testid稳定标识、异常与错误处理检查以及从 QA 手册到 Playwright 自动化测试的落地路径。一、QA 文档定位一份可执行的工具渲染验收清单showcase/integrations/claude-sdk-typescript/qa/tool-rendering.md是集成 Showcase 中 tool-rendering 演示的官方测试计划。它的主题非常聚焦验证后端 Agent 发出的工具调用能否在前端聊天流中渲染为组件卡片。这与演示在 manifest.yaml 中的描述完全一致Backend agent tools rendered as UI components后端 Agent 工具渲染为 UI 组件路由为/demos/tool-rendering。在深入测试步骤之前先建立对被测功能的概念模型。演示目录下的 README.md 一句话点明了机制后端 Agent 的工具调用在聊天记录中被渲染为 React 组件。前端用useRenderTool按工具名注册渲染器接收args、result和status从而让 UI 既能反映执行中的调用也能反映已完成的调用。也就是说QA 手册中每个勾选框最终都要落到对这套工具名 → 渲染器 → 状态机链路的观察上。二、前置条件QA 开始前的环境自检原 QA 文档明确了两条硬性前置条件任何一条不满足后续测试项均无意义Demo 已部署并可访问即/demos/tool-rendering页面可以被浏览器正常打开Agent 后端健康检查/api/health确认 Agent 服务可用。这两条对应着仓库中的两处实现健康检查路由位于 src/app/api/health/route.tsQA 执行前应先 curl 或浏览器访问该端点后端 Agent 的编排入口在 src/agent_server.ts工具渲染演示的 Agent 通过agenttool-rendering在 演示页面 中绑定。验证提示健康检查通过 ≠ 工具渲染正常。它只保证 Agent 进程活着工具渲染是否工作需要后面逐项功能测试来确认。建议把/api/health的探测写入 CI 或部署脚本作为一切功能测试的前置 gate。三、基础功能测试聊天界面与 Agent 响应QA 文档的第一步是最基础的冒烟测试Smoke Test共 5 个勾选项导航到 tool-rendering 演示页面验证聊天界面以水平居中、全高度的布局加载验证聊天输入框占位符 Type a message 可见发送一条基础消息验证 Agent 会响应3.1 布局与占位符的源码依据从当前演示源码看布局契约由 page.tsx 提供CopilotKit runtimeUrl/api/copilotkit agenttool-rendering div classNameflex justify-center items-center h-screen w-full div classNameh-full w-full max-w-4xl Chat / /div /div /CopilotKitflex justify-center items-center h-screen水平居中 垂直居中 全屏高度max-w-4xl内容区最大宽度约束约 896px保证宽屏下不过度拉伸CopilotChat渲染于 Chat 组件classNameh-full rounded-2xl确保聊天区填满外层高度。而 Type a message 占位符在 Playwright 自动化用例中作为页面加载完成的锚点使用// tests/e2e/tool-rendering.spec.ts await page.goto(/demos/tool-rendering); await expect(page.getByPlaceholder(Type a message)).toBeVisible({ timeout: SUGGESTION_TIMEOUT, // 15s });可以看到占位符可见性被当作页面可交互就绪的信号——QA 手册中占位符可见这一项正是自动化里beforeEach的同步条件。3.2 发送基础消息验证什么发送一条基础消息不触发任何工具调用验证的是纯文本聊天链路前端 →/api/copilotkit运行时 → Agent 后端 → 流式响应回到聊天记录。这条链路正常才谈得上后续工具调用渲染的观察。四、功能特性专项检查一建议按钮SuggestionsQA 文档要求验证三枚天气建议按钮可见Weather in San FranciscoWeather in New YorkWeather in Tokyo并验证点击天气建议后能填充输入框或直接发送消息。4.1 当前实现中的建议来源需要注意QA 文档是功能验收清单而实际 Demo 的建议内容可能随迭代调整。从当前源码看建议由 suggestions.ts 通过useConfigureSuggestions提供useConfigureSuggestions({ suggestions: [ { title: Weather in SF, message: Whats the weather in San Francisco? }, { title: Find flights, message: Find flights from SFO to JFK. }, { title: Stock price, message: Whats the current price of AAPL? }, { title: Roll a d20, message: Roll a 20-sided die. }, { title: Chain tools, message: Chain a few tools in this single turn: ... }, ], available: always, });QA 文档的测试意图可以这样理解建议按钮的数量、标题与可用性属于产品级契约QA 应以当前生效的建议配置为准逐项核对。核心验收点是两条不变原则每条建议都是一个标题 预置消息的组合点击后消息注入输入框或直接发送建议点击后必须能驱动对应工具路径——天气建议要能触发get_weather工具调用。4.2 自动化中的建议验证Playwright 用例 page loads with composer and 5 suggestion pills 正是对建议契约的自动化固化它断言[data-testidcopilot-suggestion]下五枚建议全部可见并用每个建议驱动一条独立用例天气卡、航班卡、股票卡、d20 卡、链式工具卡。QA 实操建议手工测试时逐一点击每枚建议确认建议文字正确、点击后消息被正确填充/发送、并观察是否触发了预期的工具渲染。五、功能特性专项检查二天气卡片渲染useRenderTool 核心场景这是整个 QA 文档中技术含量最高、检查项最多的一节。QA 手册规定输入 Whats the weather in San Francisco?验证加载态显示 Retrieving weather... 和 spinner验证 WeatherCard 渲染data-testidweather-card包含城市名data-testidweather-city摄氏与华氏双单位温度湿度百分比data-testidweather-humidity风速 mphdata-testidweather-wind体感温度data-testidweather-feels-like天气条件文字 对应图标sun/rain/cloud验证卡片背景色随天气条件主题变化Clear/Sunny#667eea蓝紫Rain/Storm#4A5568深灰Cloudy#718096中灰Snow#63B3ED浅蓝5.1 useRenderTool 渲染器的注册方式天气渲染器的注册位于 page.tsxuseRenderTool( { name: get_weather, parameters: z.object({ location: z.string() }), render: ({ parameters, result, status }) { const loading status ! complete; const parsed parseJsonResultWeatherResult(result); return ( WeatherCard loading{loading} location{parameters?.location ?? parsed.city ?? } temperature{parsed.temperature} humidity{parsed.humidity} windSpeed{parsed.wind_speed} conditions{parsed.conditions} / ); }, }, [], );这里浓缩了useRenderTool的完整契约name绑定的后端工具名必须与 Agent 侧注册的工具名一致这里是get_weatherparameters用zod schema声明工具入参类型实现前端侧的入参校验render回调接收{ parameters, result, status }三要素——status ! complete即加载态result需要按工具约定的 JSON 结构解析第二参数[]为依赖数组控制渲染器重建时机。5.2 卡片实现与>await expect(card.locator([data-testidweather-city])).toContainText( San Francisco, { timeout: TOOL_TIMEOUT }); await expect(card.locator([data-testidweather-humidity])).toContainText( 55%, { timeout: TOOL_TIMEOUT }); await expect(card.locator([data-testidweather-wind])).toContainText( 10, { timeout: TOOL_TIMEOUT });它依赖 aimock 夹具fixture将模型输出固定为确定性的工具调用序列从而让城市San Francisco、湿度55%、风速10成为可断言的事实。手工 QA 与自动化测试在这一节的目标完全一致卡片必须完整呈现五个数据字段且状态从加载流转到完成。六、功能特性专项检查三多次天气查询与多卡片共存QA 文档要求询问第二个城市的天气验证第二张 WeatherCard 渲染且不破坏第一张验证每张卡片显示正确的城市名这一节验证的是工具渲染的实例隔离性每次工具调用都应挂载一张独立的卡片卡片之间不共享状态、不互相覆盖。从实现看useRenderTool的 render 回调每次被调用都会返回新的组件实例roll_d20的注释也印证了这一设计——Each tool call mounts its own card so e2e tests can count them每次工具调用挂载自己的卡片以便 E2E 测试计数。QA 实操建议连续询问两个城市后检查聊天流中是否出现两张独立卡片第一张卡片的城市、温度等数据是否在第二张出现后保持不变卡片顺序是否与提问顺序一致消息流的时间顺序。七、错误处理与鲁棒性检查QA 文档的第三节只有两条但都是容易遗漏的验收项发送空消息应被优雅处理正常使用过程中无控制台报错7.1 空消息的处理语义优雅处理指输入框为空时发送应被阻止或给出无破坏性的反馈聊天流与渲染状态不进入异常分支。CopilotChat 输入组件对空提交自带防抖与禁用逻辑QA 时重点观察不出现 JS 异常、不出现空白消息气泡、后续功能不受影响。7.2 控制台无报错建议在浏览器 DevTools Console 中开启Preserve log完整跑一遍第三节到第六节的所有路径建议点击、工具调用、链式调用、空消息然后逐一检查无未捕获的异常Uncaught errors无 React key 警告、Hydration 警告无失败的网络请求可结合 Network 面板交叉验证。从源码结构看custom-catchall-renderer.tsx 对结果解析做了防御parseResult先尝试JSON.parse失败则回退为原始字符串safeStringify对不可序列化对象兜底。这类防御逻辑的存在正是无控制台报错得以成立的部分原因。八、预期结果把验收标准量化QA 文档最后给出四条量化验收标准验收项标准聊天加载3 秒内完成Agent 响应10 秒内返回天气卡片所有数据字段完整填充界面质量天气图标与主题色匹配条件无 UI 错误或布局损坏这些数字应被理解为软性 SLO服务级目标网络环境、模型延迟、回放模式都会影响实际数值。在自动化测试中仓库实际采用了更宽松的超时配置——建议加载等待 15 秒SUGGESTION_TIMEOUT、工具渲染等待 60 秒TOOL_TIMEOUT见 tool-rendering.spec.ts。QA 执行建议以 QA 文档的 3s/10s 作为理想目标同时参考自动化配置的现实阈值在测试报告中记录实测值而非仅标记通过/失败。九、纵深扩展从 QA 手册到实现的完整链路9.1 前端per-tool 渲染器 兜底渲染器的双轨结构tool-rendering 演示是最完整的渲染变体——每类有趣的工具都有专属品牌化 UI外加一个 catch-all 兜底。从 page.tsx 的注释可梳理出完整的映射表后端工具前端渲染器说明get_weatherWeatherCard /天气卡片含城市/温度/湿度/风速search_flightsFlightListCard /航班列表卡片get_stock_priceStockCard /股票卡片roll_d20D20Card /骰子卡片其他所有工具CustomCatchallRenderer /通配兜底展示工具名/状态/参数/结果兜底渲染器通过useDefaultRenderTool注册page.tsx其 状态机 包含三个状态inProgressstreaming、executingrunning、completedone每个状态有独立的徽章颜色与文案。QA 测试兜底渲染器时可以特意触发一个没有专属渲染器的工具如roll_dice验证兜底路径。9.2 后端工具 schema 与确定性实现工具渲染依赖后端 Agent 真实执行工具。定义位于 tool-rendering-prompts.tsTOOL_RENDERING_SYSTEM_PROMPT系统提示词规定路由规则——天气问题调get_weather、航班搜索调search_flights、股票调get_stock_price、骰子调roll_d20Chain a few tools则要求单轮内同时调用 get_weather search_flights roll_d20SEARCH_FLIGHTS_TOOL_SCHEMA以 Anthropic Tool 格式声明search_flights的input_schemaorigin/destination均必填ROLL_D20_TOOL_SCHEMAroll_d20支持可选value参数用于让演示运行确定化——这正是 E2E 用例能断言最后一张 d20 卡片值为 20的机制searchFlightsImpl/rollD20Impl确定性 mock 实现航班数据固定返回 United/DL/JetBlue 三个班次。前端useRenderTool声明的 zod 参数 schema 与后端 Anthropicinput_schema是同一契约的两端QA 时可以交叉核对两者字段是否对齐。9.3 后端工具如何进入 Agent 运行循环工具最终通过 claude-agent-sdk-adapter.ts 接入buildBackendToolServer将工具 schema 转换为 MCP server 配置ClaudeAgentAdapter接收mcpServers与allowedTools随后createSdkMcpServer注册可执行工具 handler白名单使用mcp__copilotkit__*全限定名。完整接线说明见 docs/setup/tool-rendering-setup.mdx。QA 排障时这条链路很关键如果卡片一直停留在加载态优先排查工具结果是否真正返回——历史上正是调用被转发到前端但结果从未落地、所有卡片永远 loading这一失败模式驱动了后端 mock 实现的引入见 tool-rendering-prompts.ts 的说明。9.4 同族演示与回归测试tool-rendering 属于一个演示家族manifest.yaml 列出了四个成员tool-rendering-default-catchall、tool-rendering-custom-catchall、tool-rendering、tool-rendering-reasoning-chain。QA 文档覆盖的是中间的tool-renderingper-tool catch-all 双轨制另有三份配套的 E2E 规格tool-rendering-custom-catchall.spec.ts、tool-rendering-default-catchall.spec.ts、tool-rendering-reasoning-chain.spec.ts分别覆盖仅自定义兜底仅默认兜底跨轮次链式推理如双股票对比、航班目的地天气。回归建议修改任何渲染器或工具 schema 后应同时跑这四份规格因为同一契约被多个变体共享。十、把 QA 手册固化为自动化Playwright 实践要点QA 手册中的每一条勾选都能在 tool-rendering.spec.ts 中找到自动化对应物。映射关系如下QA 手册条目自动化用例页面加载 占位符可见page loads with composer and 5 suggestion pillsbeforeEach 锚点建议按钮可见同上断言 5 枚copilot-suggestion天气卡片渲染Weather in SF pill renders the SF weather card航班卡片渲染Find flights pill renders the flights card股票卡片渲染Stock price pill renders the AAPL stock card多卡片共存/计数Roll a d20 pill produces exactly 5 d20 cards断言恰好 5 张、末张为 20单轮链式多工具Chain tools pill renders weather flights d20 cards in one turn自动化固化的核心方法论有三点同样适用于手工 QA稳定 testid 优先断言一律挂在data-testid上而不是 CSS 类或文本位置这样样式重构不会破坏测试确定性数据回放通过 aimock 夹具把模型响应钉死让湿度 55%这类细节成为可断言事实轮询等待工具完成用expect.poll(...)等待工具链全部落地如 5 次连续掷骰避免固定 sleep 导致的脆测。十一、QA 执行清单速查与排障指引将全文整合为一份可直接执行的最终清单准备阶段确认 Demo 已部署/api/health返回健康打开/demos/tool-rendering基础功能页面居中全高布局、占位符 Type a message 可见发送基础消息Agent 正常响应建议与工具渲染所有建议按钮可见、可点击、能填充/发送消息触发天气查询加载态 → WeatherCard 完成态城市/温度/湿度/风速/条件/图标齐全触发第二个城市查询第二张卡片渲染且第一张不受影响可选触发无专属渲染器的工具验证兜底卡片错误处理空消息被优雅处理全流程 Console 无报错结果量化加载 ≤ 3s、响应 ≤ 10s记录实测值无 UI 错误、无布局损坏常见排障链路卡片永远 loading → 检查后端工具是否真实执行mcp__copilotkit__*白名单、mock 实现卡片不出现 → 检查前端useRenderTool的工具名与后端 schema 是否一致建议不可见 → 检查useConfigureSuggestions与available: always配置断言失败 → 检查data-testid契约是否在卡片重构中被移除。综上这份 QA 文档的价值不在于罗列步骤而在于把工具渲染这条涉及前端 React 渲染器、后端工具 schema、MCP 适配层三层协同的能力变成了一组可重复、可量化、可自动化的验收契约。无论是手工 QA 还是 CI 回归它都是 tool-rendering 功能质量保障的基准线。【免费下载链接】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），仅供参考