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

CopilotKit × Google ADK：工具渲染与推理链（Tool Rendering + Reasoning Chain）Demo 的架构原理与 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 ADK（Agent 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→ 发送多工具提示词（如 "What's 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_status（reachable/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_config=types.GenerateContentConfig(thinking_config=types.ThinkingConfig(include_thoughts=True, thinking_budget=-1))开启 Gemini 思考模式，使推理 token 与顺序工具调用交错产出——这正是该 demo 与纯 tool-rendering demo 的差异点（docstring 中将其描述为 "Gemini 3.1 thinking mode"）。
after_model_callback=stop_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(sides=20)`→`roll_dice(其它面数)`
查询两地航班	`search_flights(a, b)`→`get_weather(<b>)`

配套的 mock 工具均为确定性实现：get_weather固定返回 68°F、湿度 55、风速 10、Sunny（见 tool_rendering_common.py）；search_flights返回 United UA231、Delta DL412、JetBlue B6722 三条航班（见 tool_rendering_common.py）；get_stock_price与roll_dice支持通过可选参数注入确定性数值，便于测试回放。

前端：一个 cell 组合两种既有模式

page.tsx 的注释点明了设计意图：这个 cell 把两个此前分离的模式组合进同一消息视图——

推理渲染：复用reasoning-customcell 的做法，通过messageView.reasoningMessage槽位注入自定义ReasoningBlock。
顺序工具渲染：复用tool-rendering主 cell 的做法，get_weather → WeatherCard、search_flights → FlightListCard、其余工具 → 自定义兜底渲染器。

整体接线如下（见 page.tsx）：

<CopilotKit runtimeUrl="/api/copilotkit" agent="tool-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 weather；
<CopilotChat agentId="tool-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 文档要求发送多工具提示词（如 "What's the weather in Tokyo?"）并验证推理块与顺序工具卡片交错出现。在真实复现时，直接点击三条建议 pill 是最稳妥的路径，因为每条 pill 都对应一段确定性的两段式工具链：

Compare two stocks：get_stock_price(AAPL)→get_stock_price(MSFT)→ 对比总结（全部走兜底渲染器，2 张custom-catchall-card，且data-tool-name="get_stock_price"）；
Chain of dice rolls：roll_dice(sides=20)→roll_dice(sides=6)→ 对比（2 张data-tool-name="roll_dice"的兜底卡片）；
Flights + destination weather：search_flights(SFO, JFK)→get_weather(JFK)→ 出行计划（各自走品牌化渲染器：flight-list-card与weather-card各 1 张，不得出现兜底卡片，见 spec）。

"每个工具匹配其类型化渲染器"的对应关系：

后端工具	前端渲染器	关键特征
`get_weather`	WeatherCard	城市名、温度、湿度、风速、天气 emoji；运行中显示 "Fetching weather..."
`search_flights`	FlightListCard	起降地、结果数徽章、航班列表（航司/航班号/时间/价格）；运行中显示骨架屏
其余所有工具	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槽位被替换为ReasoningBlock（page.tsx）。类型层面将其断言为typeof CopilotChatReasoningMessage，保证与内置槽位契约兼容。
ReasoningBlock 接收message: ReasoningMessage（类型来自@ag-ui/core）、messages与isRunning，并展示三种状态：
- isStreaming = isRunning && isLatest（当前消息仍在流式产出）→ 显示 "Thinking…"；
- 已有内容（message.content非空）→ 显示 "Agent reasoning" 并渲染斜体思考文本；
- 否则显示 "…"。
每个推理块都带有data-testid="reasoning-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，即可获得"思考与工具调用并排交错"的对话体验。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考