CopilotKit × Agno 集成实战State Streaming——将工具参数逐 token 实时镜像进共享状态【免费下载链接】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/CopilotKitCopilotKit 的 State Streaming状态流式渲染解决的是 Agent 应用中最直观的体验问题当后端在执行write_document这类长耗时工具时前端不再傻等一个结束时的整体爆发而是能看着文档在 UI 里逐 token 生长出来。本文以仓库中 Agno 集成下的shared-state-streaming演示为对象结合其 QA 验证清单、演示源码、端到端测试与官方文档完整讲解该能力的前后端实现原理、交互验证步骤与排错要点。读完你可以独立复现这一实时文档面板模式并迁移到自己的 Agent 应用中。功能定位State Streaming 解决什么问题默认情况下Agent 的共享状态只在后端检查点checkpoint之间更新。这意味着一个正在执行的工具调用例如写一篇完整的文档起草一封邮件对前端来说最终表现为一次性的数据爆发——用户盯着 spinner 干等直到工具结束才看到全部输出。State Streaming 的做法是把某个工具参数的生成过程直接前向转发到共享状态键中LLM 每流式生成一个 tokenstate.document就立即变长一点订阅了该状态的useAgent组件随之逐 token 重渲染。官方文档在 docs/src/content/docs/shared-state/streaming.mdx 中给出的适用场景非常明确协作写作类 Agent持续产出文档内容研究类 Agent不断累积 findings 列表规划类 Agent逐步构建 step-by-step 计划。一句话概括没有流式用户看到的是 spinner有了流式用户看到答案 token 一个接一个地长出来。前置条件跑通演示与后端健康检查在开始功能验证之前QA 清单 showcase/integrations/agno/qa/shared-state-streaming.md 明确列出了两条前置条件演示应用已部署且可访问演示路由为/demos/shared-state-streaming该路由同时登记在 showcase/integrations/agno/manifest.yaml 的demos列表中路由与highlight源码路径均可查Agent 后端健康检查/api/health。关于后端健康检查仓库中提供了两级探针showcase/integrations/agno/src/app/api/health/route.ts基础健康端点showcase/integrations/agno/src/app/api/copilotkit/route.ts 中的GET处理器不仅返回自身状态还会主动探测AGENT_URL默认http://localhost:8000的/health把agent_status区分为reachable、unreachable、error并顺带报告OPENAI_API_KEY是否已配置。用它来判断前端就绪但 Agent 后端未起来这类问题非常直接。{ status: ok, agent_url: http://localhost:8000, agent_status: reachable, env: { OPENAI_API_KEY: set, NODE_ENV: development } }后端实现一条StateStreamingMiddleware声明搞定流式映射State Streaming 的魔法全部集中在一个中间件配置上。演示自带的 README showcase/integrations/agno/src/app/demos/shared-state-streaming/README.md 给出了完整写法StateStreamingMiddleware( StateItem( state_keydocument, toolwrite_document, tool_argumentcontent, ) )三个字段的含义分别是字段值作用state_keydocument写入的共享状态键必须已存在于 Agent 的状态 schema 中toolwrite_document要监听的工具名必须与 LLM 实际看到的工具调用完全一致tool_argumentcontent该工具的参数名LLM 流式生成该参数时逐 token 转发从 SDK 的导入路径可以看到该中间件的出处——sdk-python/copilotkit/init.py 从ag_ui_langgraph.middlewares.state_streaming重新导出StateStreamingMiddleware与StateItem并在__all__中对外公开说明它是 AG-UI Python 生态的标准中间件由 CopilotKit SDK 直接复用。中间件的核心行为结合官方文档 docs/src/content/docs/shared-state/streaming.mdx 的描述可以总结为三点当 LLM 正在流式生成content参数时每个部分值都会被立即写入document状态键——此时工具本身可能仍在执行中工具调用完成后其最终返回值会覆盖写入同一个键因此流式过程中的部分值最终会被权威的完整值取代两者不会冲突若无该中间件state.document只会在工具调用结束时更新一次。关于后端挂载的补充说明从源码结构看这个演示的 Agent 会话在 showcase/integrations/agno/src/app/api/copilotkit/route.ts 中把shared-state-streaming这一 agent 名映射到主 AgentHttpAgent指向AGENT_URL/agui即 showcase/integrations/agno/src/agents/main.py 中定义的mainAgent后端实际由 showcase/integrations/agno/src/agent_server.py 的 AG-UI 路由提供服务。也就是说演示界面通过/api/copilotkit单一运行时路由与 Agno 后端进行 AG-UI 协议通信而StateStreamingMiddleware负责其中的状态转发。另外注意 showcase/integrations/agno/manifest.yaml 的not_supported_features中目前仍列出shared-state-streaming这与仓库中已存在的完整演示实现与 E2E 测试存在出入——引用该能力时建议以实际源码与运行结果为准。前端实现useAgent订阅状态与运行状态前端的订阅逻辑非常精简全部在 showcase/integrations/agno/src/app/demos/shared-state-streaming/page.tsx 中完成use client; import { CopilotKit, useAgent, UseAgentUpdate } from copilotkit/react-core/v2; import { DemoLayout } from ./demo-layout; import { useSharedStateStreamingSuggestions } from ./suggestions; interface StreamingAgentState { document?: string; } export default function SharedStateStreamingDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentshared-state-streaming DemoContent / /CopilotKit ); } function DemoContent() { const { agent } useAgent({ agentId: shared-state-streaming, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); useSharedStateStreamingSuggestions(); const agentState agent.state as StreamingAgentState | undefined; const document agentState?.document ?? ; const isRunning agent.isRunning; return DemoLayout document{document} isStreaming{isRunning} /; }这段代码揭示了两个关键设计双更新订阅OnStateChanged驱动文档文本的逐 token 重渲染OnRunStatusChanged负责切换 LIVE 徽标的显示与隐藏agent.isRunning——官方文档 docs/src/content/docs/shared-state/streaming.mdx 明确建议用这两个更新的组合来实现运行中/已完成指示器状态即普通数据agent.state.document就是一个随每个 token 变长的字符串读取方式与普通 React state 无异。布局与实时文档面板showcase/integrations/agno/src/app/demos/shared-state-streaming/demo-layout.tsx 把DocumentView放在主视图右侧挂载CopilotSidebardefaultOpen{true}输入框占位文案为 Ask me to write something...。核心的展示组件是 showcase/integrations/agno/src/app/demos/shared-state-streaming/document-view.tsx它渲染了三个让逐 token 流式肉眼可见的元素LIVE 徽标data-testiddocument-live-badge仅当isStreaming为 true 时渲染红色胶囊样式带脉冲圆点字符计数器data-testiddocument-char-countcontent.length以N chars展示是最廉价但最直观的token 量感指示器文档内容区data-testiddocument-contentwhitespace-pre-wrap 等宽/衬线字体流式期间末尾附带闪烁光标空态时展示斜体占位文案 Ask the agent to write something — its output will stream here token by token.。建议指令showcase/integrations/agno/src/app/demos/shared-state-streaming/suggestions.ts 通过useConfigureSuggestions注册了三条常驻建议方便一键触发建议标题实际发送的消息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.功能验证步骤从 QA 清单到自动化 E2EQA 清单 showcase/integrations/agno/qa/shared-state-streaming.md 把验证过程拆为三部分基础功能、特性检查、错误处理。仓库中对应有一份完整的 Playwright 端到端测试 showcase/integrations/agno/tests/e2e/shared-state-streaming.spec.ts两者可以一一对应——QA 清单是人工视角的验收标准E2E 测试则把这些标准固化为可回归的断言。1. 基础功能验证QA 清单要求访问shared-state-streaming演示页聊天界面能加载发送一条基础消息示例 Hello! What can you do?确认 Agent 有响应。E2E 测试用更具体的断言覆盖了等价路径页面加载后document-view面板可见、侧栏聊天输入框占位 Ask me to write something...可见发送 Write a short poem about autumn leaves. 后copilot-assistant-message出现在侧栏中等待上限 60 秒。提示QA 清单中记录的标题为 State Streaming、占位文案为 Type a message...、建议按钮为 Get started而当前实现的实际值是 Document、Ask me to write something... 与上述三条建议。这说明 QA 清单相对当前实现略有滞后验收时以 showcase/integrations/agno/src/app/demos/shared-state-streaming 下的实际代码为准或直接复用 E2E 测试中的断言。2. 特性检查流式行为是否真的逐 token 可见这是 State Streaming 演示的核心验收点E2E 测试从三个维度验证内容逐渐出现发送消息后document-content在 60 秒内可见且文本长度超过 10 个字符防止空文档假阳性字符计数递增初始为0 chars流式期间数值大于 0LIVE 徽标发送前document-live-badge不可见Agent 运行期间变为可见。这三条断言恰好对应了DocumentView中内容 计数器 LIVE 徽标的三个视觉信号——任何一条不通过都意味着流式链路中间件 → 状态快照 →useAgent重渲染某处断裂。QA 清单在此节还标注了历史状态Status: Stub — This demo is currently a stub (TODO: implement)。从当前仓库源码结构看该演示已完成完整实现page.tsx、document-view.tsx、suggestions.ts及 E2E 测试齐备此标注应视为历史遗留说明验收时可忽略。3. 错误处理验证QA 清单要求两点发送空消息应被优雅处理不崩溃、不报错正常使用过程中无控制台错误。空消息处理由CopilotSidebar/ CopilotKit 运行时在输入层面拦截前端不提交空内容这部分逻辑在预置组件内部实现至于无控制台错误E2E 测试已通过所有断言在运行成功后隐式覆盖——若页面存在未捕获异常导致组件渲染失败上述定位器断言将直接超时失败。预期结果与验收基线QA 清单给出的验收基线同时也应是任何一次人工回归的最低标准检查项基线聊天界面加载3 秒内完成Agent 响应10 秒内返回UI 状态无报错、无布局破坏对应到 E2E 测试中页面加载相关断言的超时设置为 1015 秒首次渲染含面板挂载与字符计数流式相关断言放宽到 60 秒等待 LLM 生成完整文档。这里有两个值得注意的经验值E2E 的加载断言15 秒比 QA 人工基线3 秒宽松是因为 Playwright 在 CI 环境下需要容忍冷启动而 60 秒的流式超时则暗示文档生成本身耗时较长这正是 State Streaming 价值所在——越长的工具执行逐 token 反馈带来的体验收益越大。验证链路速查状态从后端走到 UI 的完整路径综合本文各部分state.document从 Agent 到 UI 的完整链路是后端StateStreamingMiddleware监听write_document工具的content参数LLM 每生成一个 token 就把部分值写入document状态键工具结束后以完整返回值覆盖传输Agno 后端的 AG-UI 路由showcase/integrations/agno/src/agent_server.py状态类演示使用自定义的 state-aware 处理器在每次 run 结束前发出StateSnapshotEvent将状态变化通过 AG-UI 事件流经 showcase/integrations/agno/src/app/api/copilotkit/route.ts 的CopilotRuntime转发到前端前端useAgent({ updates: [OnStateChanged, OnRunStatusChanged] })收到更新后触发重渲染agent.state.document与agent.isRunning驱动 document-view.tsx 逐 token 展示内容、字符数与 LIVE 徽标。该模式的通用化说明收录在 docs/src/content/docs/shared-state/streaming.mdx 与 docs/src/content/docs/generative-ui/state-rendering.mdx两者都内嵌了本演示作为InlineDemo如需将这一能力引入自己的项目可以此演示为参照模板。【免费下载链接】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 × Agno 集成实战：State Streaming——将工具参数逐 token 实时镜像进共享状态
CopilotKit × Agno 集成实战State Streaming——将工具参数逐 token 实时镜像进共享状态【免费下载链接】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/CopilotKitCopilotKit 的 State Streaming状态流式渲染解决的是 Agent 应用中最直观的体验问题当后端在执行write_document这类长耗时工具时前端不再傻等一个结束时的整体爆发而是能看着文档在 UI 里逐 token 生长出来。本文以仓库中 Agno 集成下的shared-state-streaming演示为对象结合其 QA 验证清单、演示源码、端到端测试与官方文档完整讲解该能力的前后端实现原理、交互验证步骤与排错要点。读完你可以独立复现这一实时文档面板模式并迁移到自己的 Agent 应用中。功能定位State Streaming 解决什么问题默认情况下Agent 的共享状态只在后端检查点checkpoint之间更新。这意味着一个正在执行的工具调用例如写一篇完整的文档起草一封邮件对前端来说最终表现为一次性的数据爆发——用户盯着 spinner 干等直到工具结束才看到全部输出。State Streaming 的做法是把某个工具参数的生成过程直接前向转发到共享状态键中LLM 每流式生成一个 tokenstate.document就立即变长一点订阅了该状态的useAgent组件随之逐 token 重渲染。官方文档在 docs/src/content/docs/shared-state/streaming.mdx 中给出的适用场景非常明确协作写作类 Agent持续产出文档内容研究类 Agent不断累积 findings 列表规划类 Agent逐步构建 step-by-step 计划。一句话概括没有流式用户看到的是 spinner有了流式用户看到答案 token 一个接一个地长出来。前置条件跑通演示与后端健康检查在开始功能验证之前QA 清单 showcase/integrations/agno/qa/shared-state-streaming.md 明确列出了两条前置条件演示应用已部署且可访问演示路由为/demos/shared-state-streaming该路由同时登记在 showcase/integrations/agno/manifest.yaml 的demos列表中路由与highlight源码路径均可查Agent 后端健康检查/api/health。关于后端健康检查仓库中提供了两级探针showcase/integrations/agno/src/app/api/health/route.ts基础健康端点showcase/integrations/agno/src/app/api/copilotkit/route.ts 中的GET处理器不仅返回自身状态还会主动探测AGENT_URL默认http://localhost:8000的/health把agent_status区分为reachable、unreachable、error并顺带报告OPENAI_API_KEY是否已配置。用它来判断前端就绪但 Agent 后端未起来这类问题非常直接。{ status: ok, agent_url: http://localhost:8000, agent_status: reachable, env: { OPENAI_API_KEY: set, NODE_ENV: development } }后端实现一条StateStreamingMiddleware声明搞定流式映射State Streaming 的魔法全部集中在一个中间件配置上。演示自带的 README showcase/integrations/agno/src/app/demos/shared-state-streaming/README.md 给出了完整写法StateStreamingMiddleware( StateItem( state_keydocument, toolwrite_document, tool_argumentcontent, ) )三个字段的含义分别是字段值作用state_keydocument写入的共享状态键必须已存在于 Agent 的状态 schema 中toolwrite_document要监听的工具名必须与 LLM 实际看到的工具调用完全一致tool_argumentcontent该工具的参数名LLM 流式生成该参数时逐 token 转发从 SDK 的导入路径可以看到该中间件的出处——sdk-python/copilotkit/init.py 从ag_ui_langgraph.middlewares.state_streaming重新导出StateStreamingMiddleware与StateItem并在__all__中对外公开说明它是 AG-UI Python 生态的标准中间件由 CopilotKit SDK 直接复用。中间件的核心行为结合官方文档 docs/src/content/docs/shared-state/streaming.mdx 的描述可以总结为三点当 LLM 正在流式生成content参数时每个部分值都会被立即写入document状态键——此时工具本身可能仍在执行中工具调用完成后其最终返回值会覆盖写入同一个键因此流式过程中的部分值最终会被权威的完整值取代两者不会冲突若无该中间件state.document只会在工具调用结束时更新一次。关于后端挂载的补充说明从源码结构看这个演示的 Agent 会话在 showcase/integrations/agno/src/app/api/copilotkit/route.ts 中把shared-state-streaming这一 agent 名映射到主 AgentHttpAgent指向AGENT_URL/agui即 showcase/integrations/agno/src/agents/main.py 中定义的mainAgent后端实际由 showcase/integrations/agno/src/agent_server.py 的 AG-UI 路由提供服务。也就是说演示界面通过/api/copilotkit单一运行时路由与 Agno 后端进行 AG-UI 协议通信而StateStreamingMiddleware负责其中的状态转发。另外注意 showcase/integrations/agno/manifest.yaml 的not_supported_features中目前仍列出shared-state-streaming这与仓库中已存在的完整演示实现与 E2E 测试存在出入——引用该能力时建议以实际源码与运行结果为准。前端实现useAgent订阅状态与运行状态前端的订阅逻辑非常精简全部在 showcase/integrations/agno/src/app/demos/shared-state-streaming/page.tsx 中完成use client; import { CopilotKit, useAgent, UseAgentUpdate } from copilotkit/react-core/v2; import { DemoLayout } from ./demo-layout; import { useSharedStateStreamingSuggestions } from ./suggestions; interface StreamingAgentState { document?: string; } export default function SharedStateStreamingDemo() { return ( CopilotKit runtimeUrl/api/copilotkit agentshared-state-streaming DemoContent / /CopilotKit ); } function DemoContent() { const { agent } useAgent({ agentId: shared-state-streaming, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); useSharedStateStreamingSuggestions(); const agentState agent.state as StreamingAgentState | undefined; const document agentState?.document ?? ; const isRunning agent.isRunning; return DemoLayout document{document} isStreaming{isRunning} /; }这段代码揭示了两个关键设计双更新订阅OnStateChanged驱动文档文本的逐 token 重渲染OnRunStatusChanged负责切换 LIVE 徽标的显示与隐藏agent.isRunning——官方文档 docs/src/content/docs/shared-state/streaming.mdx 明确建议用这两个更新的组合来实现运行中/已完成指示器状态即普通数据agent.state.document就是一个随每个 token 变长的字符串读取方式与普通 React state 无异。布局与实时文档面板showcase/integrations/agno/src/app/demos/shared-state-streaming/demo-layout.tsx 把DocumentView放在主视图右侧挂载CopilotSidebardefaultOpen{true}输入框占位文案为 Ask me to write something...。核心的展示组件是 showcase/integrations/agno/src/app/demos/shared-state-streaming/document-view.tsx它渲染了三个让逐 token 流式肉眼可见的元素LIVE 徽标data-testiddocument-live-badge仅当isStreaming为 true 时渲染红色胶囊样式带脉冲圆点字符计数器data-testiddocument-char-countcontent.length以N chars展示是最廉价但最直观的token 量感指示器文档内容区data-testiddocument-contentwhitespace-pre-wrap 等宽/衬线字体流式期间末尾附带闪烁光标空态时展示斜体占位文案 Ask the agent to write something — its output will stream here token by token.。建议指令showcase/integrations/agno/src/app/demos/shared-state-streaming/suggestions.ts 通过useConfigureSuggestions注册了三条常驻建议方便一键触发建议标题实际发送的消息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.功能验证步骤从 QA 清单到自动化 E2EQA 清单 showcase/integrations/agno/qa/shared-state-streaming.md 把验证过程拆为三部分基础功能、特性检查、错误处理。仓库中对应有一份完整的 Playwright 端到端测试 showcase/integrations/agno/tests/e2e/shared-state-streaming.spec.ts两者可以一一对应——QA 清单是人工视角的验收标准E2E 测试则把这些标准固化为可回归的断言。1. 基础功能验证QA 清单要求访问shared-state-streaming演示页聊天界面能加载发送一条基础消息示例 Hello! What can you do?确认 Agent 有响应。E2E 测试用更具体的断言覆盖了等价路径页面加载后document-view面板可见、侧栏聊天输入框占位 Ask me to write something...可见发送 Write a short poem about autumn leaves. 后copilot-assistant-message出现在侧栏中等待上限 60 秒。提示QA 清单中记录的标题为 State Streaming、占位文案为 Type a message...、建议按钮为 Get started而当前实现的实际值是 Document、Ask me to write something... 与上述三条建议。这说明 QA 清单相对当前实现略有滞后验收时以 showcase/integrations/agno/src/app/demos/shared-state-streaming 下的实际代码为准或直接复用 E2E 测试中的断言。2. 特性检查流式行为是否真的逐 token 可见这是 State Streaming 演示的核心验收点E2E 测试从三个维度验证内容逐渐出现发送消息后document-content在 60 秒内可见且文本长度超过 10 个字符防止空文档假阳性字符计数递增初始为0 chars流式期间数值大于 0LIVE 徽标发送前document-live-badge不可见Agent 运行期间变为可见。这三条断言恰好对应了DocumentView中内容 计数器 LIVE 徽标的三个视觉信号——任何一条不通过都意味着流式链路中间件 → 状态快照 →useAgent重渲染某处断裂。QA 清单在此节还标注了历史状态Status: Stub — This demo is currently a stub (TODO: implement)。从当前仓库源码结构看该演示已完成完整实现page.tsx、document-view.tsx、suggestions.ts及 E2E 测试齐备此标注应视为历史遗留说明验收时可忽略。3. 错误处理验证QA 清单要求两点发送空消息应被优雅处理不崩溃、不报错正常使用过程中无控制台错误。空消息处理由CopilotSidebar/ CopilotKit 运行时在输入层面拦截前端不提交空内容这部分逻辑在预置组件内部实现至于无控制台错误E2E 测试已通过所有断言在运行成功后隐式覆盖——若页面存在未捕获异常导致组件渲染失败上述定位器断言将直接超时失败。预期结果与验收基线QA 清单给出的验收基线同时也应是任何一次人工回归的最低标准检查项基线聊天界面加载3 秒内完成Agent 响应10 秒内返回UI 状态无报错、无布局破坏对应到 E2E 测试中页面加载相关断言的超时设置为 1015 秒首次渲染含面板挂载与字符计数流式相关断言放宽到 60 秒等待 LLM 生成完整文档。这里有两个值得注意的经验值E2E 的加载断言15 秒比 QA 人工基线3 秒宽松是因为 Playwright 在 CI 环境下需要容忍冷启动而 60 秒的流式超时则暗示文档生成本身耗时较长这正是 State Streaming 价值所在——越长的工具执行逐 token 反馈带来的体验收益越大。验证链路速查状态从后端走到 UI 的完整路径综合本文各部分state.document从 Agent 到 UI 的完整链路是后端StateStreamingMiddleware监听write_document工具的content参数LLM 每生成一个 token 就把部分值写入document状态键工具结束后以完整返回值覆盖传输Agno 后端的 AG-UI 路由showcase/integrations/agno/src/agent_server.py状态类演示使用自定义的 state-aware 处理器在每次 run 结束前发出StateSnapshotEvent将状态变化通过 AG-UI 事件流经 showcase/integrations/agno/src/app/api/copilotkit/route.ts 的CopilotRuntime转发到前端前端useAgent({ updates: [OnStateChanged, OnRunStatusChanged] })收到更新后触发重渲染agent.state.document与agent.isRunning驱动 document-view.tsx 逐 token 展示内容、字符数与 LIVE 徽标。该模式的通用化说明收录在 docs/src/content/docs/shared-state/streaming.mdx 与 docs/src/content/docs/generative-ui/state-rendering.mdx两者都内嵌了本演示作为InlineDemo如需将这一能力引入自己的项目可以此演示为参照模板。【免费下载链接】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），仅供参考