CopilotKit AG2 集成实战State Streaming 演示——把工具参数逐 Token 流入共享 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本文以 CopilotKit 仓库中 AG2 集成的 State Streaming状态流式演示为蓝本完整讲解工具调用参数逐 token 写入共享 agent 状态这一机制从StateStreamingMiddleware这一行后端中间件配置到前端useAgent双事件订阅驱动打字机式文档面板的落地方式并结合该 demo 在仓库中的路由注册、E2E 测试与同模式的 LangGraph Python 实现做源码级印证。读完本文你将掌握如何在任意 CopilotKit 支持的 agent 框架中把write_document这类长文本工具的参数流式映射到状态键以及如何在前端订阅状态与运行状态变化渲染出带 LIVE 徽标、闪烁光标和字符计数的实时文档视图。演示要解决的核心问题共享 agent 状态shared agent state是 CopilotKit 的 Generative UI 基础能力之一agent 后端把状态键值对推送给前端前端据此渲染自定义 UI。默认情况下一个工具调用的参数只有在工具调用结束时才会作为整体落入状态——如果document键承载的是一篇几百字的长文用户要等到生成完全结束才看到内容。State Streaming 演示展示了另一种形态per-token streaming of a tool argument directly into shared agent state——工具调用尚在飞行途中document就已经在界面上逐字符增长。演示包含三个可观察要素见 README实时文档面板state.document渲染在文档视图中带闪烁光标和 LIVE 徽标Token 级增量agentwrite_document工具参数中每一个流式 token 都直接转发到document状态键字符计数器实时跳动的字符数让逐 token 流式过程清晰可见。如何与演示交互演示页面提供三个建议芯片suggestion chips也可以直接输入同类指令来源README、suggestions.tsWrite 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注入侧边栏available: always使其始终可用import { useConfigureSuggestions } from copilotkit/react-core/v2; export function useSharedStateStreamingSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Write a short poem, message: Write a short poem about autumn leaves., }, { title: Draft an email, message: Draft a polite email declining a meeting next Tuesday afternoon., }, { title: Explain quantum computing, message: Write a 2-paragraph explanation of quantum computing for a curious teenager., }, ], available: always, }); }发送任一消息后观察右侧文档面板被实时填上内容——agent 写的每一个 token 都会即时出现在面板里。前端实现双事件订阅驱动的文档面板页面入口与状态订阅页面组件位于 page.tsx。外层用CopilotKitProvider 指定运行时地址与 agent 名称内层DemoContent做状态订阅CopilotKit runtimeUrl/api/copilotkit agentshared-state-streaming DemoContent / /CopilotKit ); } function DemoContent() { // region[frontend-use-coagent-state] // Subscribe to BOTH state changes and run-status changes. The former // drives the per-token document rerender; the latter toggles the // LIVE badge when the agent starts / stops. const { agent } useAgent({ agentId: shared-state-streaming, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); // endregion[frontend-use-coagent-state] useSharedStateStreamingSuggestions(); const agentState agent.state as StreamingAgentState | undefined; const document agentState?.document ?? ; const isRunning agent.isRunning; return DemoLayout document{document} isStreaming{isRunning} /; }关键在useAgent的updates参数README 中一句话概括的原理对应着两个枚举值订阅项驱动效果UseAgentUpdate.OnStateChanged每次state.document收到增量即触发重渲染——这是逐 token 文本更新的数据源UseAgentUpdate.OnRunStatusChangedagent 开始/停止运行时切换 LIVE 徽标的显隐此外agent.isRunning布尔量被用来切换文档视图中闪烁光标的显示。三者组合后前端不需要任何轮询或手动 diffLLM 每吐一个 token后端把增量写进documentOnStateChanged触发一次重渲染面板自然向前打字。状态结构在前端用最小接口声明interface StreamingAgentState { document?: string; }文档面板LIVE 徽标、光标与字符计数document-view.tsx 中的DocumentView是一个纯受控组件把流式过程可视化成三个 UI 信号export function DocumentView({ content, isStreaming }: DocumentViewProps) { const charCount content.length; // ... span classNametext-lg font-semiboldDocument/span {isStreaming ( span>CopilotSidebar agentIdshared-state-streaming defaultOpen{true} labels{{ chatInputPlaceholder: Ask me to write something..., }} /后端核心一条中间件配置README 指出让document状态从工具结束后一次性更新变为token 级增量更新的全部后端魔法是一条中间件配置StateStreamingMiddleware( StateItem( state_keydocument, toolwrite_document, tool_argumentcontent, ) )三个参数的语义参数含义state_keydocument目标共享状态键前端从agent.state.document读取toolwrite_document被监听的工具名只有该工具的调用参数会被转发tool_argumentcontent被转发为状态增量的具体参数名——LLM 为该参数生成的每个 token 都会立即镜像进状态对照效果没有这条中间件state.document只在工具调用结束时更新一次加上之后LLM 为content参数生成的每个 token 都即时写入状态。StateStreamingMiddleware与StateItem均由 CopilotKit Python SDK 导出可从 sdk-python/copilotkit/__init__.py 确认二者的公开导出。值得注意的是README 只给出配置骨架完整可运行的同款实现在仓库中另一个姊妹集成里有直接参考langgraph-python 的 shared_state_streaming.py 用 LangGraph 实现了完全相同的设计——在AgentState上声明document: str定义write_document(document: str, runtime: ToolRuntime)工具工具文档字符串明确写道Thedocumentargument is streamedper tokeninto shared agent state under thedocumentkey再通过StateStreamingMiddleware(StateItem(...))挂到 agent 上。这个文件是理解本演示中间件行为最完整的 Python 参照。仓库中的路由注册与 E2E 验证Agent 名称代理机制从 route.ts 的源码结构看AG2 集成的后端用AGUIStream包装单个ConversableAgent大多数 agent 名称都代理到同一个后端进程只是注册名不同。shared-state-streaming就在sharedAgentNames列表中——即前端agentshared-state-streaming/agentIdshared-state-streaming最终解析到共享的 AG2 agent。这也解释了为什么 demo 目录下没有独立的 Python 后端文件后端复用共享 agent演示差异体现在 agent 名称与前端订阅逻辑上。该 demo 同时登记在 manifest.yaml 中id: shared-state-streaming、name: State Streaming、description: Per-token state delta streaming from agent to UI路由为/demos/shared-state-streaming。E2E 测试覆盖了哪些行为shared-state-streaming.spec.ts 用 Playwright 对该演示做了系统验证断言点与文档声明一一对应页面加载[data-testiddocument-view]可见Document 标题可见字符计数初始为 0 chars侧边栏输入框占位符可见空状态无内容时显示斜体占位文案且document-content节点不可见建议芯片三个建议按钮Write a short poem / Draft an email / Explain quantum computing均可见流式写入发送 Write a short poem about autumn leaves. 后document-content在 60 秒内出现且文本长度大于 10字符计数增长document-char-count从 0 chars 变为大于 0LIVE 徽标发送前不可见agent 运行期间document-live-badge出现侧边栏回复copilot-assistant-message消息出现。这份测试实际上给出了如何验证 per-token 流式真的生效的可复用检查清单观察字符计数是否在生成过程中持续增长而非在末尾一次性跳到终值。要点小结一条配置完成状态流式StateStreamingMiddleware(StateItem(state_key, tool, tool_argument))把指定工具的指定参数 token 级转发进共享状态是 CopilotKit 把工具中间产物实时暴露给 UI 的通用机制前端双订阅模式useAgent({ updates: [OnStateChanged, OnRunStatusChanged] })agent.isRunning分别驱动文本增量渲染与 LIVE 徽标/光标开关这套写法可迁移到任何共享状态演示可视化三信号LIVE 徽标、闪烁光标、字符计数器让 token 级流式过程对用户可感知完整证据链本 demo 的前端实现page.tsx/document-view.tsx/demo-layout.tsx/suggestions.ts、路由注册route.ts、manifest.yaml与 E2E 测试tests/e2e/shared-state-streaming.spec.ts均在 showcase/integrations/ag2 目录内可直接对照阅读。适用前提以上行为以当前仓库版本的 AG2 集成演示为准运行该 demo 需要 AG2 后端AG2 的AGUIStreamConversableAgent与前端 Next.js 应用同时可用若要在自己的框架上复刻可参考仓库中 LangGraph Python 版同名 demo 的完整后端写法。【免费下载链接】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 AG2 集成实战：State Streaming 演示——把工具参数逐 Token 流入共享 Agent 状态
CopilotKit AG2 集成实战State Streaming 演示——把工具参数逐 Token 流入共享 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本文以 CopilotKit 仓库中 AG2 集成的 State Streaming状态流式演示为蓝本完整讲解工具调用参数逐 token 写入共享 agent 状态这一机制从StateStreamingMiddleware这一行后端中间件配置到前端useAgent双事件订阅驱动打字机式文档面板的落地方式并结合该 demo 在仓库中的路由注册、E2E 测试与同模式的 LangGraph Python 实现做源码级印证。读完本文你将掌握如何在任意 CopilotKit 支持的 agent 框架中把write_document这类长文本工具的参数流式映射到状态键以及如何在前端订阅状态与运行状态变化渲染出带 LIVE 徽标、闪烁光标和字符计数的实时文档视图。演示要解决的核心问题共享 agent 状态shared agent state是 CopilotKit 的 Generative UI 基础能力之一agent 后端把状态键值对推送给前端前端据此渲染自定义 UI。默认情况下一个工具调用的参数只有在工具调用结束时才会作为整体落入状态——如果document键承载的是一篇几百字的长文用户要等到生成完全结束才看到内容。State Streaming 演示展示了另一种形态per-token streaming of a tool argument directly into shared agent state——工具调用尚在飞行途中document就已经在界面上逐字符增长。演示包含三个可观察要素见 README实时文档面板state.document渲染在文档视图中带闪烁光标和 LIVE 徽标Token 级增量agentwrite_document工具参数中每一个流式 token 都直接转发到document状态键字符计数器实时跳动的字符数让逐 token 流式过程清晰可见。如何与演示交互演示页面提供三个建议芯片suggestion chips也可以直接输入同类指令来源README、suggestions.tsWrite 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注入侧边栏available: always使其始终可用import { useConfigureSuggestions } from copilotkit/react-core/v2; export function useSharedStateStreamingSuggestions() { useConfigureSuggestions({ suggestions: [ { title: Write a short poem, message: Write a short poem about autumn leaves., }, { title: Draft an email, message: Draft a polite email declining a meeting next Tuesday afternoon., }, { title: Explain quantum computing, message: Write a 2-paragraph explanation of quantum computing for a curious teenager., }, ], available: always, }); }发送任一消息后观察右侧文档面板被实时填上内容——agent 写的每一个 token 都会即时出现在面板里。前端实现双事件订阅驱动的文档面板页面入口与状态订阅页面组件位于 page.tsx。外层用CopilotKitProvider 指定运行时地址与 agent 名称内层DemoContent做状态订阅CopilotKit runtimeUrl/api/copilotkit agentshared-state-streaming DemoContent / /CopilotKit ); } function DemoContent() { // region[frontend-use-coagent-state] // Subscribe to BOTH state changes and run-status changes. The former // drives the per-token document rerender; the latter toggles the // LIVE badge when the agent starts / stops. const { agent } useAgent({ agentId: shared-state-streaming, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); // endregion[frontend-use-coagent-state] useSharedStateStreamingSuggestions(); const agentState agent.state as StreamingAgentState | undefined; const document agentState?.document ?? ; const isRunning agent.isRunning; return DemoLayout document{document} isStreaming{isRunning} /; }关键在useAgent的updates参数README 中一句话概括的原理对应着两个枚举值订阅项驱动效果UseAgentUpdate.OnStateChanged每次state.document收到增量即触发重渲染——这是逐 token 文本更新的数据源UseAgentUpdate.OnRunStatusChangedagent 开始/停止运行时切换 LIVE 徽标的显隐此外agent.isRunning布尔量被用来切换文档视图中闪烁光标的显示。三者组合后前端不需要任何轮询或手动 diffLLM 每吐一个 token后端把增量写进documentOnStateChanged触发一次重渲染面板自然向前打字。状态结构在前端用最小接口声明interface StreamingAgentState { document?: string; }文档面板LIVE 徽标、光标与字符计数document-view.tsx 中的DocumentView是一个纯受控组件把流式过程可视化成三个 UI 信号export function DocumentView({ content, isStreaming }: DocumentViewProps) { const charCount content.length; // ... span classNametext-lg font-semiboldDocument/span {isStreaming ( span>CopilotSidebar agentIdshared-state-streaming defaultOpen{true} labels{{ chatInputPlaceholder: Ask me to write something..., }} /后端核心一条中间件配置README 指出让document状态从工具结束后一次性更新变为token 级增量更新的全部后端魔法是一条中间件配置StateStreamingMiddleware( StateItem( state_keydocument, toolwrite_document, tool_argumentcontent, ) )三个参数的语义参数含义state_keydocument目标共享状态键前端从agent.state.document读取toolwrite_document被监听的工具名只有该工具的调用参数会被转发tool_argumentcontent被转发为状态增量的具体参数名——LLM 为该参数生成的每个 token 都会立即镜像进状态对照效果没有这条中间件state.document只在工具调用结束时更新一次加上之后LLM 为content参数生成的每个 token 都即时写入状态。StateStreamingMiddleware与StateItem均由 CopilotKit Python SDK 导出可从 sdk-python/copilotkit/__init__.py 确认二者的公开导出。值得注意的是README 只给出配置骨架完整可运行的同款实现在仓库中另一个姊妹集成里有直接参考langgraph-python 的 shared_state_streaming.py 用 LangGraph 实现了完全相同的设计——在AgentState上声明document: str定义write_document(document: str, runtime: ToolRuntime)工具工具文档字符串明确写道Thedocumentargument is streamedper tokeninto shared agent state under thedocumentkey再通过StateStreamingMiddleware(StateItem(...))挂到 agent 上。这个文件是理解本演示中间件行为最完整的 Python 参照。仓库中的路由注册与 E2E 验证Agent 名称代理机制从 route.ts 的源码结构看AG2 集成的后端用AGUIStream包装单个ConversableAgent大多数 agent 名称都代理到同一个后端进程只是注册名不同。shared-state-streaming就在sharedAgentNames列表中——即前端agentshared-state-streaming/agentIdshared-state-streaming最终解析到共享的 AG2 agent。这也解释了为什么 demo 目录下没有独立的 Python 后端文件后端复用共享 agent演示差异体现在 agent 名称与前端订阅逻辑上。该 demo 同时登记在 manifest.yaml 中id: shared-state-streaming、name: State Streaming、description: Per-token state delta streaming from agent to UI路由为/demos/shared-state-streaming。E2E 测试覆盖了哪些行为shared-state-streaming.spec.ts 用 Playwright 对该演示做了系统验证断言点与文档声明一一对应页面加载[data-testiddocument-view]可见Document 标题可见字符计数初始为 0 chars侧边栏输入框占位符可见空状态无内容时显示斜体占位文案且document-content节点不可见建议芯片三个建议按钮Write a short poem / Draft an email / Explain quantum computing均可见流式写入发送 Write a short poem about autumn leaves. 后document-content在 60 秒内出现且文本长度大于 10字符计数增长document-char-count从 0 chars 变为大于 0LIVE 徽标发送前不可见agent 运行期间document-live-badge出现侧边栏回复copilot-assistant-message消息出现。这份测试实际上给出了如何验证 per-token 流式真的生效的可复用检查清单观察字符计数是否在生成过程中持续增长而非在末尾一次性跳到终值。要点小结一条配置完成状态流式StateStreamingMiddleware(StateItem(state_key, tool, tool_argument))把指定工具的指定参数 token 级转发进共享状态是 CopilotKit 把工具中间产物实时暴露给 UI 的通用机制前端双订阅模式useAgent({ updates: [OnStateChanged, OnRunStatusChanged] })agent.isRunning分别驱动文本增量渲染与 LIVE 徽标/光标开关这套写法可迁移到任何共享状态演示可视化三信号LIVE 徽标、闪烁光标、字符计数器让 token 级流式过程对用户可感知完整证据链本 demo 的前端实现page.tsx/document-view.tsx/demo-layout.tsx/suggestions.ts、路由注册route.ts、manifest.yaml与 E2E 测试tests/e2e/shared-state-streaming.spec.ts均在 showcase/integrations/ag2 目录内可直接对照阅读。适用前提以上行为以当前仓库版本的 AG2 集成演示为准运行该 demo 需要 AG2 后端AG2 的AGUIStreamConversableAgent与前端 Next.js 应用同时可用若要在自己的框架上复刻可参考仓库中 LangGraph Python 版同名 demo 的完整后端写法。【免费下载链接】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），仅供参考