CopilotKit 共享状态双向读写实战基于 Claude Agent SDK (TypeScript) 实现 UI 与 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 集成 Claude Agent SDK (TypeScript) 的 Shared State (Read Write) 演示功能系统讲解UI 写入状态、Agent 读取并回写状态这一双向协同机制的完整链路。你将从页面加载、表单写入、工具回写、状态清空、跨轮持久化到异常处理的端到端验证中获得可直接复用的测试清单并通过 agent_server.ts、shared-state-read-write-prompt.ts 与前端页面源码理解agent.setState、useAgent、STATE_SNAPSHOT事件在真实调用链中的工作方式。功能定位一份双向共享的 Agent 状态该 Demo路由为/demos/shared-state-read-write演示的共享状态包含两个方向不同的字段preferencesUI 写入 → Agent 读取用户在侧边栏填写的偏好姓名、语气、语言、兴趣由 UI 通过agent.setState()写入共享状态。后端每一轮都会把这些偏好注入 Claude 的系统提示词使模型应答实时体现这些设置。notesAgent 写入 → UI 读取Agent 通过set_notes工具把观察到的用户信息如偏好早间会议不吃乳制品写回共享状态后端通过 AG-UI 的STATE_SNAPSHOT事件推送UI 无需刷新页面即可实时更新Agent 笔记卡片。这一字段契约在前端 page.tsx 中以RWAgentState接口明确定义interface RWAgentState { preferences: Preferences; // UI 通过 agent.setState() 写入 notes: string[]; // Agent 通过 set_notes 工具写入 }前置条件按仓库中的 QA 文档 shared-state-read-write.md 要求验证前需要确认以下条件全部满足条件说明Demo 已部署并可达页面可通过/demos/shared-state-read-write访问Agent 后端健康GET /api/copilotkit-shared-state-read-write返回正常ANTHROPIC_API_KEY已配置环境变量必须设置在 Agent 后端进程上由 agent_server.ts 中的new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })读取端到端验证步骤1. 页面加载与初始状态检查导航到/demos/shared-state-read-write后依次核对以下初始状态左侧Your preferences卡片渲染完成Name 为空、tone 为casual、language 为English、无已选兴趣右侧Agent notes卡片显示 No notes yet.实际组件文案为 the agent will make observations about you and note them here!见 notes-card.tsx右侧聊天面板加载占位符为 Chat with the agent...配置在 demo-layout.tsx 的CopilotSidebar的chatInputPlaceholder三个建议词条可见Greet me、Remember something、Plan a weekend控制台无报错。初始偏好由前端的INITIAL_PREFERENCES常量定义{ name: , tone: casual, language: English, interests: [] }。首次挂载时useEffect会通过agent.setState({ preferences: INITIAL_PREFERENCES, notes: [] })把初始状态播种进 Agent 状态保证第一轮对话时 Agent 也能读到完整结构page.tsx。2. UI → Agent 写入偏好实时驱动模型这是写方向的核心验证将 Name 设置为Alex将 Tone 切换为playful勾选兴趣Cooking和Travel观察Shared state预览区卡片底部pref-state-json区域的 JSON 实时预览随之更新为新值点击 Greet me 建议或发送 Hi, who am I?验证 Agent 以 Alex 称呼用户语气为俏皮风格感叹号、口语化表达验证 Agent不会使用正式语体。实现原理每个表单编辑事件都会冒泡到父页面的handlePreferencesChange直接调用agent.setState({ preferences: next, notes: latestNotesRef.current })其中latestNotesRef用于保留 Agent 已写入的 notes避免 UI 写入偏好时把 Agent 写的内容覆盖掉page.tsx。下一轮请求时该对象随 AG-UI 的RunAgentInput.state转发到后端。后端路由在 agent_server.ts 中读取input.state.preferences并调用coercePreferences做类型清洗随后用buildSharedStateReadWriteSystemPrompt(prefs)把偏好拼进系统提示词The user has shared these preferences with you: - Name: Alex - Preferred tone: playful - Interests: Cooking, Travel Tailor every response to these preferences. Address the user by name when appropriate.这就是偏好写入立即影响模型行为的实现基础见 shared-state-read-write-prompt.ts 中的buildPreferencesPreamble。3. Agent → UI 读取set_notes 工具实时回写状态验证 Agent 向 UI 写回状态发送 Remember that I prefer morning meetings and that I dont eat dairy.约 10 秒内Agent notes卡片从空状态变为 13 条短项目列表包含早间会议与不吃乳制品两条笔记笔记出现过程中无需刷新页面依赖实时的STATE_SNAPSHOT再发送 Also, I work in Eastern Time.验证笔记卡片在原有条目基础之上新增时区笔记——即 Agent 传递的是完整列表而非仅新增项。实现原理set_notes工具由 shared-state-read-write-prompt.ts 中的SET_NOTES_TOOL_SCHEMA定义其描述明确要求Always pass the FULL notes list (existing new), not a diff工具参数为{ notes: string[] }。后端处理器在 agent_server.ts 中校验参数、过滤非字符串项并返回state: { ...state, notes }作为新的共享状态随后该状态以 AG-UISTATE_SNAPSHOT事件被发射给前端。前端通过useAgent({ agentId: shared-state-read-write, updates: [UseAgentUpdate.OnStateChanged] })订阅状态变更每当 Agent 变更状态如调用set_noteshook 触发、组件重渲染notes从agent.state.notes中解出并传给NotesCard实现实时刷新page.tsx。4. UI → Agent 写回清空笔记验证 UI 对 Agent 写内容的回写能力点击笔记卡片上的Clear按钮笔记卡片恢复为 No notes yet.偏好设置保持不变发送 What do you remember about me?验证 Agent 仍能引用偏好姓名、语气但不提任何笔记。实现原理handleClearNotes调用agent.setState({ preferences, notes: [] })——注意这里把当前偏好原样保留、仅清空 notes实现双向字段互不干扰page.tsx。Clear 按钮由 notes-card.tsx 渲染仅在notes.length 0时出现。5. 跨轮持久化验证偏好在整个会话中持续生效清空笔记后将 Tone 改为formal、Language 改为Spanish发送 Saludos.验证 Agent 用西班牙语、正式语体回复再发一条后续消息验证 Agent 仍遵守相同偏好。这验证了每轮请求都会把最新偏好注入系统提示词见上文路由处理且状态在多次往返中持续保留。6. 错误处理发送空消息应被优雅处理输入被忽略或 no-op不产生崩溃若后端缺少ANTHROPIC_API_KEY聊天界面应通过 AG-UI 的 run-error 路径显示错误消息。值得注意的是page.tsx 会在首次挂载时播种preferences与notes因此即使 Agent 端未收到用户编辑模型也能在第一轮就读取到结构化的初始状态。预期结果汇总行为机制预期偏好编辑传播agent.setState每次键盘输入 / 开关切换即生效Agent 系统提示词每轮注入最新偏好应答实时体现姓名、语气、语言、兴趣set_notes工具写入STATE_SNAPSHOT事件工具调用结束后约 1 秒内落入 UI页面刷新无整个 Demo 过程无整页刷新控制台无快乐路径happy path零报错后端调用链与 AG-UI 事件机制整个 Demo 的运行链路为前端表单 (PreferencesCard) → agent.setState({ preferences, notes }) → AG-UI RunAgentInput.state → Next.js runtime (route.ts 代理) → Express agent_server /shared-state-read-write → coercePreferences buildSharedStateReadWriteSystemPrompt → runAgenticLoop调用 Claude → set_notes 工具处理器返回新 state → STATE_SNAPSHOT 事件 → useAgent({ updates: [OnStateChanged] }) 触发重渲染 → NotesCard / PreferencesCard 更新前端运行时路由在 route.ts 中创建CopilotRuntime通过createClaudeHttpAgent把/shared-state-read-write端点包装为 AG-UI 抽象 Agent模式为single-route后端每轮读取input.state.preferences与input.state.notes交给runAgenticLoop处理并把SET_NOTES_TOOL_SCHEMA注册进工具列表agent_server.tscoercePreferences对传入的偏好做防御性清洗只接受字符串name、枚举集合内的toneformal/casual/playful、字符串language与字符串数组interests其余字段静默丢弃防止异常前端污染提示词shared-state-read-write-prompt.ts。自动化测试佐证仓库内提供了配套的 Playwright 端到端测试 shared-state-read-write.spec.ts覆盖两个侧边栏卡片Your preferences / Agent Scratch pad均成功挂载三个建议词条渲染Greet me 返回共享状态感知的问候断言包含shared-state co-pilot并反向断言不出现通用 showcase 回复Plan a weekend 返回基于兴趣的计划断言包含interests panel并反向断言不出现通用内容营销模板。其中还记录了一个历史回归 Bug建议词条曾因匹配到feature-parity.json中较短的hi/plan通用 fixture 而返回错误回复修复方式是为 shared-state 场景补充更长、更优先匹配的 fixture。这些测试与 QA 文档共同构成对该功能的正向 负向双重保障可作为你复刻该功能时的验收参照。小结CopilotKit 的 Shared State (Read Write) 演示展示了双向状态协同的完整范式UI 通过agent.setState写入、Agent 通过工具函数回写、AG-UISTATE_SNAPSHOT事件驱动前端实时刷新而状态契约preferencesnotes由前端、后端与系统提示词三处共享形成一套可测试、可扩展、跨轮持久的 Agent 状态管理方案。无论你是要复现该 Demo、为其补充自动化测试还是把同样的模式迁移到自己的 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），仅供参考