CopilotKit Built-in Agent 状态流式同步实战从 StateStreamingMiddleware 到令牌级文档渲染【免费下载链接】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 仓库中 Built-in AgentTanStack AI集成的shared-state-streamingState Streaming示例为对象完整讲解Agent 在工具调用尚未结束时就把工具参数的增量逐 token 同步到共享状态驱动前端面板实时渲染这一核心能力的验证方法、前端订阅方式与后端事件转换原理。读完本文你将掌握一条可复用的 Agent 状态流式同步链路LLM 生成write_document工具参数 → 状态增量工具发出 JSON Patch → AG-UISTATE_DELTA事件 → 前端useAgent订阅重渲染并了解如何用 QA 检查清单与 Playwright 端到端测试对其进行逐项验证。一、这个 Demo 解决什么问题在常规的 Agent 应用中共享状态的更新往往滞后于 LLM 的输出模型先写完整个工具参数工具执行完毕后才一次性写入状态前端面板随即跳变到最终结果。shared-state-streaming演示的则是另一种体验——每生成一个 token状态就更新一次文档在用户眼前逐字符生长。Demo 的页面布局是一左一右两个区域左侧文档面板只读渲染共享状态中的state.document字段带闪烁光标、LIVE 徽标与实时字符计数见 document-view.tsx右侧聊天栏基于CopilotSidebar的对话输入见 demo-layout.tsx。Demo 的定位说明与交互建议记录在 shared-state-streaming/README.md其核心卖点是Token 级增量——Agent 的write_document工具参数中每一个流式 token 都被直接转发进document状态键外加一个让流式过程肉眼可见的字符计数器。对应 QA 验证文档为 qa/shared-state-streaming.md它是本文的主体骨架。二、前置条件与运行方式根据 QA 文档 的 Prerequisites 一节运行该 Demo 需要三步配置 API Key在built-in-agent/包目录下的.env.local或环境变量中设置OPENAI_API_KEY安装依赖并启动在built-in-agent/包目录执行npm install --legacy-peer-deps npm run dev--legacy-peer-deps用于规避 peer 依赖冲突仓库采用 pnpm workspace 组织但该示例单独给出 npm 安装路径说明它可脱离 monorepo 独立运行访问 Demo 页面浏览器打开http://localhost:3000/demos/shared-state-streaming。该路由注册在 src/app/api/copilotkit/route.tsCopilotRuntime中显式注册了名为shared-state-streaming的 Agent通过createBuiltInAgent()工厂创建并使用InMemoryAgentRunner在进程内运行前端通过runtimeUrl/api/copilotkit与agentshared-state-streaming建立连接。三、页面加载基线检查QA 文档要求先做三项页面加载基线验证用于确认环境就绪、UI 骨架完整左侧列可见页面标题State Streaming左侧面板内显示斜体占位提示The agent will fill this panel as it streams updates.位于带边框的pre块中右侧列可见聊天输入框。对照源码这些检查点与 document-view.tsx 的实现一一对应面板头部标题为Document而页面级标题 State Streaming 由 Demo 页面框架渲染空状态时content.length 0 !isStreaming渲染斜体占位文案Ask the agent to write something — its output will stream here token by token.聊天输入由 demo-layout.tsx 中的CopilotSidebar提供其chatInputPlaceholder被配置为Ask me to write something...。值得一提的是组件中每个关键 UI 元素都带有data-testid如document-view、document-char-count、document-live-badge、document-content这是为端到端测试预留的稳定选择器详见后文第五节。四、快乐路径令牌级流式渲染的验证与原理4.1 QA 验证步骤QA 文档定义的主流程Happy path如下发送指令Write a short essay about small habits, and stream the document to state as you go.验证文本在Agent 仍在响应的过程中就逐步出现在左侧面板而不是等全部完成才一次性显示该行为要求 Agent 在每个 chunk上调用AGUISendStateDelta携带形如{ op: replace, path: /document, value: partial text }的增量负载Agent 结束后验证左侧面板展示完整文章全文。4.2 后端增量工具的定义AGUISendStateDelta是内置 Agent 暴露给 LLM 的状态工具之一定义在 src/lib/factory/state-tools.tsAGUISendStateSnapshot以完整快照替换整个应用状态入参为snapshotAGUISendStateDelta使用JSON Patch 操作数组对状态做增量更新。其 schema 限定op取值枚举[add, replace, remove]并允许path指向任意 JSON 指针路径如/document以及可选的value。这正是 QA 文档中{ op: replace, path: /document, value: partial text }的来源——每次工具调用参数delta数组里携带一个用当前位置的部分文本来替换/document的补丁多个 chunk 的replace连续叠加就形成了文档逐 token 生长的效果。4.3 事件转换链路从 TanStack 流到 AG-UI STATE_DELTA内置 Agent 运行在 TanStack AI 的chat()多轮循环之上而前端消费的是 AG-UI 协议事件。两者之间的桥梁是 src/lib/factory/tanstack-factory.ts 中的流转换器其关键处理逻辑见 L110-L190TOOL_CALL_START登记toolCallId → toolName发出TOOL_CALL_START事件TOOL_CALL_ARGS每个 chunk 的delta都被追加累积进toolArgsById对应 QA 文档所说的每个 chunk 调用一次 AGUISendStateDelta并透传TOOL_CALL_ARGS事件TOOL_CALL_RESULT当检测到工具名为AGUISendStateDelta且结果对象含delta字段时将delta数组包装为 AG-UI 的STATE_DELTA事件L180-L190同理AGUISendStateSnapshot的结果被转换为STATE_SNAPSHOT事件。从源码结构可以推断TOOL_CALL_ARGS阶段的逐 chunk 透传 结果阶段的STATE_DELTA聚合就是工具调用在途即可更新状态的底层实现机制——前端无需等待工具结束就能持续收到状态增量。4.4 前端订阅useAgent 的双通道更新前端页面 src/app/demos/shared-state-streaming/page.tsx 通过useAgent同时订阅两类更新const { agent } useAgent({ agentId: shared-state-streaming, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], });OnStateChanged驱动每次状态变化即每个增量 token 到达时的文档重渲染OnRunStatusChanged驱动LIVE 徽标的出现与消失。随后页面从agent.state读取document字段并以agent.isRunning控制光标与徽标传给DocumentView。DocumentView在流式期间同时展示三个视觉证据红色 LIVE 徽标、跳动的光标块、实时增长的chars字符计数见 document-view.tsx三者共同让逐 token 流式这一行为变得直观可验证。4.5 参考实现的中间件形态Demo 的 README.md 指出这一行为的魔法在参考后端LangGraph Python 等中体现为一行中间件配置StateStreamingMiddleware( StateItem( state_keydocument, toolwrite_document, tool_argumentcontent, ) )其语义是将write_document工具参数content的每个流式 token 即时镜像进document状态键没有它state.document只能在工具调用结束后一次性更新。需要说明的是该中间件属于 Python 侧参考实现Built-in AgentTanStack AI运行时没有 Python 中间件而是通过AGUISendStateDelta工具 TanStack→AG-UI 事件转换器实现等价行为对应 state-tools.ts 与 tanstack-factory.ts。理解两者对应关系有助于在不同后端之间迁移同样的流式状态同步能力。五、边界情况非流式消息与二次请求QA 文档要求额外验证两个边界场景它们分别检验状态不被无关对话污染与新文档替换旧文档而非追加场景一非流式消息不触碰状态。发送不请求文档流式的消息如What time is it?验证 Agent 在聊天栏正常回复而左侧文档面板保持不变。其原理是document状态只在AGUISendStateDelta携带/document路径补丁时才会被修改普通文本回复只产生TEXT_MESSAGE_CHUNK事件tanstack-factory.ts不产生状态增量。场景二第二次流式请求替换旧内容。再发一次流式请求验证左侧面板被新文档整体替换而不是追加到旧文档之后。这与 QA 文档与状态工具都采用的op: replace语义直接相关每一次流式都以replace /document覆盖该路径天然满足整体替换预期若改用add或append语义则会破坏此行为。六、E2E 测试佐证与自动化回归上述 QA 检查点并非只能人工执行——仓库提供了完整的 Playwright 端到端测试 tests/e2e/shared-state-streaming.spec.ts将其固化为自动化回归用例测试用例对应验证点page loads with document panel and chat sidebar文档面板、标题、0 chars初始计数与聊天输入框就位empty state shows placeholder text空状态下斜体占位文案可见document-content不出现starter suggestions render in the sidebar三个建议按钮诗、邮件、量子计算渲染正常sending a message triggers document streaming发送消息后文档内容出现且长度超过 10 字符character count updates as document streams字符计数从 0 增长证明增量到达live badge appears while agent is streaming流式期间 LIVE 徽标可见、空闲时不可见assistant responds in the sidebar chat聊天栏出现助手回复这些用例在beforeEach中统一访问/demos/shared-state-streaming路由与 QA 文档的验证路径保持一致。其中字符计数增长与LIVE 徽标出现两条正是快乐路径增量流式的可量化断言可作为人工 QA 的自动化替代。七、交互建议与实操提示为快速触发流式效果Demo 提供了三个内置建议见 suggestions.ts点击即可发送Write a short poem about autumn leaves.Draft a polite email declining a meeting next Tuesday afternoon.Write a 2-paragraph explanation of quantum computing for a curious teenager.这些建议通过useConfigureSuggestions({ suggestions, available: always })注入available: always表示任何对话阶段都可用。总结shared-state-streaming演示并验证了 CopilotKit 生态中一项关键能力共享 Agent 状态可以在工具调用尚未完成时逐 token 流式更新。从 QA 视角看验证要点集中在三处——页面加载基线、快乐路径的增量渲染、以及非流式消息与二次请求两个边界从实现视角看它由状态工具AGUISendStateDelta的 JSON Patch 增量、事件转换器TanStack 流 → AG-UISTATE_DELTA与前端useAgent双通道订阅三部分协作完成并有完整的 Playwright 测试作为自动化保障。掌握这条链路即可在自己的 CopilotKit 应用中复现文档/画布/表单随 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CopilotKit Built-in Agent 状态流式同步实战：从 StateStreamingMiddleware 到令牌级文档渲染
CopilotKit Built-in Agent 状态流式同步实战从 StateStreamingMiddleware 到令牌级文档渲染【免费下载链接】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 仓库中 Built-in AgentTanStack AI集成的shared-state-streamingState Streaming示例为对象完整讲解Agent 在工具调用尚未结束时就把工具参数的增量逐 token 同步到共享状态驱动前端面板实时渲染这一核心能力的验证方法、前端订阅方式与后端事件转换原理。读完本文你将掌握一条可复用的 Agent 状态流式同步链路LLM 生成write_document工具参数 → 状态增量工具发出 JSON Patch → AG-UISTATE_DELTA事件 → 前端useAgent订阅重渲染并了解如何用 QA 检查清单与 Playwright 端到端测试对其进行逐项验证。一、这个 Demo 解决什么问题在常规的 Agent 应用中共享状态的更新往往滞后于 LLM 的输出模型先写完整个工具参数工具执行完毕后才一次性写入状态前端面板随即跳变到最终结果。shared-state-streaming演示的则是另一种体验——每生成一个 token状态就更新一次文档在用户眼前逐字符生长。Demo 的页面布局是一左一右两个区域左侧文档面板只读渲染共享状态中的state.document字段带闪烁光标、LIVE 徽标与实时字符计数见 document-view.tsx右侧聊天栏基于CopilotSidebar的对话输入见 demo-layout.tsx。Demo 的定位说明与交互建议记录在 shared-state-streaming/README.md其核心卖点是Token 级增量——Agent 的write_document工具参数中每一个流式 token 都被直接转发进document状态键外加一个让流式过程肉眼可见的字符计数器。对应 QA 验证文档为 qa/shared-state-streaming.md它是本文的主体骨架。二、前置条件与运行方式根据 QA 文档 的 Prerequisites 一节运行该 Demo 需要三步配置 API Key在built-in-agent/包目录下的.env.local或环境变量中设置OPENAI_API_KEY安装依赖并启动在built-in-agent/包目录执行npm install --legacy-peer-deps npm run dev--legacy-peer-deps用于规避 peer 依赖冲突仓库采用 pnpm workspace 组织但该示例单独给出 npm 安装路径说明它可脱离 monorepo 独立运行访问 Demo 页面浏览器打开http://localhost:3000/demos/shared-state-streaming。该路由注册在 src/app/api/copilotkit/route.tsCopilotRuntime中显式注册了名为shared-state-streaming的 Agent通过createBuiltInAgent()工厂创建并使用InMemoryAgentRunner在进程内运行前端通过runtimeUrl/api/copilotkit与agentshared-state-streaming建立连接。三、页面加载基线检查QA 文档要求先做三项页面加载基线验证用于确认环境就绪、UI 骨架完整左侧列可见页面标题State Streaming左侧面板内显示斜体占位提示The agent will fill this panel as it streams updates.位于带边框的pre块中右侧列可见聊天输入框。对照源码这些检查点与 document-view.tsx 的实现一一对应面板头部标题为Document而页面级标题 State Streaming 由 Demo 页面框架渲染空状态时content.length 0 !isStreaming渲染斜体占位文案Ask the agent to write something — its output will stream here token by token.聊天输入由 demo-layout.tsx 中的CopilotSidebar提供其chatInputPlaceholder被配置为Ask me to write something...。值得一提的是组件中每个关键 UI 元素都带有data-testid如document-view、document-char-count、document-live-badge、document-content这是为端到端测试预留的稳定选择器详见后文第五节。四、快乐路径令牌级流式渲染的验证与原理4.1 QA 验证步骤QA 文档定义的主流程Happy path如下发送指令Write a short essay about small habits, and stream the document to state as you go.验证文本在Agent 仍在响应的过程中就逐步出现在左侧面板而不是等全部完成才一次性显示该行为要求 Agent 在每个 chunk上调用AGUISendStateDelta携带形如{ op: replace, path: /document, value: partial text }的增量负载Agent 结束后验证左侧面板展示完整文章全文。4.2 后端增量工具的定义AGUISendStateDelta是内置 Agent 暴露给 LLM 的状态工具之一定义在 src/lib/factory/state-tools.tsAGUISendStateSnapshot以完整快照替换整个应用状态入参为snapshotAGUISendStateDelta使用JSON Patch 操作数组对状态做增量更新。其 schema 限定op取值枚举[add, replace, remove]并允许path指向任意 JSON 指针路径如/document以及可选的value。这正是 QA 文档中{ op: replace, path: /document, value: partial text }的来源——每次工具调用参数delta数组里携带一个用当前位置的部分文本来替换/document的补丁多个 chunk 的replace连续叠加就形成了文档逐 token 生长的效果。4.3 事件转换链路从 TanStack 流到 AG-UI STATE_DELTA内置 Agent 运行在 TanStack AI 的chat()多轮循环之上而前端消费的是 AG-UI 协议事件。两者之间的桥梁是 src/lib/factory/tanstack-factory.ts 中的流转换器其关键处理逻辑见 L110-L190TOOL_CALL_START登记toolCallId → toolName发出TOOL_CALL_START事件TOOL_CALL_ARGS每个 chunk 的delta都被追加累积进toolArgsById对应 QA 文档所说的每个 chunk 调用一次 AGUISendStateDelta并透传TOOL_CALL_ARGS事件TOOL_CALL_RESULT当检测到工具名为AGUISendStateDelta且结果对象含delta字段时将delta数组包装为 AG-UI 的STATE_DELTA事件L180-L190同理AGUISendStateSnapshot的结果被转换为STATE_SNAPSHOT事件。从源码结构可以推断TOOL_CALL_ARGS阶段的逐 chunk 透传 结果阶段的STATE_DELTA聚合就是工具调用在途即可更新状态的底层实现机制——前端无需等待工具结束就能持续收到状态增量。4.4 前端订阅useAgent 的双通道更新前端页面 src/app/demos/shared-state-streaming/page.tsx 通过useAgent同时订阅两类更新const { agent } useAgent({ agentId: shared-state-streaming, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], });OnStateChanged驱动每次状态变化即每个增量 token 到达时的文档重渲染OnRunStatusChanged驱动LIVE 徽标的出现与消失。随后页面从agent.state读取document字段并以agent.isRunning控制光标与徽标传给DocumentView。DocumentView在流式期间同时展示三个视觉证据红色 LIVE 徽标、跳动的光标块、实时增长的chars字符计数见 document-view.tsx三者共同让逐 token 流式这一行为变得直观可验证。4.5 参考实现的中间件形态Demo 的 README.md 指出这一行为的魔法在参考后端LangGraph Python 等中体现为一行中间件配置StateStreamingMiddleware( StateItem( state_keydocument, toolwrite_document, tool_argumentcontent, ) )其语义是将write_document工具参数content的每个流式 token 即时镜像进document状态键没有它state.document只能在工具调用结束后一次性更新。需要说明的是该中间件属于 Python 侧参考实现Built-in AgentTanStack AI运行时没有 Python 中间件而是通过AGUISendStateDelta工具 TanStack→AG-UI 事件转换器实现等价行为对应 state-tools.ts 与 tanstack-factory.ts。理解两者对应关系有助于在不同后端之间迁移同样的流式状态同步能力。五、边界情况非流式消息与二次请求QA 文档要求额外验证两个边界场景它们分别检验状态不被无关对话污染与新文档替换旧文档而非追加场景一非流式消息不触碰状态。发送不请求文档流式的消息如What time is it?验证 Agent 在聊天栏正常回复而左侧文档面板保持不变。其原理是document状态只在AGUISendStateDelta携带/document路径补丁时才会被修改普通文本回复只产生TEXT_MESSAGE_CHUNK事件tanstack-factory.ts不产生状态增量。场景二第二次流式请求替换旧内容。再发一次流式请求验证左侧面板被新文档整体替换而不是追加到旧文档之后。这与 QA 文档与状态工具都采用的op: replace语义直接相关每一次流式都以replace /document覆盖该路径天然满足整体替换预期若改用add或append语义则会破坏此行为。六、E2E 测试佐证与自动化回归上述 QA 检查点并非只能人工执行——仓库提供了完整的 Playwright 端到端测试 tests/e2e/shared-state-streaming.spec.ts将其固化为自动化回归用例测试用例对应验证点page loads with document panel and chat sidebar文档面板、标题、0 chars初始计数与聊天输入框就位empty state shows placeholder text空状态下斜体占位文案可见document-content不出现starter suggestions render in the sidebar三个建议按钮诗、邮件、量子计算渲染正常sending a message triggers document streaming发送消息后文档内容出现且长度超过 10 字符character count updates as document streams字符计数从 0 增长证明增量到达live badge appears while agent is streaming流式期间 LIVE 徽标可见、空闲时不可见assistant responds in the sidebar chat聊天栏出现助手回复这些用例在beforeEach中统一访问/demos/shared-state-streaming路由与 QA 文档的验证路径保持一致。其中字符计数增长与LIVE 徽标出现两条正是快乐路径增量流式的可量化断言可作为人工 QA 的自动化替代。七、交互建议与实操提示为快速触发流式效果Demo 提供了三个内置建议见 suggestions.ts点击即可发送Write a short poem about autumn leaves.Draft a polite email declining a meeting next Tuesday afternoon.Write a 2-paragraph explanation of quantum computing for a curious teenager.这些建议通过useConfigureSuggestions({ suggestions, available: always })注入available: always表示任何对话阶段都可用。总结shared-state-streaming演示并验证了 CopilotKit 生态中一项关键能力共享 Agent 状态可以在工具调用尚未完成时逐 token 流式更新。从 QA 视角看验证要点集中在三处——页面加载基线、快乐路径的增量渲染、以及非流式消息与二次请求两个边界从实现视角看它由状态工具AGUISendStateDelta的 JSON Patch 增量、事件转换器TanStack 流 → AG-UISTATE_DELTA与前端useAgent双通道订阅三部分协作完成并有完整的 Playwright 测试作为自动化保障。掌握这条链路即可在自己的 CopilotKit 应用中复现文档/画布/表单随 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考