：State Streaming 演示的 QA 验证清单与逐 token 状态流式实现)
CopilotKit × MS Agent Framework (.NET)State Streaming 演示的 QA 验证清单与逐 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/CopilotKit本篇以 CopilotKit 仓库中 MS Agent Framework.NETshowcase 的shared-state-streaming演示 QA 清单为骨架讲解如何验证State Streaming演示的可用性并深入拆解其底层逐 token 状态流式per-token state streaming机制从 .NET 侧的write_document工具、运行时的TOOL_CALL_ARGS → STATE_SNAPSHOT中间件到前端useAgent驱动的DocumentView。读完后你既能按清单完成该演示的验收也能理解它字符级实时生长的完整调用链与可执行断言。一、State Streaming 演示的定位与核心概念该演示位于 MS Agent Framework.NET集成 showcase 内对应前端路由为/demos/shared-state-streaming。其演示目标用一句可验证的话概括就是把一次工具调用tool call的字符串参数逐 token 地流式写入到 agent 的共享状态里——文档在 UI 中逐字符生长而此刻这次工具调用其实仍在进行中。该演示的自述见 演示 README是Per-token streaming of a tool argument directly into shared agent state即工具参数被逐 token 镜像进状态键document。QA 清单qa/shared-state-streaming.md把这一演示列为State Streaming作为整篇验证的主对象。说明README 里给出的是 Python 参考实现StateStreamingMiddleware(StateItem(state_keydocument, toolwrite_document, tool_argumentcontent))。但当前 showcase 的后端是 .NET Agent Framework运行时在源码注释中明确写道the .NET host has nopredict_state_config, so per-token emission is done here on the route见 route.ts 第 892–897 行。也就是说.NET 这条链路是靠运行时中间件在路由层补出逐 token 快照的后文会专门拆解。二、前置条件与运行环境QA 清单给出的前置条件只有两条但对照源码后可以落到具体可检查的端点上演示已部署并可访问页面挂在/demos/shared-state-streaming见 演示 page。Agent 后端健康检查/api/health前端存在 health 路由同时 CopilotKit 运行时在 GET 探针里会fetch(${AGENT_URL}/health)其中AGENT_URL默认http://localhost:8000见 route.ts 第 12–13、989–999 行。由此可以推断出该演示的运行拓扑Next.js 前端 独立的 .NET Agent 后端默认 :8000前端通过/api/copilotkit这条 single-route 运行时以 AG-UI 协议代理到后端/shared-state-streaming路径见 route.tscreateCopilotRuntimeHandler第 952–969 行 与agents[shared-state-streaming] createSharedStateStreamingAgent()第 898 行。三、QA 验证清单继承 QA 文档骨架下面完整继承 QA 清单的原始检查项并逐条对照当前源码给出的实际可验证锚点。1. 基础功能Basic Functionality清单原始步骤为导航到演示页 → 校验聊天界面以标题State Streaming加载 → 校验输入框 placeholderType a message...可见 → 发送一条基础消息如Hello! What can you do?→ 校验 agent 响应。对照当前实现可验证的 DOM 锚点来自 Playwright spec文档面板以[data-testiddocument-view]挂载内部标题文案为Document字符计数初始为0 chars[data-testiddocument-char-count]侧边栏输入框 placeholder 实为Ask me to write something...来自 demo-layout.tsx 第 19–25 行。⚠️ 清单中写的标题State Streaming与 placeholderType a message...与当前实现存在偏差详见第八节差异说明。验收时建议以 E2E 断言的Document/Ask me to write something...为准。2. 功能点检查Suggestions 与Stub状态说明清单原始条目包含校验Get started建议按钮可见并标注Status: Stub — This demo is currently a stub (TODO: implement)期望仅基础 CopilotChat 加载并接受消息、agent 能响应、除聊天外无自定义 UI。当前实现里建议 chips 由 suggestions.ts 通过useConfigureSuggestions({ available: always })注入共三颗不是单个Get startedWrite a short poem→ Write a short poem about autumn leaves.Draft an email→ Draft a polite email declining a meeting next Tuesday afternoon.Explain quantum computing→ Write a 2-paragraph explanation of quantum computing for a curious teenager.E2E 中starter suggestions render in the sidebar用例正是逐一断言这三颗按钮可见。这说明当前仓库中的演示已经不是清单所记录的 Stub 状态它带有完整的自定义DocumentView面板。3. 异常处理Error Handling清单要求发送空消息应被妥善处理正常使用期间不应有控制台错误。对照实现可验证的行为来自 document-view.tsx 第 54–59 行当content.length 0 !isStreaming时展示占位提示Ask the agent to write something — its output will stream here token by token.且此时[data-testiddocument-content]不应可见E2E 的empty state shows placeholder text用例正是这一断言。空消息不会破坏布局文档面板会稳定停留在占位态。4. 预期结果与时间阈值Expected Results清单给出的验收阈值是聊天 3 秒内加载agent 10 秒内响应无 UI 错误或布局错乱。这些是 QA 文档既定的验收标准非性能基准可直接作为回归门槛沿用。四、逐 token 状态流式.NET 侧write_document工具演示的魔法起点是一个 .NET 工具。在 agent/D5ParityAgents.cs 第 120 行 的CreateSharedStateStreamingAgent()中注册了一个名为write_document的工具第 132 行agent 名称为SharedStateStreamingAgent第 143 行其 system instructions第 144 行明确要求Whenever the user asks you to write, draft, or revise text, ALWAYS callwrite_documentwith the full content as a single string in thedocumentargument. Never paste the document into a chat message directly — the document belongs in shared state and the UI renders it live as you type.这条指令保证了模型的产出会被塞进工具的document字符串参数而不是直接吐进聊天消息气泡。该 agent 在 agent/Program.cs 第 65 行 通过app.MapAGUI(/shared-state-streaming, d5ParityFactory.CreateSharedStateStreamingAgent())挂载到 AG-UI 路径。五、运行时中间件把TOOL_CALL_ARGS增量变成STATE_SNAPSHOT真正让 UI逐 token 生长的关键在 CopilotKit 运行时的路由层核心是 route.ts 第 602–687 行 的createSharedStateStreamingAgent()。其工作机制如下捕获工具调用开始当事件TOOL_CALL_START且toolCallName write_document时把toolCallId记入集合并吞掉该事件文档应活在状态里而不是聊天 tool-call 气泡里。缓冲参数增量对TOOL_CALL_ARGS事件把delta追加到argsByToolCallId的 JSON 缓冲中每追加一次就尝试解码出当前document值。按需发射快照只有当解码出的文档字符串真的增长/变化时才发射{ type: STATE_SNAPSHOT, snapshot: { document } }避免结构性 JSON 字符造成冗余快照。清理TOOL_CALL_RESULT时移除该toolCallId相关的缓冲与去重记录。解码的难点是JSON.parse无法解析流到一半的 JSON比如{document:Autumn lea。为此 route.ts 第 524–588 行 的extractStreamingDocument手写了一个字符串值增量解码器先用正则定位document:再逐字符扫描并处理转义序列\n、\t、\、\\、\/等遇到尚未流完的\uXXXX就等待下一个 delta遇到未转义收尾引号即判定字符串值完整。这保证了在工具调用结束前state.document就能逐 token 更新。对照 READMEPython 参考版靠StateStreamingMiddleware完成同样语义而 .NET 这条链因为宿主没有对应中间件改由上述路由层 shim 复现README 的tool_argument写作content而 .NET 实际参数名是document见 D5ParityAgents.cs 第 144 行 与 route.ts 第 533 行 对document键的匹配。六、前端渲染useAgent与DocumentView前端只订阅状态与运行状态两路更新见 page.tsx 第 30–42 行const { agent } useAgent({ agentId: shared-state-streaming, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); const document (agent.state as StreamingAgentState | undefined)?.document ?? ; const isRunning agent.isRunning; return DemoLayout document{document} isStreaming{isRunning} /;OnStateChanged驱动逐 token 的文档重渲染OnRunStatusChanged则在 agent 起止时切换 LIVE 徽标agent.isRunning进一步控制光标闪烁。document-view.tsx 把state.document渲染成活文档面板LIVE徽标data-testiddocument-live-badge、字符计数document-char-count、以及一个随isStreaming出现的闪烁光标内容区data-testiddocument-content用whitespace-pre-wrap保留换行。整体布局是文档面板 右侧CopilotSidebar侧边栏defaultOpen且 placeholder 为Ask me to write something...见 demo-layout.tsx 第 19–25 行。三者合起来使得每收到一个流式 token父组件就以更长的content字符串重新渲染 DocumentView——这正是 QA 清单逐 token要验证的现象。七、自动化 E2E把 QA 清单变成可执行断言QA 清单的手工检查项在仓库里有一一映射的可执行 Playwright 用例tests/e2e/shared-state-streaming.spec.ts。用例覆盖page loads with document panel and chat sidebar面板挂载、Document标题、初始0 chars、侧边栏输入框存在empty state shows placeholder text空态占位文案可见、document-content不可见starter suggestions render in the sidebar三颗建议按钮可见sending a message triggers document streaming发送消息后document-content出现且长度 10character count updates as document streams字符数从 0 增长live badge appears while agent is streamingdocument-live-badge在 agent 运行时出现assistant responds in the sidebar chat侧边栏出现copilot-assistant-message。这一 spec 事实上就是 QA 清单的机器可读版本可作为 CI 回归直接运行替代人工勾选。八、QA 清单与当前实现的差异测试维护提示为保证验收口径与现状一致建议对照源码更新 QA 清单主要差异点均可在源码中核对状态清单标注 Status: Stub但当前实现已具备完整的DocumentView、LIVE徽标与字符计数除聊天外无自定义 UI的期望已不成立。标题 / placeholder清单写State Streaming与Type a message...实际面板标题为Document、侧边栏 placeholder 为Ask me to write something...。建议按钮清单写单个Get started实际是三颗固定主题 chips诗 / 邮件 / 量子计算。这些差异不影响逐 token 状态流式这一核心主题的验证但直接照抄旧清单会产生误判。建议把第八节的实际锚点回填进 qa/shared-state-streaming.md并以 Playwright spec 作为权威验收断言。注本文为只读介绍仅说明查看、运行与配置方式不改动仓库内容。【免费下载链接】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 × MS Agent Framework (.NET)：State Streaming 演示的 QA 验证清单与逐 token 状态流式实现
CopilotKit × MS Agent Framework (.NET)State Streaming 演示的 QA 验证清单与逐 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/CopilotKit本篇以 CopilotKit 仓库中 MS Agent Framework.NETshowcase 的shared-state-streaming演示 QA 清单为骨架讲解如何验证State Streaming演示的可用性并深入拆解其底层逐 token 状态流式per-token state streaming机制从 .NET 侧的write_document工具、运行时的TOOL_CALL_ARGS → STATE_SNAPSHOT中间件到前端useAgent驱动的DocumentView。读完后你既能按清单完成该演示的验收也能理解它字符级实时生长的完整调用链与可执行断言。一、State Streaming 演示的定位与核心概念该演示位于 MS Agent Framework.NET集成 showcase 内对应前端路由为/demos/shared-state-streaming。其演示目标用一句可验证的话概括就是把一次工具调用tool call的字符串参数逐 token 地流式写入到 agent 的共享状态里——文档在 UI 中逐字符生长而此刻这次工具调用其实仍在进行中。该演示的自述见 演示 README是Per-token streaming of a tool argument directly into shared agent state即工具参数被逐 token 镜像进状态键document。QA 清单qa/shared-state-streaming.md把这一演示列为State Streaming作为整篇验证的主对象。说明README 里给出的是 Python 参考实现StateStreamingMiddleware(StateItem(state_keydocument, toolwrite_document, tool_argumentcontent))。但当前 showcase 的后端是 .NET Agent Framework运行时在源码注释中明确写道the .NET host has nopredict_state_config, so per-token emission is done here on the route见 route.ts 第 892–897 行。也就是说.NET 这条链路是靠运行时中间件在路由层补出逐 token 快照的后文会专门拆解。二、前置条件与运行环境QA 清单给出的前置条件只有两条但对照源码后可以落到具体可检查的端点上演示已部署并可访问页面挂在/demos/shared-state-streaming见 演示 page。Agent 后端健康检查/api/health前端存在 health 路由同时 CopilotKit 运行时在 GET 探针里会fetch(${AGENT_URL}/health)其中AGENT_URL默认http://localhost:8000见 route.ts 第 12–13、989–999 行。由此可以推断出该演示的运行拓扑Next.js 前端 独立的 .NET Agent 后端默认 :8000前端通过/api/copilotkit这条 single-route 运行时以 AG-UI 协议代理到后端/shared-state-streaming路径见 route.tscreateCopilotRuntimeHandler第 952–969 行 与agents[shared-state-streaming] createSharedStateStreamingAgent()第 898 行。三、QA 验证清单继承 QA 文档骨架下面完整继承 QA 清单的原始检查项并逐条对照当前源码给出的实际可验证锚点。1. 基础功能Basic Functionality清单原始步骤为导航到演示页 → 校验聊天界面以标题State Streaming加载 → 校验输入框 placeholderType a message...可见 → 发送一条基础消息如Hello! What can you do?→ 校验 agent 响应。对照当前实现可验证的 DOM 锚点来自 Playwright spec文档面板以[data-testiddocument-view]挂载内部标题文案为Document字符计数初始为0 chars[data-testiddocument-char-count]侧边栏输入框 placeholder 实为Ask me to write something...来自 demo-layout.tsx 第 19–25 行。⚠️ 清单中写的标题State Streaming与 placeholderType a message...与当前实现存在偏差详见第八节差异说明。验收时建议以 E2E 断言的Document/Ask me to write something...为准。2. 功能点检查Suggestions 与Stub状态说明清单原始条目包含校验Get started建议按钮可见并标注Status: Stub — This demo is currently a stub (TODO: implement)期望仅基础 CopilotChat 加载并接受消息、agent 能响应、除聊天外无自定义 UI。当前实现里建议 chips 由 suggestions.ts 通过useConfigureSuggestions({ available: always })注入共三颗不是单个Get startedWrite a short poem→ Write a short poem about autumn leaves.Draft an email→ Draft a polite email declining a meeting next Tuesday afternoon.Explain quantum computing→ Write a 2-paragraph explanation of quantum computing for a curious teenager.E2E 中starter suggestions render in the sidebar用例正是逐一断言这三颗按钮可见。这说明当前仓库中的演示已经不是清单所记录的 Stub 状态它带有完整的自定义DocumentView面板。3. 异常处理Error Handling清单要求发送空消息应被妥善处理正常使用期间不应有控制台错误。对照实现可验证的行为来自 document-view.tsx 第 54–59 行当content.length 0 !isStreaming时展示占位提示Ask the agent to write something — its output will stream here token by token.且此时[data-testiddocument-content]不应可见E2E 的empty state shows placeholder text用例正是这一断言。空消息不会破坏布局文档面板会稳定停留在占位态。4. 预期结果与时间阈值Expected Results清单给出的验收阈值是聊天 3 秒内加载agent 10 秒内响应无 UI 错误或布局错乱。这些是 QA 文档既定的验收标准非性能基准可直接作为回归门槛沿用。四、逐 token 状态流式.NET 侧write_document工具演示的魔法起点是一个 .NET 工具。在 agent/D5ParityAgents.cs 第 120 行 的CreateSharedStateStreamingAgent()中注册了一个名为write_document的工具第 132 行agent 名称为SharedStateStreamingAgent第 143 行其 system instructions第 144 行明确要求Whenever the user asks you to write, draft, or revise text, ALWAYS callwrite_documentwith the full content as a single string in thedocumentargument. Never paste the document into a chat message directly — the document belongs in shared state and the UI renders it live as you type.这条指令保证了模型的产出会被塞进工具的document字符串参数而不是直接吐进聊天消息气泡。该 agent 在 agent/Program.cs 第 65 行 通过app.MapAGUI(/shared-state-streaming, d5ParityFactory.CreateSharedStateStreamingAgent())挂载到 AG-UI 路径。五、运行时中间件把TOOL_CALL_ARGS增量变成STATE_SNAPSHOT真正让 UI逐 token 生长的关键在 CopilotKit 运行时的路由层核心是 route.ts 第 602–687 行 的createSharedStateStreamingAgent()。其工作机制如下捕获工具调用开始当事件TOOL_CALL_START且toolCallName write_document时把toolCallId记入集合并吞掉该事件文档应活在状态里而不是聊天 tool-call 气泡里。缓冲参数增量对TOOL_CALL_ARGS事件把delta追加到argsByToolCallId的 JSON 缓冲中每追加一次就尝试解码出当前document值。按需发射快照只有当解码出的文档字符串真的增长/变化时才发射{ type: STATE_SNAPSHOT, snapshot: { document } }避免结构性 JSON 字符造成冗余快照。清理TOOL_CALL_RESULT时移除该toolCallId相关的缓冲与去重记录。解码的难点是JSON.parse无法解析流到一半的 JSON比如{document:Autumn lea。为此 route.ts 第 524–588 行 的extractStreamingDocument手写了一个字符串值增量解码器先用正则定位document:再逐字符扫描并处理转义序列\n、\t、\、\\、\/等遇到尚未流完的\uXXXX就等待下一个 delta遇到未转义收尾引号即判定字符串值完整。这保证了在工具调用结束前state.document就能逐 token 更新。对照 READMEPython 参考版靠StateStreamingMiddleware完成同样语义而 .NET 这条链因为宿主没有对应中间件改由上述路由层 shim 复现README 的tool_argument写作content而 .NET 实际参数名是document见 D5ParityAgents.cs 第 144 行 与 route.ts 第 533 行 对document键的匹配。六、前端渲染useAgent与DocumentView前端只订阅状态与运行状态两路更新见 page.tsx 第 30–42 行const { agent } useAgent({ agentId: shared-state-streaming, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); const document (agent.state as StreamingAgentState | undefined)?.document ?? ; const isRunning agent.isRunning; return DemoLayout document{document} isStreaming{isRunning} /;OnStateChanged驱动逐 token 的文档重渲染OnRunStatusChanged则在 agent 起止时切换 LIVE 徽标agent.isRunning进一步控制光标闪烁。document-view.tsx 把state.document渲染成活文档面板LIVE徽标data-testiddocument-live-badge、字符计数document-char-count、以及一个随isStreaming出现的闪烁光标内容区data-testiddocument-content用whitespace-pre-wrap保留换行。整体布局是文档面板 右侧CopilotSidebar侧边栏defaultOpen且 placeholder 为Ask me to write something...见 demo-layout.tsx 第 19–25 行。三者合起来使得每收到一个流式 token父组件就以更长的content字符串重新渲染 DocumentView——这正是 QA 清单逐 token要验证的现象。七、自动化 E2E把 QA 清单变成可执行断言QA 清单的手工检查项在仓库里有一一映射的可执行 Playwright 用例tests/e2e/shared-state-streaming.spec.ts。用例覆盖page loads with document panel and chat sidebar面板挂载、Document标题、初始0 chars、侧边栏输入框存在empty state shows placeholder text空态占位文案可见、document-content不可见starter suggestions render in the sidebar三颗建议按钮可见sending a message triggers document streaming发送消息后document-content出现且长度 10character count updates as document streams字符数从 0 增长live badge appears while agent is streamingdocument-live-badge在 agent 运行时出现assistant responds in the sidebar chat侧边栏出现copilot-assistant-message。这一 spec 事实上就是 QA 清单的机器可读版本可作为 CI 回归直接运行替代人工勾选。八、QA 清单与当前实现的差异测试维护提示为保证验收口径与现状一致建议对照源码更新 QA 清单主要差异点均可在源码中核对状态清单标注 Status: Stub但当前实现已具备完整的DocumentView、LIVE徽标与字符计数除聊天外无自定义 UI的期望已不成立。标题 / placeholder清单写State Streaming与Type a message...实际面板标题为Document、侧边栏 placeholder 为Ask me to write something...。建议按钮清单写单个Get started实际是三颗固定主题 chips诗 / 邮件 / 量子计算。这些差异不影响逐 token 状态流式这一核心主题的验证但直接照抄旧清单会产生误判。建议把第八节的实际锚点回填进 qa/shared-state-streaming.md并以 Playwright spec 作为权威验收断言。注本文为只读介绍仅说明查看、运行与配置方式不改动仓库内容。【免费下载链接】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），仅供参考