CopilotKit × Google ADK：工具渲染与推理链（Tool Rendering + Reasoning Chain）Demo 的架构原理与 QA 验证指南

CopilotKit × Google ADK工具渲染与推理链Tool Rendering Reasoning ChainDemo 的架构原理与 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本指南以 QA 文档 为骨架面向 CopilotKit 2.x 与 Google ADKAgent Development Kit集成中的tool-rendering-reasoning-chaindemo逐一拆解其前置条件、测试步骤与期望结果并借助仓库中的前端渲染器、Python Agent 与 Playwright 端到端测试说明推理 token 与顺序工具卡片在同一消息视图内交错渲染这一能力是如何实现的、又该如何验证。文档定位一份 testing 类 demo 的 QA 清单showcase/integrations/google-adk/qa/tool-rendering-reasoning-chain.md是一份精简的 QA 测试清单原文明确自述为为栏目完整性而编写的占位文档Stub并注明该 demo 属于 testing 类型不需要完整的人工核对清单full manual checklist。它的核心内容可以压缩为三句话前置条件demo 已部署且可访问Agent 后端健康。测试步骤访问/demos/tool-rendering-reasoning-chain→ 发送多工具提示词如 Whats the weather in Tokyo?并验证推理块与顺序工具卡片WeatherCard、FlightListCard或自定义兜底渲染器交错出现 → 验证推理 token 与工具卡片同屏流式渲染。期望结果页面无错误加载推理 token 与工具调用卡片在单一顺序链中并排展示且每个工具匹配其类型化渲染器。清单虽然简短但其背后的 demo 在整个集成中拥有完整的实现链。在 manifest.yaml 中该 demo 的登记信息是id: tool-rendering-reasoning-chain、名称 Tool Rendering Reasoning Chain (testing)、描述 Sequential tool calls with reasoning tokens rendered side-by-side、标签generative-ui并高亮了四个核心文件agent、公共工具定义、页面实现 与 运行时路由。仓库中真正承担该 demo 自动化 QA 职责的是配套的 Playwright 测试本篇将把这份手工清单与自动化断言相互印证。前置条件Demo 已部署且 Agent 后端健康QA 文档的两条前置条件对应着该集成前端 Next.js 后端 Python ADK的部署拓扑可以从运行时路由源码中看清前端通过/api/copilotkit暴露CopilotRuntime每个 agent 名称对应一个HttpAgent其 URL 为AGENT_URL / agentName其中AGENT_URL默认指向http://localhost:8000见 route.ts。agentNames数组中显式包含了tool-rendering-reasoning-chain见 route.ts路由注释说明Python 侧agent_server.py会为每个 demo 在/agent_name挂载一个 ADKAgent middleware。路由的GET处理器提供了健康探测访问/api/copilotkit会返回agent_statusreachable/error/unreachable以及GOOGLE_API_KEY是否已设置见 route.ts。因此Agent 后端健康可以通过该接口直接确认同时GOOGLE_API_KEY环境变量是驱动 Gemini 模型所必需的。从 manifest.yaml 的描述可知该集成的每个 demo 都是一个由 Gemini 驱动的 ADKLlmAgent通过 ag-ui-adk 中间件暴露给 React 侧的 CopilotKit 组件copilotkit_version为 2.0.0见 manifest.yaml。这意味着要复现 QA 场景需要同时保证 Python 后端8000 端口与 Next.js 前端均处于运行状态。被测对象一次多工具提示词的完整渲染链路QA 文档的测试步骤一要求发送多工具提示词要理解这条链路需要分别看后端与前端两侧。后端开启思考模式的 ADK Agent工具渲染推理链 Agent 是一个标准的LlmAgent工具面为[get_weather, search_flights, get_stock_price, roll_dice]与其它 tool-rendering 变体基本一致用roll_dice替换了roll_d20以便用sides参数编排 d20→d6 对比链见 tool_rendering_common.py。通过generate_content_configtypes.GenerateContentConfig(thinking_configtypes.ThinkingConfig(include_thoughtsTrue, thinking_budget-1))开启 Gemini 思考模式使推理 token 与顺序工具调用交错产出——这正是该 demo 与纯 tool-rendering demo 的差异点docstring 中将其描述为 Gemini 3.1 thinking mode。after_model_callbackstop_on_terminal_text负责在模型输出终止文本时收尾。真正让顺序链发生的是指令词。TOOL_RENDERING_REASONING_CHAIN_INSTRUCTION 明确要求 Agent 养成一个用户问题至少连续调用两个工具的习惯并给出了四条默认链用户请求默认工具链查询某城市天气get_weather(city)→search_flights(SFO, city)查询某股票行情get_stock_price(ticker)→get_stock_price(对比标的)掷一个 20 面骰roll_dice(sides20)→roll_dice(其它面数)查询两地航班search_flights(a, b)→get_weather(b)配套的 mock 工具均为确定性实现get_weather固定返回 68°F、湿度 55、风速 10、Sunny见 tool_rendering_common.pysearch_flights返回 United UA231、Delta DL412、JetBlue B6722 三条航班见 tool_rendering_common.pyget_stock_price与roll_dice支持通过可选参数注入确定性数值便于测试回放。前端一个 cell 组合两种既有模式page.tsx 的注释点明了设计意图这个 cell 把两个此前分离的模式组合进同一消息视图——推理渲染复用reasoning-customcell 的做法通过messageView.reasoningMessage槽位注入自定义ReasoningBlock。顺序工具渲染复用tool-rendering主 cell 的做法get_weather → WeatherCard、search_flights → FlightListCard、其余工具 → 自定义兜底渲染器。整体接线如下见 page.tsxCopilotKit runtimeUrl/api/copilotkit agenttool-rendering-reasoning-chain建立运行时连接useRenderTool为get_weather参数z.object({ location: z.string() })与search_flights参数z.object({ origin, destination })注册类型化渲染器useDefaultRenderTool注册通配渲染器捕获get_stock_price、roll_dice等所有未被命名注册认领的工具useConfigureSuggestions注入三条多工具提示词建议Compare two stocks、Chain of dice rolls、Flights destination weatherCopilotChat agentIdtool-rendering-reasoning-chain messageView{{ reasoningMessage: ReasoningBlock as typeof CopilotChatReasoningMessage }} /把推理消息槽位替换为自定义组件。测试步骤一进入 /demos/tool-rendering-reasoning-chain 并确认页面加载对应 QA 文档导航到/demos/tool-rendering-reasoning-chain。自动化测试对此做了镜像断言见 spec输入框composer可见、三条建议 pill 全部可见并且页面初始状态下不存在任何weather-card、flight-list-card、custom-catchall-card或reasoning-block——说明工具卡片与推理块只会在 Agent 真正产出消息后挂载。页面加载无错误还隐含一层要求CopilotChat 绑定的agentId必须在运行时中注册否则会抛出useAgent: Agent ... not found一类错误。tool-rendering-reasoning-chain已列入 route.ts 的agentNames因此运行时能将其解析到http://localhost:8000/tool-rendering-reasoning-chain。测试步骤二多工具提示词下推理块与顺序工具卡片交错渲染QA 文档要求发送多工具提示词如 Whats the weather in Tokyo?并验证推理块与顺序工具卡片交错出现。在真实复现时直接点击三条建议 pill 是最稳妥的路径因为每条 pill 都对应一段确定性的两段式工具链Compare two stocksget_stock_price(AAPL)→get_stock_price(MSFT)→ 对比总结全部走兜底渲染器2 张custom-catchall-card且data-tool-nameget_stock_priceChain of dice rollsroll_dice(sides20)→roll_dice(sides6)→ 对比2 张data-tool-nameroll_dice的兜底卡片Flights destination weathersearch_flights(SFO, JFK)→get_weather(JFK)→ 出行计划各自走品牌化渲染器flight-list-card与weather-card各 1 张不得出现兜底卡片见 spec。每个工具匹配其类型化渲染器的对应关系后端工具前端渲染器关键特征get_weatherWeatherCard城市名、温度、湿度、风速、天气 emoji运行中显示 Fetching weather...search_flightsFlightListCard起降地、结果数徽章、航班列表航司/航班号/时间/价格运行中显示骨架屏其余所有工具CustomCatchallRenderer工具名、状态徽章streaming → running → done、格式化 Arguments 与 Result两个值得注意的工程细节工具结果到达前端时可能是字符串Agent 输出 JSON也可能是已解析对象parseJsonResult 统一处理两种形态解析失败则回退为{}渲染器据此优雅降级。兜底渲染器的状态徽章由status驱动inProgress显示 streaming、executing显示 running、complete显示 done见 custom-catchall-renderer.tsx这就是顺序链在视觉上逐张卡片推进的机制。测试步骤三推理 token 流式进入自定义 ReasoningBlock 槽位QA 文档要求验证推理 token 流式渲染进自定义ReasoningBlock槽位与工具卡片处于同一消息视图。这一步的实现完全落在前端CopilotChat的messageView.reasoningMessage槽位被替换为ReasoningBlockpage.tsx。类型层面将其断言为typeof CopilotChatReasoningMessage保证与内置槽位契约兼容。ReasoningBlock 接收message: ReasoningMessage类型来自ag-ui/core、messages与isRunning并展示三种状态isStreaming isRunning isLatest当前消息仍在流式产出→ 显示 Thinking…已有内容message.content非空→ 显示 Agent reasoning 并渲染斜体思考文本否则显示 …。每个推理块都带有data-testidreasoning-block供 e2e 精确定位。由此推理 token 与工具卡片并排出现的本质是Agent 在同一条消息流中先产出reasoning角色的消息再依次产出各工具调用前端分别将它们路由到reasoningMessage槽位与useRenderTool/useDefaultRenderTool注册的渲染器最终形成思考块 → 工具卡片 1 → 思考块 → 工具卡片 2 → 总结的单条顺序链。这解释了 QA 文档每个工具匹配其类型化渲染器的期望结果。顺带一提manifest.yaml 的not_supported_features中列出了reasoning-default-render可以推断该集成下内置的默认推理渲染不受支持这正是 demo 必须显式提供自定义reasoningMessage槽位的原因。期望结果逐条对照QA 文档的两条期望结果可以直接映射到源码与测试期望结果验证方式依据页面无错误加载输入框与 3 条建议 pill 可见初始无工具卡片/推理块spec 首条用例推理 token 与工具卡片在单一顺序链中并排每条 pill 渲染出 2 张对应工具卡片 至少 1 个推理块卡片间无卸载顺序链断言每个工具匹配类型化渲染器get_weather/search_flights走品牌化卡片且不出现兜底卡片get_stock_price/roll_dice走兜底卡片spec 第三条用例把 QA 清单固化为自动化e2e 回归测试仓库把这份手工 QA 清单升级为可重复执行的 Playwright 测试其中第四条用例同一线程内顺序点击三条 pill是关键的回归防线spec三轮点击后分别断言推理块数量递增≥1、≥2、≥3证明每一轮对话都产出了新的推理而非复用上一轮断言前两轮的股票卡片与骰子卡片依然存在无中途卸载为覆盖三轮 × 两段工具链 × LLM mock 延迟将用例超时拉长到 240 秒。测试注释中还记录了一段真实的回归背景AG-UI 协议中的reasoning角色消息曾在ag-ui/langgraph的消息转换器中触发 message role is not supported 异常导致同一线程内第二次点击 pill 时以INCOMPLETE_STREAM崩溃运行时在LangGraphAgent.run中加入 reasoning-role 过滤后修复。该顺序点击用例正是为了锁死这类跨轮次问题——尽管本 demo 走的是 Google ADK 后端但其共享的 aimock fixture 与 e2e 规范同时服务于 langgraph-python 变体见 tool_rendering_common.py 模块注释。本地复现与调试建议运行环境启动 Python 后端监听 8000 端口由AGENT_URL指向并启动 Next.js 前端应用设置GOOGLE_API_KEY。可通过GET /api/copilotkit的健康探针确认后端可达与密钥配置状态。手动复现打开/demos/tool-rendering-reasoning-chain点击任一条建议 pill比自由输入更能触发确定性的两段式链重点观察推理块从 Thinking… 切换到 Agent reasoning、航班卡片由骨架屏变为结果列表、兜底卡片状态徽章经历 streaming → running → done。自动化复现运行配套 e2e 测试其data-testid契约reasoning-block、weather-card、flight-list-card、custom-catchall-card、copilot-suggestion可直接作为手工验证时的 DOM 定位参考。调试提示若某个工具未按预期渲染先确认它是否被某个useRenderTool命名注册认领——被认领的工具绝不进入兜底渲染器若推理块缺失检查后端thinking_config是否生效、以及messageView.reasoningMessage槽位是否被覆盖。综上这份看似精简的 QA 文档实际上浓缩了 CopilotKit 与 Google ADK 集成中推理可视化 顺序工具调用渲染这一能力的完整验证路径从 Gemini 思考模式的开启、链式工具指令的编排到前端槽位替换与类型化/兜底渲染器的分工再到用 Playwright 将手工清单固化为回归防线。读者若想在自有项目中复刻该模式可直接以 page.tsx 与 tool_rendering_reasoning_chain_agent.py 为蓝本后端打开思考模式并给出链式调用指令前端同时注册messageView.reasoningMessage槽位与按工具分派的useRenderTool/useDefaultRenderTool即可获得思考与工具调用并排交错的对话体验。【免费下载链接】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），仅供参考