CopilotKit AG2 集成中的默认推理渲染零配置展示 Agent 思考过程的完整指南【免费下载链接】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导读在 AG2原 AutoGen后端接入 CopilotKit 的聊天界面时Agent 的思考过程reasoning默认会通过内置的CopilotChatReasoningMessage组件渲染为一条位于最终答案上方的可折叠推理卡片无需编写任何自定义插槽。本文以仓库内 QA 清单 reasoning-default-render.md 为骨架结合reasoning-default演示页、内置组件源码与reasoning_agent.py后端实现完整讲解默认推理渲染的验证路径、零配置接入方式、底层 AG-UI 事件协议以及当前 AG2 适配中的已知限制帮助你在自己的集成中快速复现并排查该能力。一、QA 场景速览默认推理渲染要验证什么仓库中的 QA 文档 reasoning-default-render.md 定义了这一功能的验收清单核心是一个零自定义插槽场景步骤操作期望结果1导航到/demos/reasoning-default-render页面正常加载内置CopilotChat2发送Think step-by-step: what is 17 * 23?Agent 开始推理并流式输出3验证在最终答案上方出现一条推理卡片默认CopilotChatReasoningMessage推理内容与答案分离展示4验证卡片可折叠点击头部可展开 / 收起推理内容预期无需自定义reasoningMessage插槽内置推理 UI 即可渲染零配置开箱即用这份清单的核心断言是默认渲染模式下前端不注入任何自定义插槽CopilotKit 的内置推理卡片依然能够完整呈现 Agent 的思考过程。这与同仓库的reasoning-custom演示形成对照——后者通过覆盖messageView.reasoningMessage插槽实现了自定义琥珀色 ReasoningBlock而默认版则什么都不做。二、零配置接入两行核心代码即可点亮推理卡片实际的演示实现位于 reasoning-default/page.tsx。整个前端零配置体现在两处在CopilotKit上通过agent属性指定 AG2 后端代理 ID直接渲染CopilotChat不传messageView或任何 slot 覆盖。// showcase/integrations/ag2/src/app/demos/reasoning-default/page.tsx use client; import { CopilotKit, CopilotChat } from copilotkit/react-core/v2; import { useReasoningDefaultSuggestions } from ./suggestions; const AGENT_ID reasoning-default; export default function ReasoningDefaultDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agent{AGENT_ID} div classNameflex justify-center items-center h-screen w-full div classNameh-full w-full max-w-4xl Chat / /div /div /CopilotKit ); } function Chat() { useReasoningDefaultSuggestions(); return CopilotChat agentId{AGENT_ID} classNameh-full rounded-2xl /; }从源码结构看这里的关键约定是只要不覆盖reasoningMessage插槽CopilotChatMessageView在遇到 AG-UIREASONING_MESSAGE_*事件时就会自动回退到内置的CopilotChatReasoningMessage组件。也就是说是否使用默认渲染完全取决于你是否传入自定义 slot——后端与 runtime 无需为默认版做任何额外配置。QA 文档建议的测试提问Think step-by-step: what is 17 * 23?也印证了 suggestions.ts 中的设计注释OpenAI 系推理模型只有在遇到真正需要思考的问题时才会发射推理摘要事件response.reasoning_summary_text.delta像show your reasoning这类元提示反而不会触发推理通道推理卡片自然不会点亮。因此验证时务必使用具体的、有计算量的问题如 17×23、天空为何蓝色等。三、内置卡片组件解剖CopilotChatReasoningMessage的行为细节默认推理卡片的实现位于 packages/react-core/src/v2/components/chat/CopilotChatReasoningMessage.tsx它对外暴露三个可单独覆盖的子插槽Header、Content、Toggle未覆盖时使用内置默认实现。理解其源码能帮你准确判断 QA 步骤 3、4 的验收行为。1. 头部标签随流式状态切换对应出现在答案上方组件通过isStreaming isRunning isLatest判断当前推理消息是否正在流式输出并据此切换头部文案流式中Thinking…且右侧出现一个animate-pulse的脉冲圆点提示仍在思考流式结束Thought for {duration}时长由formatDuration格式化为人类可读文本——不足 1 秒显示a few seconds超过 1 分钟显示1m 5s形式。2. 可折叠与自动展开 / 自动收起对应 QA 步骤 4折叠状态由isOpen控制其行为策略值得注意流式开始时自动展开setIsOpen(true)让用户实时看到思考过程流式结束时自动收起仅保留一行Thought for Xs头部保持对话区整洁若用户手动点击过头部userToggledRef会记录其意图之后的自动收起不会覆盖用户的手动选择源码注释明确这是为了避免 CI 上异步时序导致的 flaky 测试头部仅在hasContent消息内容非空时才可点击展开否则为cursor-default且不渲染箭头展开箭头ChevronRight在展开时旋转 90°Toggle子插槽用grid-template-rows: 1fr/0fr过渡实现平滑的展开收起动画。3. 内容区使用 Streamdown 流式渲染内容区域通过Streamdown组件渲染message.content这意味着推理过程中的 markdown 片段如分步列表可以边流边渲染流式且已有内容时末尾会追加一个animate-pulse-cursor光标点模拟打字状态当既无内容又不在流式时内容区完全不渲染return null。组件同样遵循 CopilotKit 的 slots 约定WithSlots/renderSlot如果你未来想部分定制例如只改头部样式而保留内容渲染可以直接传入header、contentView或toggle中的任意一个其余回退到默认实现——这正是默认渲染与自定义渲染共存的插槽机制。四、后端如何产生推理事件reasoning_agent.py的自定义路由默认渲染的前提是后端能把推理内容翻译成 AG-UI 协议事件。在 AG2 集成中这一步由 reasoning_agent.py 完成其文件头注释完整说明了动机与设计为什么不用 AG2 自带的AGUIStreamAG2 的AGUIStream来自autogen.ag_ui只会把模型的文本作为TEXT_MESSAGE_CONTENT流式输出不会发射任何REASONING_MESSAGE_*事件。更根本的问题是ConversableAgent只消费 OpenAI chat-completions 流中的delta.content与delta.tool_calls会直接丢弃delta.reasoning_content这个携带推理内容的旁路通道。因此任何依赖该通道的 reasoning 槽位在 stock 适配器下永远无法点亮。自定义/reasoning子应用的四步处理流程该模块构建了一个独立的 FastAPI 子应用并挂载到/reasoning由 agent_server.py 中的路由映射支撑前端route.ts中的reasoningAgentNames统一代理到该路径直接以流式方式调用 OpenAI 兼容的 chat-completions 端点带上系统提示词与完整历史对话保证追问上下文保持与 agno 参考实现的对齐单次 LLM 调用避免多轮 CoT 循环从而兼容 aimock 录制回放。缓冲完整的上游响应同时累积delta.reasoning_content原生推理通道与delta.content最终答案不做增量转发。兜底策略当上游没有原生推理通道时从文本中解析reasoning.../reasoning标签作为推理内容与 agno 的 fallback 路径保持一致。最后把每个通道各作为一次完整增量发出先REASONING_MESSAGE_START / REASONING_MESSAGE_CONTENT / REASONING_MESSAGE_END输出推理部分再以TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END输出答案。注意事件必须使用角色为reasoning的REASONING_MESSAGE_*事件——源码注释明确指出如果误用THINKING_*事件会被ag-ui/client静默丢弃推理卡片将永不出现。这正是 QA 步骤 3推理卡片出现在最终答案上方在协议层的依据推理与答案是两个独立的 AG-UI 消息通道前端按事件到达顺序依次渲染。五、前端路由与 Agent 注册legacy 别名的由来在 showcase/integrations/ag2/src/app/api/copilotkit/route.ts 中可以看到完整的推理代理 ID 集合const reasoningAgentNames [ reasoning-default, reasoning-custom, reasoning-default-render, agentic-chat-reasoning, // ... ]; for (const name of reasoningAgentNames) { agents[name] createAgent(/reasoning/); }也就是说reasoning-default-render与agentic-chat-reasoning是为兼容旧页面保留的 legacy 别名它们与reasoning-default、reasoning-custom共享同一个/reasoning/推理后端演示页实际使用的 ID 是reasoning-default。QA 文档中写入/demos/reasoning-default-render在仓库当前的 manifest.yaml 中对应的正式 demo 条目为reasoning-defaultroute/demos/reasoning-default。实测时两者都指向同一后端与同一内置渲染组件验收行为一致。六、当前适配状态与已知限制务必如实告知读者默认推理渲染在协议层与前端渲染层是完整可用的但仓库明确标注了 AG2 生态侧的适配现状。在 manifest.yaml 的not_supported_features区块中not_supported_features: - shared-state-streaming - gen-ui-interrupt - interrupt-headless # AG2s ConversableAgent/AGUIStream does not emit AG-UI REASONING_MESSAGE_* # events ... the reasoning-block can never mount, so any reasoning-bearing # pill is upstream-incapable until autogen maps reasoning deltas to AG-UI events. - reasoning-default-render - agentic-chat-reasoning - tool-rendering-reasoning-chain注释明确了两点事实AG2 的ConversableAgent/AGUIStream目前不发射 AG-UIREASONING_MESSAGE_*事件除非上游 autogen 将 reasoning delta 映射为 AG-UI 事件否则任何承载推理内容的槽位都无法挂载reasoning-default-render、agentic-chat-reasoning两个 demo 在磁盘上仍保留接线即本文所述的默认渲染路径完整存在但在当前 AG2 适配版本下无法真正流式输出推理文本tool-rendering-reasoning-chain的工具循环可用但其 reasoning 槽位同样受此限制。因此对读者的准确表述是默认推理渲染的渲染层内置卡片、折叠交互、Thinking…/Thought for 标签在任何接入 AG-UI 推理事件的后端上都开箱即用但在 AG2 的 stock 适配器下产生推理事件依赖 reasoning_agent.py 这类自定义路由的旁路通道且整体能力以 autogen 上游对 reasoning delta 的原生支持为前提。若你的 AG2 版本已原生发射推理事件可直接走零配置路径验证若仍沿用 stockAGUIStream请参考本仓库自定义路由的做法或直接对比 agno 集成的 reasoning_agent.py 的对应实现本仓库注释明确二者互为镜像。七、端到端验证清单与常见排查点将 QA 文档的验收步骤扩展为可落地的排查清单路由与 Agent 注册确认 runtimeroute.ts中代理 ID 已注册reasoning-default或 legacyreasoning-default-render且指向/reasoning/后端/demos/reasoning-default-render与/demos/reasoning-default共用同一后端与渲染组件。提问必须是真问题参考 suggestions.ts使用Explain step by step why the sky appears blue during the day but red at sunset.这类需要分步推理的提问元提示式提问不会触发推理通道。流式过程中头部显示Thinking…与脉冲圆点卡片自动展开推理内容经 Streamdown 边流边渲染。流式结束后头部切换为Thought for Xs卡片自动收起为单行点击头部可再次展开aria-expanded同步更新手动展开/收起后自动收起不会覆盖用户意图。协议排查若卡片始终不出现抓包确认后端发射的是REASONING_MESSAGE_*角色reasoning而非THINKING_*——后者会被ag-ui/client静默丢弃同时确认推理通道内容非空hasContent为 false 时头部不可展开。对照实验将reasoning-default与reasoning-custom两个演示并列对比可直观确认是否覆盖messageView.reasoningMessage插槽是默认渲染与自定义渲染的唯一差异。八、总结默认推理渲染是 CopilotKit 前端栈中零配置开箱即用能力的典型代表前端只要不覆盖reasoningMessage插槽CopilotChatReasoningMessage就会自动承担推理卡片的渲染与折叠交互后端只要按 AG-UI 协议发射REASONING_MESSAGE_*事件推理内容就能与最终答案分离呈现。本文依据 reasoning-default-render.md 的 QA 骨架结合 默认渲染演示页、内置组件源码、推理后端路由 与 适配清单 manifest.yaml从验证路径、组件行为、协议原理到生态限制做了完整拆解。在将推理能力接入你的 AG2 集成时请以本文第七节清单逐项验证并始终关注 autogen 上游对 reasoning delta 的原生支持进展以决定是继续使用自定义/reasoning路由还是切换回官方流式适配。【免费下载链接】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），仅供参考