拓冰网站定制 
CopilotKit Agentic Chat 推理能力实战指南基于 Agno 的 Reasoning 卡片实现与 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 Agno 集成中Agentic Chat (Reasoning)演示的完整实现链路从 Agno 后端推理 Agent 的配置、AG-UIREASONING_MESSAGE_*事件的合成到前端 reasoning 卡片的默认/自定义渲染最后给出与 QA 文档一一对应的可执行验证步骤与 Playwright 自动化测试。读完本文你将掌握如何在 CopilotKit 项目中让 Agent 的思考过程以独立卡片形式流式呈现并能够自主编写、复现和自动化这一 QA 用例。前置条件与运行环境根据 QA 文档 的定义验证该演示需要满足两个前置条件前置条件说明仓库中的对应实现演示已部署前端页面挂在/demos/agentic-chat-reasoning路由下manifest.yaml 的 demos 定义与 api/copilotkit/route.ts 中的 agent 别名注册后端 Agent 健康Agno Agent 后端已加载reasoning_agent模块并服务在/reasoning/aguireasoning_agent.py agent_server.py从 route.ts 可以看到agentic-chat-reasoning与reasoning-default-render、tool-rendering-reasoning-chain、reasoning-default、reasoning-custom同属一个 reasoning 家族全部被映射到指向${AGENT_URL}/reasoning/agui的HttpAgent// showcase/integrations/agno/src/app/api/copilotkit/route.ts function createReasoningAgent() { return new HttpAgent({ url: ${AGENT_URL}/reasoning/agui }); } const reasoningAgentNames [ agentic-chat-reasoning, reasoning-default-render, tool-rendering-reasoning-chain, reasoning-default, reasoning-custom, ];其中AGENT_URL默认取http://localhost:8000可通过环境变量覆盖Next.js 的 CopilotKit runtime 通过 AG-UI 协议将请求代理到该后端。本地启动整套环境的命令在 package.json 中定义# 在 showcase/integrations/agno 目录下执行 pnpm dev # 等价于 # next dev --turbopack 前端端口 3000 # PYTHONPATH. python -m uvicorn agent_server:app --host 0.0.0.0 --port 8000 --reload Agno Agent 后端agent_server.py的main()中通过AgentOS.serve(..., portint(os.getenv(PORT, 8000)), loopasyncio)启动 uvicorn默认端口为 8000见 agent_server.py。整体链路一次带推理的对话如何呈现QA 文档的核心断言是发送问题后一条琥珀色的自定义推理卡片data-testidreasoning-block出现在最终助手回答之前。这条链路的完整数据流如下用户在前端/demos/agentic-chat-reasoning页面发送问题CopilotChat 将消息经/api/copilotkit交给 CopilotKit runtimeruntime 按 agent 名agentic-chat-reasoning路由到HttpAgent即后端的/reasoning/aguiAgno 后端_attach_reasoning_route挂载的自定义 AG-UI handler 启动一次 Agent 运行agent_server.py后端先发出RUN_STARTED收集模型的原生 reasoning 流或解析reasoning标签依次发射REASONING_MESSAGE_START→REASONING_MESSAGE_CONTENT→REASONING_MESSAGE_END随后发射TEXT_MESSAGE_*事件承载最终答案前端 CopilotChat 收到这些事件后将role reasoning的消息交给messageView.reasoningMessage槽位渲染——本项目演示中即自定义ReasoningBlock组件最终呈现为先卡片、后答案的视觉顺序。值得强调的是CopilotKit 在前端将 reasoning 作为一等消息类型处理。自定义槽位方案的原理注释reasoning-custom/page.tsx指出v2 的消息视图组件按message.role reasoning区分消息类型并通过reasoningMessage槽位渲染默认组件为CopilotChatReasoningMessage覆盖该槽位即官方支持的自定义途径。后端基石reasoning_agent 的刻意设计reasoning_agent.py 是整个推理演示的后端核心。它用一个 AgnoAgent同时支撑三个 reasoning 演示单元reasoning-custom、reasoning-default、tool-rendering-reasoning-chain其关键配置如下agent Agent( modelOpenAIChat(idgpt-4o-mini, timeout120), tools[get_weather, search_flights, get_stock_price, roll_dice], reasoningFalse, # 刻意关闭 Agno 原生多轮 CoT 循环 tool_call_limit10, descriptionYou are a helpful assistant. For each user question, first think step-by-step about the approach, then answer concisely. When the question calls for a tool, call it explicitly rather than guessing., instructionsREASONING STYLE: ..., )这里有两个极易被忽视的设计决策值得展开为什么reasoningFalseAgno 的reasoningTrue会触发一个最多reasoning_max_steps次串行 LLM 调用的 Chain-of-Thought 循环。这在代理/夹具环境aimock、D5 探针中会破坏 fixture 匹配——只有第一次调用能命中录制好的夹具后续调用要么穿透到真实 API慢且不确定要么直接失败。因此该演示刻意使用reasoningFalse即默认值改由agent_server.py中的自定义 AG-UI handler 从响应文本中合成REASONING_MESSAGE_*事件reasoning_agent.py。为了让模型产出可解析的推理内容系统提示词要求模型以reasoning.../reasoningXML 标签包裹思考过程再给出简洁答案。示例格式如下摘自 reasoning_agent.pyreasoning Step 1: Identify what the user is asking. Step 2: Consider which tool to use. Step 3: Formulate the answer. /reasoning Here is my answer...工具集与推理链扩展该 Agent 挂载了 4 个共享工具reasoning_agent.py工具签名用途get_weatherget_weather(location: str)返回指定地点的天气 JSONsearch_flightssearch_flights(flights: list[dict])生成 2 条航班并以富 A2UI 卡片展示get_stock_priceget_stock_price(ticker: str)返回股票模拟价格提示词建议拉取第二个相关代码作对比roll_diceroll_dice(sides: int 6)掷骰子默认 6 面这些工具让tool-rendering-reasoning-chain演示能呈现出完整的推理 → 工具调用 → 推理 → 工具调用链条供 catch-all 工具渲染器观察。需要注意的是与 CopilotKit 前端对接时工具的定位参数、返回 JSON 结构均由工具 docstring 与系统提示词约束例如search_flights要求航班字段包含airline、flightNumber、departureTime、status、price等这为后文 QA 中的工具渲染验证提供了数据前提。后端关键实现自定义 AG-UI Handler 如何合成推理事件QA 文档断言推理卡片出现在最终答案之前这背后是 agent_server.py 中_run_reasoning_agent与配套函数实现的协议级转换。Agno 自带的 AG-UI 流映射器async_stream_agno_response_as_agui_events对 reasoning 只发射STEP_STARTED/STEP_FINISHED而这并非 CopilotKit 前端期望的REASONING_MESSAGE_*事件因此必须替换为自定义 handler。原生推理通道reasoning_content_tee_native_reasoning生成器agent_server.py在不消费任何 chunk 的前提下透传 Agno 运行流同时把RunContentEvent.reasoning_content字段累积到reasoning_sinkasync for chunk in response_stream: if getattr(chunk, event, None) RunEvent.run_content: delta getattr(chunk, reasoning_content, None) if delta: reasoning_sink[text] reasoning_sink.get(text, ) delta yield chunk这里原生推理通道指的是 OpenAI 兼容的 chat-completions 流中delta.reasoning_content字段——这正是真实推理模型在生产环境中的输出通道也是 aimock 夹具通过其reasoning字段填充的通道。Agno 的OpenAIChat模型会把它暴露在每个RunContentEvent.reasoning_content上但 AG-UI 流映射器会将其丢弃所以这里的 tee 操作把它抢救回来。三级推理内容提取策略_run_reasoning_agentagent_server.py在运行结束后按优先级确定推理文本原生通道优先若native_reasoning[text]非空直接使用并从答案文本中剥离残留的reasoning标签防御性清理XML 标签回退否则用正则_REASONING_PATTERN re.compile(rreasoning(.*?)/reasoning, re.DOTALL | re.IGNORECASE)从完整文本中解析推理块剩余部分作为答案前缀模式回退若文本以reasoning:或reasoning step开头aimock 夹具的形态则整段文本同时作为推理与答案发射确保ReasoningBlock能渲染且会话中保留助手气泡。随后按固定顺序发射事件agent_server.pyREASONING_MESSAGE_STARTrolereasoning REASONING_MESSAGE_CONTENTdelta推理文本 REASONING_MESSAGE_END TEXT_MESSAGE_STARTroleassistant TEXT_MESSAGE_CONTENTdelta答案 TEXT_MESSAGE_END 如有缓冲的 TOOL_CALL_START / ARGS / END / RESULT 事件 RUN_FINISHED代码注释特别强调即使推理为空也必须发射一条文本消息否则前端默认CopilotChat转录区会什么都不显示reasoning 事件本身不产生可见气泡。此外TOOL_CALL_RESULT必须被缓冲否则会丢失推理链演示中的工具结果渲染。路由挂载方式_attach_reasoning_routeagent_server.py在 FastAPI 上注册POST /reasoning/agui通过EventEncoder将事件编码为text/event-stream流式响应并设置 CORS 头。路由在agent_os.get_app()之后手动挂载agent_server.py替换掉 Agno 自带的AGUI(agentreasoning_agent, prefix/reasoning)接口。前端呈现默认渲染 vs 自定义槽位QA 文档检查的是自定义卡片但仓库还提供了同一后端的默认渲染对照组两者共用/reasoning/agui差异仅在于前端是否覆盖messageView.reasoningMessage槽位零配置的默认渲染reasoning-defaultreasoning-default/page.tsx 不覆盖任何槽位function Chat() { useReasoningDefaultSuggestions(); return CopilotChat agentId{AGENT_ID} classNameh-full rounded-2xl /; }推理消息由内置的CopilotChatReasoningMessage组件渲染呈现为带 Thinking… / Thought for X seconds 头部的可折叠卡片展开后可查看逐步思考内容见 reasoning-default-render.md 的验证要点。自定义琥珀色卡片QA 文档验证的对象reasoning-custom/page.tsx 通过messageView.reasoningMessage槽位注入自定义组件CopilotChat agentId{AGENT_ID} classNameh-full rounded-2xl messageView{{ reasoningMessage: ReasoningBlock as unknown as typeof CopilotChatReasoningMessage, }} /ReasoningBlock 组件 是 QA 文档所有断言的落点其实现要点包括根节点带data-testidreasoning-block供 QA 与 Playwright 定位样式为琥珀色/淡紫色横幅bg-[#BEC2FF1A]、圆角边框内嵌一个 Reasoning 胶囊标签data-testid可定位文本通过isRunning isLatest判断流式状态运行中显示 Thinking…运行结束后有内容时显示 Agent reasoning恰好对应 QA 文档第 2 节的两个断言推理内容渲染在whitespace-pre-wrap italic样式的 div 中——斜体正是 QA 文档推理内容与答案视觉区分的断言基础无内容且未运行时显示 … 占位。推理链演示推理 顺序工具调用tool-rendering-reasoning-chain/page.tsx 把自定义推理槽位与工具渲染组合进同一页面get_weather→WeatherCard、search_flights→FlightListCard其余工具走CustomCatchallRenderer并内置了三条建议提示词对比股票、掷骰子链、航班目的地天气与后端 4 个工具一一呼应。完整 QA 验证步骤含实现级解释以下按 QA 文档 的原始测试步骤展开并为每一步补充源码层面的依据1. 基础功能验证导航访问/demos/agentic-chat-reasoning。路由可访问性依赖 Next.js 页面存在及agentic-chat-reasoning在 route.ts 中的别名注册。发送问题发送Explain why the sky is blue in two short stepsQA 文档原文。注意 suggestions.ts 的提示推理模型对要求展示思维链的元提示通常拒绝输出推理摘要必须使用一个真正需要多步思考的具体问题该演示内置的 Show reasoning 建议提示词为Explain step by step why the sky appears blue during the day but red at sunset.。这也是 QA 文档把问题限定为两个简短步骤解释天空为何是蓝色的原因。断言卡片出现data-testidreasoning-block的推理卡片出现在最终答案之前。实现上由后端事件顺序保证先REASONING_MESSAGE_*后TEXT_MESSAGE_*前端按事件顺序渲染。断言卡片内容卡片显示 Reasoning 胶囊标签 流式思考内容。2. 特性专项检查运行中状态Agent 运行时卡片标题显示 Thinking…——对应isStreaming isRunning isLatest时ReasoningBlock渲染的分支reasoning-block.tsx。运行完成状态结束后标题切换为 Agent reasoning——对应hasContent分支。视觉区分推理内容以斜体.italic渲染与常规答案气泡在字体风格和背景色上均有区分。3. 错误处理检查无未捕获控制台错误后端任何异常都会被_run_reasoning_agent的except Exception分支捕获并转换为RUN_ERROR事件而非静默丢弃见 agent_server.py 对内层 RUN_ERROR 的透传逻辑前端则不应出现未捕获异常。自动化回归Playwright 测试QA 文档的每个手工步骤都对应了仓库中的自动化用例。最直接的等价实现是 agentic-chat-reasoning.spec.tstest(reasoning block surfaces after sending a prompt, async ({ page }) { const input page.getByPlaceholder(/type a message/i); await input.fill(Why is the sky blue? Think step by step.); await input.press(Enter); await expect( page.locator([data-testidreasoning-block]).first(), ).toBeVisible({ timeout: 60000 }); });更完整的断言族位于 reasoning-custom.spec.ts它覆盖了 QA 文档的全部三个层面QA 检查项对应测试卡片先于答案出现reasoning prompt renders a reasoning-block before the answerThinking… → Agent reasoning 状态切换reasoning-block label flips from Thinking to Agent reasoning斜体推理内容reasoning-block accumulates italic reasoning content断言.italic可见建议提示词可复现Show reasoning suggestion pill fires the reasoning prompt这些测试通过data-testid、role、稳定文本选择器断言不对 LLM 输出文本做断言从而在 aimock 夹具showcase/aimock/d5-all.json中带reasoning字段的夹具下可确定性复现无需真实 LLM 调用。本地调试时点击 Show reasoning 建议胶囊即可一键复现流式推理体验。常见问题与排查结合源码实现QA 与日常使用中最可能遇到的三个问题及根因如下1. 发送后推理卡片一直不出现最可能是提示词问题。推理模型只在存在真正需要思考的具体问题时才输出推理摘要元提示如 show your reasoning step by step会被模型视为要求泄露思维链而拒绝。改用内置的 Show reasoning 建议或 QA 文档中的具体问题即可suggestions.ts。2. 推理显示但答案气泡缺失前端默认CopilotChat中 reasoning 事件不产生可见气泡。后端_run_reasoning_agent已保证无条件发射TEXT_MESSAGE_*agent_server.py若仍缺失应检查事件流是否被中间层截断。3. 真实推理模型 vs 夹具表现不一致仓库的 reasoning 实现以原生reasoning_content通道优先、XML 标签解析兜底的策略同时兼容生产推理模型与 aimock 夹具。若你自行接入不支持reasoning_content字段的模型应确保系统提示词中保留reasoning.../reasoning标签约定否则将退化为无推理内容的分支。小结Agentic Chat (Reasoning) 演示展示了 CopilotKit 将 Agent 思维链作为一等消息类型的完整闭环后端通过自定义 AG-UI handler 将 Agno 模型的原生reasoning_content通道或reasoning标签转换为标准的REASONING_MESSAGE_*事件前端通过messageView.reasoningMessage槽位即可用零配置默认卡片或自定义组件呈现。QA 文档定义的卡片先于答案、状态切换、视觉区分、无控制台错误四条验收线既有 Playwright 用例 可自动回归也有 reasoning-block.tsx 与 agent_server.py 的源码可逐行追溯是一套可复制到其他 Agent 框架集成中的推理呈现范式。相关对照文档可进一步参阅 reasoning-default-render.md 与 PARITY_NOTES.md。【免费下载链接】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），仅供参考 CopilotKit Agentic Chat 推理能力实战指南：基于 Agno 的 Reasoning 卡片实现与 QA 验证
CopilotKit Agentic Chat 推理能力实战指南基于 Agno 的 Reasoning 卡片实现与 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 Agno 集成中Agentic Chat (Reasoning)演示的完整实现链路从 Agno 后端推理 Agent 的配置、AG-UIREASONING_MESSAGE_*事件的合成到前端 reasoning 卡片的默认/自定义渲染最后给出与 QA 文档一一对应的可执行验证步骤与 Playwright 自动化测试。读完本文你将掌握如何在 CopilotKit 项目中让 Agent 的思考过程以独立卡片形式流式呈现并能够自主编写、复现和自动化这一 QA 用例。前置条件与运行环境根据 QA 文档 的定义验证该演示需要满足两个前置条件前置条件说明仓库中的对应实现演示已部署前端页面挂在/demos/agentic-chat-reasoning路由下manifest.yaml 的 demos 定义与 api/copilotkit/route.ts 中的 agent 别名注册后端 Agent 健康Agno Agent 后端已加载reasoning_agent模块并服务在/reasoning/aguireasoning_agent.py agent_server.py从 route.ts 可以看到agentic-chat-reasoning与reasoning-default-render、tool-rendering-reasoning-chain、reasoning-default、reasoning-custom同属一个 reasoning 家族全部被映射到指向${AGENT_URL}/reasoning/agui的HttpAgent// showcase/integrations/agno/src/app/api/copilotkit/route.ts function createReasoningAgent() { return new HttpAgent({ url: ${AGENT_URL}/reasoning/agui }); } const reasoningAgentNames [ agentic-chat-reasoning, reasoning-default-render, tool-rendering-reasoning-chain, reasoning-default, reasoning-custom, ];其中AGENT_URL默认取http://localhost:8000可通过环境变量覆盖Next.js 的 CopilotKit runtime 通过 AG-UI 协议将请求代理到该后端。本地启动整套环境的命令在 package.json 中定义# 在 showcase/integrations/agno 目录下执行 pnpm dev # 等价于 # next dev --turbopack 前端端口 3000 # PYTHONPATH. python -m uvicorn agent_server:app --host 0.0.0.0 --port 8000 --reload Agno Agent 后端agent_server.py的main()中通过AgentOS.serve(..., portint(os.getenv(PORT, 8000)), loopasyncio)启动 uvicorn默认端口为 8000见 agent_server.py。整体链路一次带推理的对话如何呈现QA 文档的核心断言是发送问题后一条琥珀色的自定义推理卡片data-testidreasoning-block出现在最终助手回答之前。这条链路的完整数据流如下用户在前端/demos/agentic-chat-reasoning页面发送问题CopilotChat 将消息经/api/copilotkit交给 CopilotKit runtimeruntime 按 agent 名agentic-chat-reasoning路由到HttpAgent即后端的/reasoning/aguiAgno 后端_attach_reasoning_route挂载的自定义 AG-UI handler 启动一次 Agent 运行agent_server.py后端先发出RUN_STARTED收集模型的原生 reasoning 流或解析reasoning标签依次发射REASONING_MESSAGE_START→REASONING_MESSAGE_CONTENT→REASONING_MESSAGE_END随后发射TEXT_MESSAGE_*事件承载最终答案前端 CopilotChat 收到这些事件后将role reasoning的消息交给messageView.reasoningMessage槽位渲染——本项目演示中即自定义ReasoningBlock组件最终呈现为先卡片、后答案的视觉顺序。值得强调的是CopilotKit 在前端将 reasoning 作为一等消息类型处理。自定义槽位方案的原理注释reasoning-custom/page.tsx指出v2 的消息视图组件按message.role reasoning区分消息类型并通过reasoningMessage槽位渲染默认组件为CopilotChatReasoningMessage覆盖该槽位即官方支持的自定义途径。后端基石reasoning_agent 的刻意设计reasoning_agent.py 是整个推理演示的后端核心。它用一个 AgnoAgent同时支撑三个 reasoning 演示单元reasoning-custom、reasoning-default、tool-rendering-reasoning-chain其关键配置如下agent Agent( modelOpenAIChat(idgpt-4o-mini, timeout120), tools[get_weather, search_flights, get_stock_price, roll_dice], reasoningFalse, # 刻意关闭 Agno 原生多轮 CoT 循环 tool_call_limit10, descriptionYou are a helpful assistant. For each user question, first think step-by-step about the approach, then answer concisely. When the question calls for a tool, call it explicitly rather than guessing., instructionsREASONING STYLE: ..., )这里有两个极易被忽视的设计决策值得展开为什么reasoningFalseAgno 的reasoningTrue会触发一个最多reasoning_max_steps次串行 LLM 调用的 Chain-of-Thought 循环。这在代理/夹具环境aimock、D5 探针中会破坏 fixture 匹配——只有第一次调用能命中录制好的夹具后续调用要么穿透到真实 API慢且不确定要么直接失败。因此该演示刻意使用reasoningFalse即默认值改由agent_server.py中的自定义 AG-UI handler 从响应文本中合成REASONING_MESSAGE_*事件reasoning_agent.py。为了让模型产出可解析的推理内容系统提示词要求模型以reasoning.../reasoningXML 标签包裹思考过程再给出简洁答案。示例格式如下摘自 reasoning_agent.pyreasoning Step 1: Identify what the user is asking. Step 2: Consider which tool to use. Step 3: Formulate the answer. /reasoning Here is my answer...工具集与推理链扩展该 Agent 挂载了 4 个共享工具reasoning_agent.py工具签名用途get_weatherget_weather(location: str)返回指定地点的天气 JSONsearch_flightssearch_flights(flights: list[dict])生成 2 条航班并以富 A2UI 卡片展示get_stock_priceget_stock_price(ticker: str)返回股票模拟价格提示词建议拉取第二个相关代码作对比roll_diceroll_dice(sides: int 6)掷骰子默认 6 面这些工具让tool-rendering-reasoning-chain演示能呈现出完整的推理 → 工具调用 → 推理 → 工具调用链条供 catch-all 工具渲染器观察。需要注意的是与 CopilotKit 前端对接时工具的定位参数、返回 JSON 结构均由工具 docstring 与系统提示词约束例如search_flights要求航班字段包含airline、flightNumber、departureTime、status、price等这为后文 QA 中的工具渲染验证提供了数据前提。后端关键实现自定义 AG-UI Handler 如何合成推理事件QA 文档断言推理卡片出现在最终答案之前这背后是 agent_server.py 中_run_reasoning_agent与配套函数实现的协议级转换。Agno 自带的 AG-UI 流映射器async_stream_agno_response_as_agui_events对 reasoning 只发射STEP_STARTED/STEP_FINISHED而这并非 CopilotKit 前端期望的REASONING_MESSAGE_*事件因此必须替换为自定义 handler。原生推理通道reasoning_content_tee_native_reasoning生成器agent_server.py在不消费任何 chunk 的前提下透传 Agno 运行流同时把RunContentEvent.reasoning_content字段累积到reasoning_sinkasync for chunk in response_stream: if getattr(chunk, event, None) RunEvent.run_content: delta getattr(chunk, reasoning_content, None) if delta: reasoning_sink[text] reasoning_sink.get(text, ) delta yield chunk这里原生推理通道指的是 OpenAI 兼容的 chat-completions 流中delta.reasoning_content字段——这正是真实推理模型在生产环境中的输出通道也是 aimock 夹具通过其reasoning字段填充的通道。Agno 的OpenAIChat模型会把它暴露在每个RunContentEvent.reasoning_content上但 AG-UI 流映射器会将其丢弃所以这里的 tee 操作把它抢救回来。三级推理内容提取策略_run_reasoning_agentagent_server.py在运行结束后按优先级确定推理文本原生通道优先若native_reasoning[text]非空直接使用并从答案文本中剥离残留的reasoning标签防御性清理XML 标签回退否则用正则_REASONING_PATTERN re.compile(rreasoning(.*?)/reasoning, re.DOTALL | re.IGNORECASE)从完整文本中解析推理块剩余部分作为答案前缀模式回退若文本以reasoning:或reasoning step开头aimock 夹具的形态则整段文本同时作为推理与答案发射确保ReasoningBlock能渲染且会话中保留助手气泡。随后按固定顺序发射事件agent_server.pyREASONING_MESSAGE_STARTrolereasoning REASONING_MESSAGE_CONTENTdelta推理文本 REASONING_MESSAGE_END TEXT_MESSAGE_STARTroleassistant TEXT_MESSAGE_CONTENTdelta答案 TEXT_MESSAGE_END 如有缓冲的 TOOL_CALL_START / ARGS / END / RESULT 事件 RUN_FINISHED代码注释特别强调即使推理为空也必须发射一条文本消息否则前端默认CopilotChat转录区会什么都不显示reasoning 事件本身不产生可见气泡。此外TOOL_CALL_RESULT必须被缓冲否则会丢失推理链演示中的工具结果渲染。路由挂载方式_attach_reasoning_routeagent_server.py在 FastAPI 上注册POST /reasoning/agui通过EventEncoder将事件编码为text/event-stream流式响应并设置 CORS 头。路由在agent_os.get_app()之后手动挂载agent_server.py替换掉 Agno 自带的AGUI(agentreasoning_agent, prefix/reasoning)接口。前端呈现默认渲染 vs 自定义槽位QA 文档检查的是自定义卡片但仓库还提供了同一后端的默认渲染对照组两者共用/reasoning/agui差异仅在于前端是否覆盖messageView.reasoningMessage槽位零配置的默认渲染reasoning-defaultreasoning-default/page.tsx 不覆盖任何槽位function Chat() { useReasoningDefaultSuggestions(); return CopilotChat agentId{AGENT_ID} classNameh-full rounded-2xl /; }推理消息由内置的CopilotChatReasoningMessage组件渲染呈现为带 Thinking… / Thought for X seconds 头部的可折叠卡片展开后可查看逐步思考内容见 reasoning-default-render.md 的验证要点。自定义琥珀色卡片QA 文档验证的对象reasoning-custom/page.tsx 通过messageView.reasoningMessage槽位注入自定义组件CopilotChat agentId{AGENT_ID} classNameh-full rounded-2xl messageView{{ reasoningMessage: ReasoningBlock as unknown as typeof CopilotChatReasoningMessage, }} /ReasoningBlock 组件 是 QA 文档所有断言的落点其实现要点包括根节点带data-testidreasoning-block供 QA 与 Playwright 定位样式为琥珀色/淡紫色横幅bg-[#BEC2FF1A]、圆角边框内嵌一个 Reasoning 胶囊标签data-testid可定位文本通过isRunning isLatest判断流式状态运行中显示 Thinking…运行结束后有内容时显示 Agent reasoning恰好对应 QA 文档第 2 节的两个断言推理内容渲染在whitespace-pre-wrap italic样式的 div 中——斜体正是 QA 文档推理内容与答案视觉区分的断言基础无内容且未运行时显示 … 占位。推理链演示推理 顺序工具调用tool-rendering-reasoning-chain/page.tsx 把自定义推理槽位与工具渲染组合进同一页面get_weather→WeatherCard、search_flights→FlightListCard其余工具走CustomCatchallRenderer并内置了三条建议提示词对比股票、掷骰子链、航班目的地天气与后端 4 个工具一一呼应。完整 QA 验证步骤含实现级解释以下按 QA 文档 的原始测试步骤展开并为每一步补充源码层面的依据1. 基础功能验证导航访问/demos/agentic-chat-reasoning。路由可访问性依赖 Next.js 页面存在及agentic-chat-reasoning在 route.ts 中的别名注册。发送问题发送Explain why the sky is blue in two short stepsQA 文档原文。注意 suggestions.ts 的提示推理模型对要求展示思维链的元提示通常拒绝输出推理摘要必须使用一个真正需要多步思考的具体问题该演示内置的 Show reasoning 建议提示词为Explain step by step why the sky appears blue during the day but red at sunset.。这也是 QA 文档把问题限定为两个简短步骤解释天空为何是蓝色的原因。断言卡片出现data-testidreasoning-block的推理卡片出现在最终答案之前。实现上由后端事件顺序保证先REASONING_MESSAGE_*后TEXT_MESSAGE_*前端按事件顺序渲染。断言卡片内容卡片显示 Reasoning 胶囊标签 流式思考内容。2. 特性专项检查运行中状态Agent 运行时卡片标题显示 Thinking…——对应isStreaming isRunning isLatest时ReasoningBlock渲染的分支reasoning-block.tsx。运行完成状态结束后标题切换为 Agent reasoning——对应hasContent分支。视觉区分推理内容以斜体.italic渲染与常规答案气泡在字体风格和背景色上均有区分。3. 错误处理检查无未捕获控制台错误后端任何异常都会被_run_reasoning_agent的except Exception分支捕获并转换为RUN_ERROR事件而非静默丢弃见 agent_server.py 对内层 RUN_ERROR 的透传逻辑前端则不应出现未捕获异常。自动化回归Playwright 测试QA 文档的每个手工步骤都对应了仓库中的自动化用例。最直接的等价实现是 agentic-chat-reasoning.spec.tstest(reasoning block surfaces after sending a prompt, async ({ page }) { const input page.getByPlaceholder(/type a message/i); await input.fill(Why is the sky blue? Think step by step.); await input.press(Enter); await expect( page.locator([data-testidreasoning-block]).first(), ).toBeVisible({ timeout: 60000 }); });更完整的断言族位于 reasoning-custom.spec.ts它覆盖了 QA 文档的全部三个层面QA 检查项对应测试卡片先于答案出现reasoning prompt renders a reasoning-block before the answerThinking… → Agent reasoning 状态切换reasoning-block label flips from Thinking to Agent reasoning斜体推理内容reasoning-block accumulates italic reasoning content断言.italic可见建议提示词可复现Show reasoning suggestion pill fires the reasoning prompt这些测试通过data-testid、role、稳定文本选择器断言不对 LLM 输出文本做断言从而在 aimock 夹具showcase/aimock/d5-all.json中带reasoning字段的夹具下可确定性复现无需真实 LLM 调用。本地调试时点击 Show reasoning 建议胶囊即可一键复现流式推理体验。常见问题与排查结合源码实现QA 与日常使用中最可能遇到的三个问题及根因如下1. 发送后推理卡片一直不出现最可能是提示词问题。推理模型只在存在真正需要思考的具体问题时才输出推理摘要元提示如 show your reasoning step by step会被模型视为要求泄露思维链而拒绝。改用内置的 Show reasoning 建议或 QA 文档中的具体问题即可suggestions.ts。2. 推理显示但答案气泡缺失前端默认CopilotChat中 reasoning 事件不产生可见气泡。后端_run_reasoning_agent已保证无条件发射TEXT_MESSAGE_*agent_server.py若仍缺失应检查事件流是否被中间层截断。3. 真实推理模型 vs 夹具表现不一致仓库的 reasoning 实现以原生reasoning_content通道优先、XML 标签解析兜底的策略同时兼容生产推理模型与 aimock 夹具。若你自行接入不支持reasoning_content字段的模型应确保系统提示词中保留reasoning.../reasoning标签约定否则将退化为无推理内容的分支。小结Agentic Chat (Reasoning) 演示展示了 CopilotKit 将 Agent 思维链作为一等消息类型的完整闭环后端通过自定义 AG-UI handler 将 Agno 模型的原生reasoning_content通道或reasoning标签转换为标准的REASONING_MESSAGE_*事件前端通过messageView.reasoningMessage槽位即可用零配置默认卡片或自定义组件呈现。QA 文档定义的卡片先于答案、状态切换、视觉区分、无控制台错误四条验收线既有 Playwright 用例 可自动回归也有 reasoning-block.tsx 与 agent_server.py 的源码可逐行追溯是一套可复制到其他 Agent 框架集成中的推理呈现范式。相关对照文档可进一步参阅 reasoning-default-render.md 与 PARITY_NOTES.md。【免费下载链接】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），仅供参考