CopilotKit 共享状态（只读）实战：让 Agent 直接从前端状态中读取上下文
发布时间：2026/9/12 13:56:33 作者：尧图编辑部 阅读量：1,286
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/CopilotKitCopilotKit 的共享状态Shared State机制允许 Agent 读取与前端应用共同维护的同一份状态前端无需再把数据塞进对话上下文。本文以开源仓库中的shared-state-read演示一个AI 食谱助手为核心讲解只读场景下agent.setState、useAgent().state与后端runtime.state的完整调用链并给出可复制的类型契约、交互范式与测试验证方法。读完你可以在自己的 CopilotKit 应用中实现Agent 实时感知 UI 状态并据此作答的能力。演示概览Agent 读取食谱编辑器状态shared-state-read是 showcase/integrations/claude-sdk-typescript 下众多 Agent 演示中的一个注册在 manifest.yaml 中路由为/demos/shared-state-read标签为agent-state。该演示描述为 Agent reads frontend-provided state as context——即前端把状态发布给 AgentAgent 每一轮都读取这份状态作为上下文。页面上有一个受控的食谱编辑表单recipe-card用户可修改菜名、烹饪时间、难度等级、饮食偏好、食材列表与步骤说明右侧CopilotSidebar中则是 AI 食谱助手。由于 Agent 能读到这份状态你可以直接问What tasks are on my todo list?清单类场景的通用问法Summarize what I have to do要求 Agent 概括当前任务How many items are pending?基于当前数据的数量统计在食谱场景中对应的问题就是我现在在做什么菜——Agent 会读取当前的食谱数据并如实回答而不是凭空猜测。核心机制单一事实来源与单向数据流该演示的注释与文档明确了一个设计原则前端是状态的单一事实来源single source of truth。从源码看其数据流是单向的页面首次挂载时通过agent.setState把初始食谱写入 Agent 状态agent.state.recipe之后用户对表单的任何编辑都会立刻通过agent.setState回流到状态中Agent 每一轮对话都读取这份状态但不会修改它——演示接线的是无工具的中性默认 Agent见 page.tsx 的头部注释。对比同目录下的shared-state-read-write演示README可以更清楚理解只读模式的边界读写版中 Agent 通过set_notes工具把笔记写回state.notes前端侧边栏随之重渲染而只读版中没有任何后端工具会变更状态这是两者的根本区别。换句话说只读模式回答的是Agent 如何获得对当前 UI 状态的感知能力而不涉及Agent 如何驱动 UI 变更。前端实现发布状态与订阅更新挂载 Agent 并订阅状态变化页面通过useAgent钩子拿到 Agent 句柄并订阅状态与运行状态两类更新const { agent } useAgent({ agentId: shared-state-read, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], });这里的UseAgentUpdate枚举定义于 packages/react-core/src/v2/hooks/use-agent.tsx包含三个成员枚举值含义OnMessagesChanged消息列表变化新增/更新消息OnStateChangedAgent 状态agent.state变化触发重渲染OnRunStatusChanged运行状态运行中/完成变化OnStateChanged是只读场景的关键——当 Agent 端对状态有写入时本演示中虽无写入但订阅保证 UI 始终与状态一致组件能立即重新渲染。若状态更新频繁useAgent还支持throttleMs节流参数以降低重渲染频率见 use-agent.tsx 的注释说明。写入状态agent.setState首次挂载时先播种初始状态保证 Agent 在第一轮对话就有内容可读useEffect(() { if (!(agent.state as RecipeAgentState | undefined)?.recipe) { agent.setState({ recipe: INITIAL_RECIPE } satisfies RecipeAgentState); } }, []);此后每一次表单编辑都直接写回状态形成一个纯受控组件pure controlled component——编辑即写入下一次渲染自然反映最新值const handleChange (next: RecipeData) { agent.setState({ recipe: next } satisfies RecipeAgentState); };从 packages/react-core/src/v2/hooks/tests/use-agent.e2e.test.tsx 的端到端测试可见setState写入的状态会在随后调用runAgent时完整传递给 Agent 运行这是UI 状态 → Agent 上下文链路在框架层的直接证据。发起对话runAgent 与建议问题当用户点击 Improve with AI 按钮时页面手动插入一条用户消息并调用runAgent触发一次 Agent 运行const handleImprove () { if (agent.isRunning) return; // 运行中禁止重复触发 agent.addMessage({ id: crypto.randomUUID(), role: user, content: Improve the recipe, }); void copilotkit.runAgent({ agent }).catch((err) console.error([shared-state-read] runAgent failed, err), ); };同时useConfigureSuggestions在侧边栏提供三个起步建议Create Italian recipe、Make it healthier、Suggest variations让用户快速体验 Agent 基于当前食谱状态给出定制化建议的能力。类型化的状态契约前后端共享同一份 Schema共享状态不是无结构的 JSON——它由一份类型化 SchemaAgentState约束前端与后端共用同一结构。演示中的状态契约定义在 types.tsexport interface RecipeData { title: string; skill_level: SkillLevel; // Beginner | Intermediate | Advanced cooking_time: CookingTime; // 5 min | 15 min | 30 min | 45 min | 60 min special_preferences: string[]; // 高蛋白 / 低碳水 / 辣 / 预算友好 / 一锅 / 素食 / 纯素 ingredients: Ingredient[]; // { icon, name, amount } instructions: string[]; // 步骤文本数组 } export interface RecipeAgentState { recipe: RecipeData; // Agent 可见的顶层状态切片 } export const INITIAL_RECIPE: RecipeData { title: Make Your Recipe, skill_level: SkillLevel.INTERMEDIATE, cooking_time: CookingTime.FortyFiveMin, special_preferences: [], ingredients: [ { icon: , name: Carrots, amount: 3 large, grated }, { icon: , name: All-Purpose Flour, amount: 2 cups }, ], instructions: [Preheat oven to 350°F (175°C)], };类型化 Schema 的价值在于状态键名、枚举取值、嵌套结构对前端 UI、Agent 提示词与后端工具是同一份契约避免前后端各自维护一份松散结构导致的状态漂移。后端视角Agent 工具如何读取 runtime.state演示文档指出Agent 的工具通过runtime.state查询当前应用数据。在claude-sdk-typescript这个集成中后端的共享状态读取体现在两条路径上只读版本演示后端是中性默认 Agent无自定义工具前端每轮随RunAgentInput传入stateAgent 直接读取其中的recipe读写版对照后端在/shared-state-read-write路由中显式读取input.state.preferences再经buildSharedStateReadWriteSystemPrompt(prefs)把它拼进系统提示词见 src/agent_server.ts。读写版的路由实现展示了读取 incoming state → 注入上下文 → 携带状态跑 Agent 循环的完整形态const input req.body as RunAgentInput; const incomingState ((input as any).state as Recordstring, unknown | undefined) ?? {}; const prefs coercePreferences(incomingState.preferences); const notes Array.isArray(incomingState.notes) ? (incomingState.notes as unknown[]).filter( (n): n is string typeof n string, ) : []; await runAgenticLoop(req, res, { systemPrompt: buildSharedStateReadWriteSystemPrompt(prefs), toolSchemas: [SET_NOTES_TOOL_SCHEMA] as Anthropic.Tool[], initialState: { preferences: prefs, notes }, });这意味着Agent 读取 UI 状态的底层机制是前端随每次运行请求携带state负载后端将其解析为初始上下文Agent 在每一轮工具调用中都能访问。这与演示文档中无需前端把状态作为上下文发送的说法互为印证——状态是随请求结构化传递的而不是被用户或开发者手动塞进消息文本。此外src/app/api/copilotkit/route.ts 的注释还强调了一个工程细节shared-state-read-write这类后端拥有工具的演示不能走根路由的透传pass-through否则 Agent 的工具调用会被转发给前端前端并未注册该工具导致多轮工具循环卡死。这也是把该 Agent 单独指向后端专用端点的原因。如何运行与验证该演示的 QA 清单与端到端测试提供了完整的功能验收路径QA 清单qa/shared-state-read.md 从三个层面验收基础功能页面加载、侧边栏默认展开、发送消息后 Agent 正常回复特性检查默认食谱Make Your Recipe、45 min、Intermediate、胡萝卜与面粉、三个起步建议、表单的增删改交互核心验证修改食谱后询问 What recipe am I making?确认 Agent 的回答引用了当前食谱状态——这正是Agent 读取前端状态的最终验收标准。端到端测试tests/e2e/shared-state-read.spec.ts 用 Playwright 自动化覆盖了上述流程加载断言recipe-card、ingredients-container、instructions-container可见、建议按钮渲染、点击 Add Ingredient 后行数 1、以及发送 What recipe am I making? 后断言助手消息出现。从仓库结构看集成后的整体运行方式为启动claude-sdk-typescript集成含 Next.js 前端与 Agent 后端服务在浏览器访问/demos/shared-state-read即可在侧边栏向 AI 助手提问观察其基于当前表单状态作答。所有关键接线页面、组件、路由、Agent 服务都集中在 src/app/demos/shared-state-read 与 src/agent_server.ts 中可作为实现自有只读共享状态功能的最小参考实现。总结只读共享状态的适用边界shared-state-read演示展示了 CopilotKit 共享状态能力的读半边前端持有真相状态由agent.setState写入表单与 Agent 共享同一份数据类型化契约RecipeAgentState这类 Typed Schema 保证前后端对状态结构认知一致零上下文注入Agent 通过每轮的runtime.state/input.state直接读取无需开发者手工拼接上下文文本单向性只读模式没有后端写入工具状态不会被 Agent 反向修改适合Agent 感知 UI而UI 保持权威的场景。若需要 Agent 反过来驱动 UI例如让 Agent 通过工具把笔记、文档写回状态并实时刷新界面则属于shared-state-read-write演示的双向模式。两者结合即可覆盖 CopilotKit 共享状态从读到读写的完整能力矩阵。【免费下载链接】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），仅供参考
尧图网站开发 