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-streamingAgent 后端健康后端独立进程默认运行在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表示始终可用建议标题对应消息Write a short poemWrite a short poem about autumn leaves.Draft an emailDraft a polite email declining a meeting next Tuesday afternoon.Explain quantum computingWrite a 2-paragraph explanation of quantum computing for a curious teenager.状态说明Stub 演示Note: Stub Demo原 QA 文档标注本演示为StubTODO: 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_keydocument, toolwrite_document, tool_argumentcontent, ) )StateStreamingMiddleware与StateItem由ag_ui_langgraph包的middlewares/state_streaming模块提供并通过 Python SDK 的init.py 统一导出与CopilotKitMiddleware、LangGraphAGUIAgent等作为公开 API 提供给集成方state_keydocument指定状态槽位toolwrite_document指定目标工具tool_argumentcontent指定要镜像到状态的工具参数效果不配置该中间件时state.document只有在write_document工具调用结束后才会更新配置后LLM 为content参数生成的每一个 token 都会立即镜像写入状态UI 因而可以实时重渲染。从部署链路看该演示的后端即 AG2 的ConversableAgent在 API 路由 的sharedAgentNames列表中shared-state-streaming与其他前端变体演示共用同一个默认 Agent路径/前端通过CopilotRuntimeHttpAgent按 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标志传给DocumentViewdemo-layout.tsx同时渲染一个CopilotSidebardefaultOpen{true}作为聊天入口。六、可复用的特征断言来自 e2e 测试仓库已将上述 QA 条目固化为 Playwright 端到端测试 shared-state-streaming.spec.ts其中定义的data-testid与断言可直接迁移为持续集成回归用例测试用例关键断言超时页面加载document-view可见、Document 标题可见、字符数 0 chars、侧边栏输入框可见15s / 10s空状态占位文本 Ask the agent to write something 可见document-content不应存在15s / 10s建议按钮Write a short poem、Draft an email、Explain quantum computing 三个按钮可见15s消息触发流式发送 Write a short poem about autumn leaves. 后document-content出现且文本长度 1060s字符数递增发送消息后字符数 060sLIVE 徽标发送前document-live-badge不可见发送后可见60s助手回复侧边栏出现copilot-assistant-message消息60s测试中的data-testid对应实现document-view面板容器、document-char-count字符计数器、document-content流式文本区域、document-live-badge运行中徽标全部定义于 document-view.tsx。七、验证与调试提示环境变量后端地址由AGENT_URL控制默认http://localhost:8000如需排查路由级问题可设置SHOWCASE_ROUTE_DEBUG1开启逐请求日志默认关闭因为在高频探活下会触发平台日志速率限制见 route.ts健康检查GET /api/copilotkit同时返回agent_statusreachable / 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考