AG2 工具渲染Tool Rendering实战指南从 useRenderTool 到 E2E 质量验证【免费下载链接】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导读本文以仓库中 tool-rendering.md 质量验证清单为骨架完整拆解 CopilotKit 仓库中 AG2 集成示例的工具渲染Tool Rendering能力前端如何通过useRenderTool把后端 Agent 的工具调用实时渲染为品牌化 React 卡片后端如何通过 AG-UI 协议被代理接入以及如何用 Playwright E2E 测试把整条链路固化下来。读完本文你将掌握 per-tool 渲染器 通配 catch-all 的完整注册方式、前后端数据契约的关键细节以及一套可复制的 QA 验收方法。一、功能定位AG2 集成示例中的 Tool Renderingshowcase/integrations/ag2是 CopilotKit 与 AG2 中Tool Rendering 被定义为Backend agent tools rendered as UI components后端 Agent 工具渲染为 UI 组件即后端 Agent 在执行工具时前端聊天记录chat transcript中不再是干巴巴的 JSON而是渲染为带有品牌设计的 React 组件。manifest 中高亮的关键文件覆盖了完整链路agent.py — AG2 后端 Agent 与工具定义tools/get_weather.py、tools/query_data.py、tools/search_flights.py、tools/schedule_meeting.py — 具体工具实现page.tsx — 前端渲染器注册与页面route.ts — CopilotKit 运行时与 AG-UI 协议代理。示例应用将同一主题做成了三阶段递进见 manifest 中三个独立 demotool-rendering每个核心工具都有专属渲染器 通配兜底、tool-rendering-default-catchall前端零自定义渲染器完全依赖 CopilotKit 内置默认 UI、tool-rendering-custom-catchall用useDefaultRenderTool注册一个统一品牌化兜底卡片。本 QA 文档针对的是最完整的tool-rendering变体。二、架构概览前端、运行时与 AG2 后端如何连接2.1 AG-UI 协议代理前端 demo 页面挂载时指定了运行时地址与 Agent 名称CopilotKit runtimeUrl/api/copilotkit agenttool-rendering/api/copilotkit由 route.ts 处理它通过ag-ui/client的HttpAgent把请求转发到独立运行的 FastAPI 后端默认http://localhost:8000可通过AGENT_URL环境变量覆盖并使用 AG-UI 协议通信。const AGENT_URL process.env.AGENT_URL || http://localhost:8000; function createAgent(path /) { return new HttpAgent({ url: ${AGENT_URL}${path} }); }route.ts 把tool-rendering注册在sharedAgentNames列表中route.ts#L35-L56与agentic_chat、tool-rendering-default-catchall等名称共享同一个agent.py中定义的ConversableAgent——也就是说这一系列前端差异巨大的 demo 背后是同一份后端逻辑差异全部发生在前端渲染层。2.2 健康检查前提QA 文档的前置条件强调两点Demo 已部署且可访问Agent 后端健康检查/api/health。后端侧的真实健康探针在 entrypoint.sh一个 watchdog 每 30 秒curl一次http://127.0.0.1:8000/health连续 3 次失败即判定异常。因此前端验收前先确认该端点返回正常是保证测试结果可解释的第一步。三、前端渲染机制useRenderTool 与 useDefaultRenderTool3.1 per-tool 渲染器注册demo 页面 为每个有趣的后端工具注册了专属渲染器映射关系如下后端工具专属渲染器说明get_weatherWeatherCard /天气卡片search_flightsFlightListCard /航班列表卡片get_stock_priceStockCard /股票行情卡片roll_d20D20Card /掷骰子卡片其他一切工具CustomCatchallRenderer /通配兜底useRenderTool的典型注册方式以天气工具为例useRenderTool( { 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} / ); }, }, [], );要点拆解name与parameters声明该渲染器负责的工具名与参数 Schema使用 zod 校验render回调接收{ parameters, result, status }三个入参其中result通常是后端返回的 JSON 字符串需要先用parseJsonResult位于 parse-json-result.ts解析为对象status驱动加载态。源码中status ! complete视为 loading据此切换卡片内容。3.2 通配兜底渲染器任何未被具名渲染器认领的工具调用都会落到通过useDefaultRenderTool注册的 CustomCatchallRendereruseDefaultRenderTool( { render: ({ name, parameters, status, result }) ( CustomCatchallRenderer name{name} parameters{parameters} status{status as CatchallToolStatus} result{result} / ), }, [], );兜底卡片展示工具名、状态徽章、格式化后的参数与结果 JSON。从源码看CatchallToolStatus有三种状态custom-catchall-renderer.tsx#L15状态值徽章文案含义inProgressstreaming流式执行中executingrunning正在执行completedone已完成此时才渲染结果 JSON这正好与 QA 文档验证加载态→验证渲染结果的验收顺序一一对应。四、天气卡片从后端工具到前端组件的完整数据契约4.1 后端为什么必须返回 JSON 字符串QA 文档要求验证天气卡片的多个数据字段城市名、温度、湿度、风速、体感温度、天气状况。这些字段的后端来源是 agent.py 中的get_weather工具async def get_weather( location: Annotated[str, City name to get weather for], ) - str: Get current weather for a location. result get_weather_impl(location) return json.dumps( { city: result[city], temperature: result[temperature], feels_like: result[feels_like], humidity: result[humidity], wind_speed: result[wind_speed], conditions: result[conditions], } )源码注释明确记录了一个重要契约工具必须返回 JSON 字符串而不是 dict——因为 autogen 对非字符串返回值会调用str()序列化产生带单引号的 Python repr前端JSON.parse无法解析天气卡片就会渲染出--占位符。这是工具渲染能否正常出数据的关键细节也是 QA 验证所有数据字段已填充背后的底层原因。query_data、manage_sales_todos、schedule_meeting等工具采用了同样的模式。4.2 前端WeatherCard 组件与 testidWeatherCard 是加载态与完成态的复合组件加载态显示城市名、Fetching weather... 文案与...占位符完成态渲染温度华氏、湿度百分比、风速mph、天气状况与对应 emoji。组件上打了一组稳定的data-testid供 QA 手工验收与 E2E 自动断言共用data-testid含义weather-card天气卡片容器weather-city城市名weather-humidity湿度如 55%weather-wind风速如 10 mph天气图标由conditionsEmoji函数根据状况文本关键字映射weather-card.tsx#L79-L87sun/clear → sunrain/storm → raincloud → cloudsnow → snow。4.3 关于加载文案与主题色的说明QA 文档预期加载态显示 Retrieving weather... 并带 spinner且卡片背景色随天气状况变化晴#667eea、雨#4A5568、多云#718096、雪#63B3ED。对照当前源码加载文案实际为 Fetching weather...天气 emoji 位置为...背景色为固定值#EDEDF5未按状况动态换色。也就是说QA 文档描述的是该变体的预期规格而当前实现细节以源码为准——在做手工验收时建议以实际渲染的文案与配色作为基准同时把加载态到完成态的切换是否清晰、信息是否齐全作为核心判定标准而不是逐字比对文案。五、多城市天气查询多卡片并存QA 文档专门有一节验证连续询问第二个城市后第二张卡片应正常渲染且不破坏第一张。这与前端的实现方式直接相关每次工具调用都会挂载一张独立的卡片。这个设计在 d20-card.tsx 的注释中写得很明确Each tool call mounts its own card so e2e tests can count them.每次工具调用挂载自己的卡片以便 E2E 测试计数。因此验收要点是先问 San Francisco再问第二个城市断言页面上出现两张weather-card且各自weather-city显示正确的城市名第一张卡片的内容不被第二张覆盖。E2E 侧同样验证了这一行为d20的测试用cards.count()精确断言恰好 5 张卡片、最后一张结果是 20见 tool-rendering.spec.ts#L113-L143说明每次调用独立成卡是可计数、可断言的关键设计。六、建议按钮Suggestion PillsQA 文档要求验证三个天气建议按钮可见并可点击填入输入框Weather in San Francisco、Weather in New York、Weather in Tokyo。这些建议按钮由useSuggestions()demo 页面中的 hooks按钮 DOM 使用data-testidcopilot-suggestion驱动。需要说明的是当前仓库的 E2E 测试所固化的建议集合是另一套五颗 pill——Weather in SF、Find flights、Stock price、Roll a d20、Chain toolstool-rendering.spec.ts#L26-L39覆盖了天气、航班、股票、掷骰子与多工具链式调用五条路径。手工验收时可灵活处理只要建议按钮可见、点击后能填充输入框或直接发送消息即视为通过若需要严格对齐 QA 文档可将建议文案调整为目标城市如 SF / New York / Tokyo。七、错误处理空消息与无控制台报错QA 文档的第三大块验收聚焦健壮性发送空消息应被优雅处理不崩溃、不产生无效请求正常使用过程中无 console 错误。这条检查背后的意义在于工具渲染链路横跨前端渲染器、CopilotRuntime 代理、AG2 后端三层任何一层的异常都可能在浏览器控制台暴露。建议在 DevTools Console 保持开启的状态下完成 3.1—3.3 的全部步骤把无报错作为贯穿始终的观察项。八、从手工 QA 到 Playwright E2E把验收固化为自动化QA 文档的每一项手工检查几乎都能在 tool-rendering.spec.ts 中找到对应的自动化断言。该测试文件头部注明其与 QA 文档的对应关系QA reference: qa/tool-rendering.md并把 5 颗建议 pill 映射为 6 个测试用例测试用例对应 QA 步骤关键断言testid 确定性 fixture 值页面加载与 5 颗建议 pill建议按钮检查copilot-suggestion× 5 可见Weather in SF天气卡片渲染weather-card可见weather-city含 San Franciscoweather-humidity含 55%weather-wind含 10Find flights多卡片渲染flights-card可见flight-origin含 SFOflight-destination含 JFKflight-row≥ 2 行Stock price股票卡片渲染stock-card可见stock-ticker AAPLstock-price含 $338.37stock-change含 -2.96%Roll a d20多卡片渲染恰好 5 张d20-card最后一张d20-value 20前四张非 20Chain tools多工具链式调用一轮对话中同时出现weather-card、flights-card、d20-card测试中使用的确定性数据来自 Aimock fixtureshowcase/aimock/d5-all.json每条 pill 提示词都被固定映射到确定的工具调用序列——这正是渲染结果可重复断言的前提。测试还设置了两个超时阈值建议按钮等待 15 秒、工具调用等待 60 秒tool-rendering.spec.ts#L15-L16与 QA 文档聊天 3 秒内加载、Agent 10 秒内响应的预期共同构成性能验收基线。九、验收标准总结Expected Results综合 QA 文档的最终判定标准一个通过的工具渲染验收应同时满足性能聊天界面 3 秒内加载完成Agent 10 秒内给出响应功能天气卡片渲染出全部数据字段城市、摄氏/华氏温度、湿度、风速、体感温度、状况图标视觉一致性天气图标与状况文本匹配sun/rain/cloud/snow健壮性无 UI 错误、无布局破坏、空消息被优雅处理。十、延伸阅读后端 Agent 与工具定义agent.py前端渲染器注册page.tsx天气卡片组件weather-card.tsx通配兜底渲染器custom-catchall-renderer.tsxE2E 自动化验收tool-rendering.spec.ts运行时代理与 Agent 注册route.tsDemo 目录与路由清单manifest.yaml【免费下载链接】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），仅供参考