 共享状态只读模式 QA 测试指南：让 Agent 实时读取前端表单状态)
CopilotKit LangGraph (FastAPI) 共享状态只读模式 QA 测试指南让 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 与 LangGraph (FastAPI) 集成仓库中的shared-state-readShared State: Reading演示场景给出从环境准备、逐项功能验证到错误处理与验收标准的完整 QA 测试流程。读完本文你将掌握如何在前端发布状态、Agent 只读不写的架构下系统地验证 Agent 能否基于 UI 中的实时数据回答问题以及如何用仓库中的源码与 Playwright 测试佐证每个测试断言。测试对象与架构背景shared-state-read是一个配方编辑器 AI 助手演示页面左侧是一个受控的表单Recipe Card右侧是默认展开的CopilotSidebar标题为 AI Recipe Assistant。用户编辑表单、点击建议或 Improve with AI 按钮后Agent 通过对话参与配方的生成与优化。该场景的核心架构是单向共享状态只读前端是单一数据源页面通过agent.setState({ recipe: ... })把整个配方对象发布进 Agent 状态后续每次编辑都直接流向agent.setState下一次渲染立即反映最新值Agent 只读不写后端没有用于修改配方的工具Agent 只负责在每一轮对话中读取这份状态agent.state.recipe并基于它回答因此后端无法反向污染表单数据状态有类型约束前端与后端共享同一份类型化状态结构RecipeAgentState避免运行期字段错位。上述机制对应的实现分别在 page.tsx前端状态发布与订阅、types.ts状态与数据结构定义以及 manifest.yaml 的shared-state-readdemo 条目中。前置条件开始执行 QA 前请确认以下两项Demo 已部署且可访问/demos/shared-state-read页面能正常打开Agent 后端健康请求/api/health或对应健康检查路由返回正常状态LangGraph 后端可达。后端连通性可以从 route.ts 中看到GET请求会检查${AGENT_URL}/ok默认http://localhost:8123可通过环境变量AGENT_URL覆盖并在 3 秒超时内返回agent_status: reachable / unreachable这是定位前端正常但 Agent 无响应类问题时的首选入口。一、基础功能验证页面与表单加载导航到 shared-state-read 演示页面验证配方卡片表单成功加载data-testidrecipe-card验证CopilotSidebar默认展开且标题为 AI Recipe Assistant通过侧边栏发送一条消息验证 Agent 能正常回复。这里的data-testidrecipe-card定义在 recipe-card.tsx侧边栏默认展开与标题设置来自 page.tsx 中CopilotSidebar defaultOpen labels{{ modalHeaderTitle: AI Recipe Assistant }} /的配置。Agent 路由注册后端路由中shared-state-read走的是中性默认 Agent通道在 route.ts 的agentNames列表里注册并通过createAgent()映射到sample_agent图。而sample_agent在 langgraph.json 中指向 agent.py 里由create_agent构建的图它挂载了CopilotKitMiddleware使用AgentState作为状态 schema并带有 7 个后端工具。QA 阶段若消息无法得到回复应优先检查该路由的注册日志Registered N agent names与GET /api/copilotkit返回的agent_status。二、特性专项检查1. 初始配方状态Initial Recipe State验证配方标题输入框初始值为 Make Your Recipe验证烹饪时间下拉框默认选中 45 min验证技能等级下拉框默认选中 Intermediate验证默认食材正确显示Carrots3 large, grated带 胡萝卜 emojiAll-Purpose Flour2 cups带 小麦 emoji验证默认步骤正确显示Preheat oven to 350 F。以上默认值全部来自 types.ts 中导出的INITIAL_RECIPE常量。QA 时可以对照源码逐字段断言尤其注意cooking_time默认值是通过cookingTimeValues索引映射到下拉框选项的见 recipe-card.tsx该映射逻辑正是45 min正确显示的保证。2. 建议Suggestions验证 Create Italian recipe 建议可见验证 Make it healthier 建议可见验证 Suggest variations 建议可见。三条建议通过useConfigureSuggestions注册available: alwayspage.tsx点击建议会直接把对应的message作为用户消息发送给 Agent。3. 配方编辑本地状态Local State编辑配方标题验证输入即时更新修改技能等级下拉框验证选项即时更新修改烹饪时间下拉框验证选项即时更新切换饮食偏好复选按钮如 Vegetarian验证其变为选中态点击 Add Ingredientdata-testidadd-ingredient-button验证新增一行空白食材行编辑食材的名称与用量点击 x 按钮移除某个食材点击 Add Step 验证新增一条步骤输入行编辑步骤文本并验证保存生效点击 x 按钮移除某个步骤。表单是一个纯受控组件RecipeCard接收recipe作为 props任何改动都通过update(partial)→onChange(next)合并出新对象再经handleChange写入agent.setState({ recipe: next })page.tsx。因此本地编辑本质上是写进 Agent 共享状态而不是游离于状态之外的本地临时数据——这正是下一节 AI 更新能感知编辑结果的前提。QA 时可结合 recipe-card.tsx 中updateIngredient、updateInstruction的实现来设计边界用例如连续快速编辑、清空后恢复。4. AI 驱动的配方更新useAgent 结合共享状态点击 Create Italian recipe 建议验证 Agent 更新了配方标题、食材与步骤验证被修改的区块出现 ping高亮指示器验证 Improve with AI 按钮data-testidimprove-button在加载期间文案变为 Please Wait...点击 Improve with AI验证配方被增强。这里涉及两条消息路径点击建议消息进入对话Agent 读取agent.state.recipe后给出新配方前端通过useAgent订阅OnStateChanged与OnRunStatusChangedpage.tsx任何状态变化都会触发重渲染。点击 Improve with AIhandleImprove先通过agent.addMessage注入一条用户消息 Improve the recipe再调用copilotkit.runAgent({ agent })显式触发一次 Agent 运行page.tsx并且运行期间isRunning为真按钮被禁用并显示 Spinner Please Wait...recipe-card.tsx。由于本场景后端不写状态所谓AI 更新配方是 Agent 在回复中给出新的配方内容后由前端将这些内容重新写回agent.setState或由用户在表单中采纳这是与 read-write 模式的关键差异。5. Agent 读取前端状态Agent Reads Frontend State编辑配方如修改标题、新增食材向 Agent 提问 What recipe am I making?验证 Agent 的回复内容引用了当前配方状态。这是整个只读模式最有代表性的验收点Agent 无需前端把上下文塞进消息而是直接读取共享的agent.state.recipe就能准确回答当前在做什么菜。对应的自动化断言已固化在 tests/e2e/shared-state-read.spec.ts 中向输入框填入 What recipe am I making? 并回车后断言助手消息data-testidcopilot-assistant-message在 30 秒内出现。QA 时可以在此基础上进一步断言回复文本包含刚编辑过的标题或食材名以验证引用的是当前状态而非缓存的旧数据。三、错误处理发送空消息验证能被优雅处理不崩溃、不无限 loading正常使用过程中无 console 报错验证 Improve with AI 按钮在加载期间处于禁用态。注意按钮禁用态已在 recipe-card 中由disabled{isLoading}保证recipe-card.tsx同时handleImprove内部还有if (agent.isRunning) return;的防御性检查page.tsx防止重复触发并发运行。QA 时应重点验证快速连点与运行中点建议这两种竞态场景均不会产生重复请求或状态错乱。四、预期结果验收标准验收项标准加载性能配方卡片与侧边栏在 3 秒内加载完成响应性能Agent 在 10 秒内完成回复状态一致性配方状态在 UI 与 Agent 之间双向同步UI → Agent 发布Agent 读取后回显到对话变更可视化ping 指示器正确高亮被 Agent 修改过的区块UI 稳定性无 UI 错误、无布局破损需要说明的是双向同步在此场景中是指UI 写入 → Agent 读取 → Agent 回复反映该状态的完整闭环与 write 模式下Agent 主动回写状态的含义不同两者的对比可以参考同目录的 shared-state-read-write.mdUI 写偏好、Agent 用工具写笔记与 shared-state-streaming.mdAgent 逐 token 向 UI 流式推送状态增量。五、源码级测试与复现路径端到端测试tests/e2e/shared-state-read.spec.ts 覆盖了四条核心链路——配方卡片与侧边栏加载、三条建议渲染、 Add Ingredient 追加行、侧边栏消息得到助手回复可作为手工 QA 的自动化兜底。前端实现page.tsx 与 recipe-card.tsx 提供了所有data-testid钩子recipe-card、add-ingredient-button、ingredients-container、ingredient-card、instructions-container、improve-buttonQA 脚本可以直接复用。状态与数据契约types.ts 中的SkillLevel、CookingTime、SpecialPreferences、Ingredient、RecipeData、RecipeAgentState与INITIAL_RECIPE是全部断言的事实基准。后端接线route.ts 中shared-state-read → sample_agent的映射、langgraph.json 的图注册以及 agent.py 中挂载CopilotKitMiddleware的create_agent调用共同构成了前端状态能到达 Agent 上下文的运行时链路。结语Shared State只读模式适合所有Agent 需要感知当前 UI 状态但不应篡改业务数据的场景例如文档编辑器、表单填写、配置面板与任务清单。以本文的 QA 清单为骨架配合仓库中的源码与 Playwright 用例你可以在 30 分钟内完成对shared-state-read场景的完整验收并将同样的验证思路迁移到 shared-state-read-write 等相邻 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），仅供参考
