用 `useDefaultRenderTool` 为 Google ADK Agent 实现品牌化通配工具渲染：CopilotKit Custom Catch-all 实战与 QA 验证

用useDefaultRenderTool为 Google ADK Agent 实现品牌化通配工具渲染CopilotKit Custom Catch-all 实战与 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 的 v2 React 核心中useDefaultRenderTool是一个通配wildcard级别的工具渲染器注册入口它只注册一个渲染组件接管页面上所有未被具名渲染器认领的工具调用。本文以 CopilotKit 仓库中 Google ADK 集成示例tool-rendering-custom-catchall演示页、渲染器、后端 Agent、Playwright 端到端测试、QA 清单为主线完整讲解这种单一品牌化卡片 全工具通用的渲染策略如何注册、卡片如何表达工具名/状态/参数/结果、状态机如何从streaming走到done以及如何在 QA 阶段用确定性断言验证零具名渲染器、所有工具共用同一张品牌卡片这一核心不变量。读完你将能照抄该模式到自己的 Agent 前端并写出可复用的工具渲染回归测试。1. 场景定位Custom Catch-all 在工具渲染演进中的位置在 showcase/integrations/google-adk 集成包中tool-rendering系列演示共同构成了一条工具渲染能力演进的渐进线默认工具渲染默认兜底完全依赖 CopilotKit 内置的DefaultToolCallRenderer零自定义Custom Catch-all本文主角注册一个自定义通配渲染器替换掉内置默认 UI但暂不按工具名做差异化——所有工具共用一张品牌卡片按工具具名渲染reasoning-chain 等变体在通配渲染器之上再叠加useRenderTool({ name: get_weather, ... })之类的具名注册实现每工具专属 UI。三条路径共享同一套后端工具面。自定义通配变体的核心不变量可以浓缩为一句话零个具名渲染器 一个品牌化通配组件 每次工具调用都画同一张卡片。这一点在页面源码的头部注释里写得很清楚page.tsxSame backend tools astool-rendering-default-catchall, but this cell opts out of CopilotKits built-in default tool-call UI by registering a SINGLE custom wildcard renderer viauseDefaultRenderTool. The same branded card now paints every tool call — no per-tool renderers yet.2. 前置条件与演示注册链路2.1 前置条件来自 QA 清单QA 文档tool-rendering-custom-catchall.md给出的运行前提是演示应用已部署且可访问Agent 后端健康检查/api/healthAgent slugtool-rendering-custom-catchall已在/api/copilotkit注册。这条 slug 链路在仓库里有完整的落点前端页面通过CopilotKit runtimeUrl/api/copilotkit agenttool-rendering-custom-catchall绑定 agent 名route.ts 中的agentNames数组声明了tool-rendering-custom-catchall运行时为每个名字创建一个HttpAgent代理到 Python 后端的AGENT_URL/name默认http://localhost:8000registry.py 的AGENT_REGISTRY把该名字映射到tool_rendering_custom_catchall_agent后端agent_server.py遍历注册表把每个 Agent 以agent_name挂载为独立的 ADKAgent 中间件manifest.yaml 将该 demo 登记为独立特性id: tool-rendering-custom-catchallroute: /demos/tool-rendering-custom-catchall。也就是说前端agentprop → Next.js 运行时路由 → Python 后端挂载路径三层名字必须一致QA 第 7 步的slug 已注册检查才成立。2.2 前端 Agent 后端定义后端就是一个标准的 Google ADKLlmAgenttool_rendering_custom_catchall_agent.pytool_rendering_custom_catchall_agent LlmAgent( nameToolRenderingCustomCatchallAgent, modelget_model(), instructionTOOL_RENDERING_INSTRUCTION, tools[get_weather, search_flights, get_stock_price, roll_d20], after_model_callbackstop_on_terminal_text, )四个工具来自 tool_rendering_common.py与tool-rendering基础变体完全一致且特意与 langgraph-python 集成保持镜像工具面以便两组集成共用同一套 aimock 录制夹具和 Playwright 测试。值得注意的细节get_weather返回确定性的 mock 载荷temperature: 68、humidity: 55、wind_speed: 10、conditions: Sunny这正是 QA 文档第 1 节要求核对的确切字段roll_d20的value参数与get_stock_price的price_usd/change_pct参数允许 LLM 或测试夹具传入确定值测试场景里可据此断言第 5 张卡片结果恰好是 20stop_on_terminal_text回调shared_chat.py是避免 ADK 代理循环无限重发工具调用的关键守卫工具渲染 QA 中链式调用正常收敛依赖它。3. 前端注册一个通配渲染器接管所有工具调用页面源码 page.tsx 的核心只做了三件事包CopilotKit、注册通配渲染器、渲染CopilotChat。function Chat() { // useDefaultRenderTool 是 useRenderTool({ name: *, ... }) 的便捷封装—— // 一个通配渲染器处理所有未被具名渲染器认领的工具调用。 useDefaultRenderTool( { render: ({ name, parameters, status, result }) ( CustomCatchallRenderer name{name} parameters{parameters} status{status as CatchallToolStatus} result{result} / ), }, [], ); useSuggestions(); return ( CopilotChat agentIdtool-rendering-custom-catchall classNameh-full rounded-2xl / ); }布局层与 QA 文档描述一致外层flex justify-center items-center h-screen w-full使聊天界面居中且占满全高聊天容器max-w-4xl限宽、rounded-2xl圆角。几个关键点useDefaultRenderTool就是useRenderTool({ name: * })它注册的是默认通配级别。源码注释明确写为 a convenience wrapper arounduseRenderTool({ name: *, ... })——即这个渲染器只在没有具名渲染器匹配时才被调用。在这个 demo 里没有注册任何具名渲染器因此所有工具调用必然走它hooks 从copilotkit/react-core/v2导入CopilotKit、CopilotChat、useDefaultRenderTool这是 v2 核心包的导出路径useSuggestions来自同目录的 suggestions.ts通过useConfigureSuggestions提供 4 个建议 pill建议标题触发消息Weather in SFWhats the weather in San Francisco?Find flightsFind flights from SFO to JFK.Roll a d20Roll a 20-sided die.Chain toolsChain a few tools in this single turn: get the weather in Tokyo, search flights from SFO to Tokyo, and roll a d20.available: always表示建议始终可用。点击建议会填充输入框或直接发送消息QA 第 1 节的要求其中 Chain tools 用于触发链式工具调用验证多张卡片连续渲染。4. 品牌化通配卡片CustomCatchallRenderer 的结构与状态机渲染器本体在 custom-catchall-renderer.tsx。它接收四个入参name工具名、status三态、parameters参数对象、result结果字符串输出一张 shadcn 风格的Card /。4.1 状态机定义export type CatchallToolStatus inProgress | executing | complete;三个内部状态在describeStatus中映射为对外可见的状态徽章QA 文档提到的amber → lavender/indigo → green渐变即来自这里内部状态徽章文案徽章变体状态圆点inProgressstreamingwarningbg-amber-500 animate-pulse琥珀色呼吸动画executingrunningsecondarybg-neutral-500 animate-pulse灰紫色呼吸动画completedonesuccessbg-emerald-500稳定绿色QA 文档中的过渡streaming→running→done即对应这三个状态的顺序流转。4.2 卡片结构与 contenteditable="false">【免费下载链接】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），仅供参考