CopilotKit × AG2 共享状态流式输出（State Streaming）功能验证指南

CopilotKit × AG2 共享状态流式输出（State Streaming）功能验证指南

【免费下载链接】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 仓库中 AG2 集成示例（showcase/integrations/ag2）的State Streaming（共享状态流式输出）演示与验证。该演示的核心能力是：Agent 在调用工具时，工具参数会按 token 逐字符镜像写入共享 Agent 状态，前端文档面板随之逐字生长，而非等工具调用结束才一次性更新。读完本文，你将掌握该功能的验证清单、前后端协作原理（StateStreamingMiddleware中间件 +useAgent前端订阅）、以及仓库中已固化的端到端测试断言，可直接用于部署后的回归验证与二次开发参考。

一、验证前置条件

对shared-state-streaming演示进行 QA 前，需要确认两件事已经就绪：

• 演示服务已部署并可访问：即 AG2 集成 showcase 前端（Next.js 应用）已正常运行，演示页面路径为/demos/shared-state-streaming；
• Agent 后端健康：后端独立进程默认运行在8000端口，可通过/api/health探活。在 API 路由 中，GET /api/copilotkit会主动向AGENT_URL/health发起一次 3 秒超时的探测，并返回agent_url、agent_status与OPENAI_API_KEY是否设置等环境信息，可直接用作文档中"检查 /api/health"的落地方式。

二、验证步骤与测试条目

1. 基础功能（Basic Functionality）

• 打开shared-state-streaming演示页
• 确认聊天界面加载，标题为 "State Streaming"
• 确认输入框占位符 "Type a message..." 可见（实际实现中侧边栏占位符为 "Ask me to write something..."，见 demo-layout.tsx，以实机为准）
• 发送一条基础消息（例如 "Hello! What can you do?"）
• 确认 Agent 有响应

说明：仓库中的 e2e 测试使用了真实的侧边栏占位符文本，若按文档逐条执行时发现占位符文案与文档不一致，应以后端注册文案为准——这正是"验证文档需结合实现"的典型场景。

2. 功能特性检查（Feature-Specific Checks）

建议按钮（Suggestions）

• 确认 "Get started" 建议按钮可见

在 suggestions.ts 中，通过useConfigureSuggestions注册了三个建议按钮，available: "always"表示始终可用：

状态说明：Stub 演示（Note: Stub Demo）

原 QA 文档标注本演示为Stub（TODO: implement），仅需验证基本的 CopilotChat 加载与消息收发、无自定义 UI 组件。

当前仓库状态需要更正：该演示已经完成实现，并非 Stub。仓库中已存在完整的：

• 前端页面 page.tsx；
• 布局与侧边栏 demo-layout.tsx；
• 自定义文档面板组件 document-view.tsx；
• 建议配置 suggestions.ts；
• 演示说明 README.md；
• 端到端测试 shared-state-streaming.spec.ts。

因此执行此 QA 时，"无自定义 UI 组件"这一项不再成立——页面实际包含一个自定义的DocumentView实时文档面板，验证时应一并覆盖（详见下文"特征断言"）。

3. 错误处理（Error Handling）

• 发送空消息（应被优雅处理，不产生报错）
• 正常使用过程中控制台无报错

从实现看，DocumentView对空内容有专门的分支处理：当content.length === 0 && !isStreaming时渲染斜体占位文本 "Ask the agent to write something — its output will stream here token by token."，而不会渲染内容区域（见 document-view.tsx），这为空输入与初始状态提供了天然的容错。

三、预期结果（Expected Results）

• 聊天界面在3 秒内加载完成
• Agent 在10 秒内响应
• 无 UI 报错或布局损坏

这些时间预算在仓库 e2e 测试中以更细粒度体现：页面挂载断言 15 秒超时，流式内容出现断言 60 秒超时（见下文特征断言）。

四、核心原理：中间件如何实现逐 token 状态流

原文档指出"魔法在于一行中间件配置"：

StateStreamingMiddleware( StateItem( state_key="document", tool="write_document", tool_argument="content", ) )

• StateStreamingMiddleware与StateItem由ag_ui_langgraph包的middlewares/state_streaming模块提供，并通过 Python SDK 的init.py 统一导出，与CopilotKitMiddleware、LangGraphAGUIAgent等作为公开 API 提供给集成方；
• state_key="document"指定状态槽位，tool="write_document"指定目标工具，tool_argument="content"指定要镜像到状态的工具参数；
• 效果：不配置该中间件时，state.document只有在write_document工具调用结束后才会更新；配置后，LLM 为content参数生成的每一个 token 都会立即镜像写入状态，UI 因而可以实时重渲染。

从部署链路看，该演示的后端即 AG2 的ConversableAgent：在 API 路由 的sharedAgentNames列表中，shared-state-streaming与其他前端变体演示共用同一个默认 Agent（路径/），前端通过CopilotRuntime+HttpAgent按 AG-UI 协议把请求代理到独立进程（默认http://localhost:8000）的 Python 后端。

五、前端如何订阅并重渲染

前端演示页面 page.tsx 的关键代码：

const { agent } = useAgent({ agentId: "shared-state-streaming", updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], });

• OnStateChanged：状态变化订阅——每个流式 token 写入state.document都会触发重渲染，驱动文档面板逐字生长；
• OnRunStatusChanged：运行状态订阅——Agent 启动/停止时更新 "LIVE" 徽标与光标；
• agent.isRunning用于切换光标与徽标显隐。

DemoLayout将document文本与isStreaming标志传给DocumentView（demo-layout.tsx），同时渲染一个CopilotSidebar（defaultOpen={true}）作为聊天入口。

六、可复用的特征断言（来自 e2e 测试）

仓库已将上述 QA 条目固化为 Playwright 端到端测试 shared-state-streaming.spec.ts，其中定义的data-testid与断言可直接迁移为持续集成回归用例：

测试中的data-testid对应实现：document-view（面板容器）、document-char-count（字符计数器）、document-content（流式文本区域）、document-live-badge（运行中徽标），全部定义于 document-view.tsx。

七、验证与调试提示

• 环境变量：后端地址由AGENT_URL控制，默认http://localhost:8000；如需排查路由级问题，可设置SHOWCASE_ROUTE_DEBUG=1开启逐请求日志（默认关闭，因为在高频探活下会触发平台日志速率限制，见 route.ts）；
• 健康检查：GET /api/copilotkit同时返回agent_status（reachable / unreachable）与OPENAI_API_KEY是否设置，适合作为部署冒烟的第一站；
• 回归建议：shared-state-streaming同时被 docs-links.json 与 manifest.yaml 索引，说明它属于 showcase 的正式演示集合，建议将 e2e 断言纳入 CI 门禁，防止中间件配置或状态槽位改动造成回归。

结语

State Streaming 演示展示了 CopilotKit 共享状态机制与流式能力的结合：一条StateStreamingMiddleware配置 + 前端useAgent双订阅，即可把工具参数从"结束时更新"升级为"逐 token 实时镜像"。本文既给出了可直接执行的 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