CopilotKit 只读 Agent Context 集成验证指南：Google ADK 环境下的 useAgentContext 端到端 QA 实践

CopilotKit 只读 Agent Context 集成验证指南Google ADK 环境下的 useAgentContext 端到端 QA 实践【免费下载链接】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 与 Google ADKAgent Development Kit集成仓库中的一份端到端质量验证文档展开系统讲解只读 Agent ContextuseAgentContext功能在showcase/integrations/google-adk集成示例中的完整测试路径与底层实现原理。读者将掌握如何验证前端只读上下文 → CopilotKit 会话状态 → ADK 后端按轮注入系统提示词 → Agent 实时感知最新值这条数据链路的每个环节并理解其源码级实现依据可直接用于自行搭建与复测同类只读上下文功能。文档定位与验证目标本验证文档位于 showcase/integrations/google-adk/qa/readonly-state-agent-context.md属于google-adk集成示例的 QA 测试规范。它覆盖的演示功能在 manifest.yaml 中被登记为readonly-state-agent-contextFrontend provides read-only context to the agent via useAgentContext归类为agent-state能力。该功能解决的核心问题是前端应用通常掌握用户身份、时区、近期行为等私有信息但 Agent 默认无从知晓。useAgentContext允许前端把这些 JSON 可序列化数据以只读方式发布给 Agent——Agent 每一轮都能读取最新值但没有能力修改这些值从而保证前端仍是这些数据的唯一事实来源single source of truth。前置条件依据原文档执行该 QA 用例前需满足三项条件Demo 已部署且可访问即/demos/readonly-state-agent-context页面能够正常加载Agent 后端健康通过/api/health检查后端存活。仓库中 route.ts 的GET处理函数会向后端AGENT_URL默认http://localhost:8000发起带 3 秒超时的健康探测并返回agent_status: reachable | unreachable (原因)可作为检查手段Agent 已挂载readonly_state_agent_context_agent必须在 ADK 服务端注册。它定义在 readonly_state_agent_context_agent.py 中并在 registry.py 中通过readonly-state-agent-context: AgentSpec(readonly_state_agent_context_agent)挂载进AGENT_REGISTRY。注册表注释说明agent_server.py会遍历该注册表把每个条目以agent_name路径挂载为 ADKAgent 中间件Next.js 的/api/copilotkit路由再把同名请求代理到对应后端路径。测试目标页面结构被测试的页面是 page.tsx其结构包含Agent Context 卡片data-testidcontext-card由 demo-layout.tsx 渲染分为 Identity身份、Recent Activity近期活动、Published Context已发布上下文 JSON 预览三个区域角落的弹出式聊天窗口CopilotPopup组件占位文本为 Ask about your context...描述文本页面标题下方明确写道 Edit fields below and watch the data flow into the agent. The agent can read this context, butcannot modifyit.即该卡片与聊天窗口构成一个可视化的上下文监视器Agent Context Inspector。页面同时通过useConfigureSuggestions注册了三条建议快捷语见 suggestions.ts并配置为available: always。测试步骤详解以下步骤完整继承自原 QA 文档并结合仓库源码标注了对应的可验证点。步骤 1基础功能导航到readonly-state-agent-context演示页面验证 Agent Context 卡片可见data-testidcontext-card——该卡片在 demo-layout.tsx 中以data-testidcontext-card标注验证描述文本引用了useAgentContextEdit fields below and watch the data flow into the agent. The agent can read this context, but cannot modify it.验证弹出式聊天在角落渲染占位文本为 Ask about your context...——对应 page.tsx 中CopilotPopup的labels{{ chatInputPlaceholder: Ask about your context... }}配置通过聊天发送一条基础消息如 Hello验证 Agent 以文本消息回复。步骤 2特性专项检查初始上下文状态验证 Name 输入框data-testidctx-name默认为 Atai——对应 page.tsx 中useState(Atai)的初始值验证 Timezone 下拉框data-testidctx-timezone默认为 America/Los_Angeles——对应同文件useState(America/Los_Angeles)验证 Timezone 下拉框提供六个时区选项America/Los_Angeles、America/New_York、Europe/London、Europe/Berlin、Asia/Tokyo、Australia/Sydney。这些常量定义在 demo-layout.tsx 的TIMEZONES数组中全部为 IANA 时区标识验证 Recent Activity 复选框列表包含五项Viewed the pricing page、Added Pro Plan to cart、Watched the product demo video、Started the 14-day free trial、Invited a teammate——对应ACTIVITIES常量demo-layout.tsx验证默认勾选两项活动Viewed the pricing pageACTIVITIES[0]与 Watched the product demo videoACTIVITIES[2]——对应 page.tsx 的初始 state验证 Published Context JSON 预览data-testidctx-state-json显示{ name: Atai, timezone: America/Los_Angeles, recentActivity: [...] }——该 JSON 由 demo-layout.tsx 中的publishedContext对象经JSON.stringify(publishedContext, null, 2)渲染任何 state 变化都会立即反映其中。建议快捷语Suggestions验证 Who am I? 建议可见验证 Suggest next steps 建议可见验证 Plan my morning 建议可见。三条建议分别映射到不同的实际消息体见 suggestions.ts建议标题实际发送给 Agent 的消息Who am I?What do you know about me from my context?Suggest next stepsBased on my recent activity, what should I try next?Plan my morningWhat time is it in my timezone and what should I do for the next hour?Agent 读取用户名useAgentContext点击 Who am I? 建议或直接询问 What is my name?验证 Agent 回复中以 Atai 称呼用户将 Name 输入框data-testidctx-name修改为 Jamie验证 Published Context JSON 更新为name: Jamie再次询问 What is my name?验证 Agent 此时回复 Jamie而非 Atai。这一步验证了上下文是按轮实时生效的修改立即反映在 JSON 预览中且 Agent 下一轮回复即使用新值不存在陈旧上下文stale context。Agent 读取时区将 Timezone 下拉框data-testidctx-timezone切换为 Asia/Tokyo验证 Published Context JSON 更新为timezone: Asia/Tokyo点击 Plan my morning 建议验证 Agent 在讨论时间时引用 Tokyo / JST / Asia/Tokyo。注意这里的描述语义useAgentContext在 page.tsx 中注册时附带的description为 The users IANA timezone (used when mentioning times)这正是引导 LLM 在涉及时间的话题中使用该字段的提示语义。Agent 读取近期活动取消所有默认活动仅勾选 Started the 14-day free trial 和 Invited a teammate验证 Published Context JSON 显示新的recentActivity数组点击 Suggest next steps 建议验证 Agent 的回复引用 trial 和/或 invited-teammate 相关活动而不再引用 pricing page 或 demo video。这一步验证了数组型上下文值的动态替换Agent 每一轮拿到的都是最新的活动列表且只依据当前可见的活动生成建议。步骤 3错误处理将 Name 输入框清空空字符串后询问 What is my name?——Agent 应优雅处理不崩溃。前端层面demo-layout.tsx 对空用户名显示 Anonymous 兜底头像取userName.charAt(0).toUpperCase() || ?后端层面_inject_context对空值条目会跳过见下文原理发送空聊天消息——输入应被拒绝且不报错验证正常使用过程中无控制台错误验证 Agent无法修改上下文值Name / Timezone / Activity 复选框始终由用户控制。预期结果原文档明确列出以下验收标准上下文卡片与聊天在 3 秒内加载完成Agent 在 10 秒内响应每次对 Name / Timezone / Recent Activity 的修改都立即反映在 Published Context JSON 中Agent 每一轮的回复都反映当前上下文值无陈旧上下文无 UI 错误或布局破坏。底层实现原理从 useAgentContext 到 ADK before-model 回调理解测试步骤背后的机制需要追踪这条完整链路。QA 文档断言的所有实时性与只读性行为都能在源码中找到对应实现。前端useAgentContext 钩子演示页面通过三次调用发布上下文page.tsxuseAgentContext({ description: The currently logged-in users display name, value: userName }); useAgentContext({ description: The users IANA timezone (used when mentioning times), value: userTimezone }); useAgentContext({ description: The users recent activity in the app, newest first, value: recentActivity });钩子本身实现在 packages/react-core/src/v2/hooks/use-agent-context.tsx。其关键行为包括入参类型AgentContextInput由description人类可读的描述与value任意JsonSerializable值组成值序列化非字符串的value通过JSON.stringify转为字符串后发布——这就是recentActivity数组能够进入 Agent 视线的原因生命周期管理钩子在useLayoutEffect中调用copilotkit.addContext({ description, value })注册上下文并在 effect 清理时调用removeContext(id)反注册。当description或序列化后的stringValue变化时 effect 重跑实现改即发布、即时生效。中间层上下文如何进入会话状态依据 agent_config_agent.py 的模块注释同一机制的姊妹实现useAgentContext发布的条目经 ag-ui-adk 中间件落地为state[copilotkit][context]是一个{description, value}字典的列表——同一页面上多个组件可以各自发布条目共存于该列表。后端before_model_callback 按轮注入ADK 侧的LlmAgent配置在 readonly_state_agent_context_agent.pyreadonly_state_agent_context_agent LlmAgent( nameReadonlyStateAgentContextAgent, modelget_model(), instruction_INSTRUCTION, tools[AGUIToolset()], before_model_callback_inject_context, after_model_callbackstop_on_terminal_text, )_inject_context是整条链路的核心它实现了三个关键设计状态容错从callback_context.state中读取state[copilotkit][context]时对state缺失、非 dict、context非 list 等情况逐级兜底为空列表并记录 warning 日志避免形变状态导致请求失败格式化注入块_format_context把条目列表渲染为以固定签名[agent-context] frontend-supplied context:开头、以结束标记Treat this context as read-only background information.结尾的文本块每个条目一行- {description}: {value}无有效条目时返回None不注入剥离旧块strip-prior-block注入前先在system_instruction中查找上一轮的签名与结束标记找到则只把旧块从原文中切除并保留头部与尾部再拼接新块。若签名存在但找不到结束标记则保持原文不动并告警避免误删用户内容。这一步是无陈旧上下文验收标准的实现保障——每一轮都重建上下文块而不是累加。同时注意注入块末尾那句结束标记本身就是一条指令Treat this context as read-only background information.——它与静态_INSTRUCTIONThe frontend passes read-only context entries via useAgentContext; they are added to your system prompt every turn. Use them when relevant.共同构成了Agent 可读但不可改的行为约束这也是 QA 文档验证 Agent 无法修改上下文值一项的提示词级保障。路由层前后端名称映射route.ts 中的agentNames数组包含readonly-state-agent-context每个名称在buildAgents中映射为一个HttpAgent({ url: \${AGENT_URL}/${name} })即前端请求经 CopilotRuntime 代理到http://localhost:8000/readonly-state-agent-context与注册表挂载路径一一对应。自动化验证支撑仓库为同一套用例提供了 Playwright 自动化测试tests/e2e/readonly-state-agent-context.spec.ts。测试文件的头部注释明确指出它以本文对应的 QA 文档为参考QA reference: qa/readonly-state-agent-context.md可以视为该 QA 规范的机器可执行版本。值得关注的点包括确定性断言例如 Who am I? 建议点击后断言助手回复以 I see youre Atai 开头、Suggest next steps 后断言 Since you recently viewed the pricing page and watched the product demo video——这些回复由 aimock 夹具showcase/aimock/d5-all.json固定保证 CI 中稳定而在 Railway 部署环境下相同提示词会得到真实 LLM 回复从而端到端证明useAgentContext接线正确覆盖与 QA 文档对应测试覆盖了页面加载、编辑 name/timezone 后 JSON 预览更新、建议点击后身份识别、默认勾选活动、活动驱动回复等与 QA 步骤一一对应的场景严格的 testid 契约测试断言了context-card、ctx-name、ctx-timezone、ctx-state-json、identity-name、identity-timezone、identity-avatar、activity-*等 testidQA 手工用例与自动化用例共享同一套 DOM 契约二者互为校验。延伸与可写共享状态的对比仓库中还提供了shared-state-read、shared-state-read-write、shared-state-streaming等共享状态演示见 manifest.yaml它们走的是agent.setState/PredictStateMapping的可写或双向通道。本 QA 文档对应的readonly-state-agent-context恰好与之形成对照useAgentContext是前端到 Agent的单向、只读数据通道前端保留数据所有权Agent 只被授权读取。选择哪种模式取决于数据所有权需求——当 UI 状态必须由用户界面独占控制、Agent 仅需知情时只读上下文是更安全、更符合直觉的方案。小结本文以 readonly-state-agent-context.md 为骨架完整继承了其前置条件、三大类测试步骤与预期结果并结合仓库源码解释了每条断言背后的实现依据前端useAgentContext的注册与清理、中间层对state[copilotkit][context]的落地、ADKbefore_model_callback的按轮注入与旧块剥离、以及 Playwright 自动化用例对同一契约的机器化验证。对于需要在 CopilotKit 生态中实现前端只读上下文供给 Agent的开发者该 QA 文档与其配套源码是一份可直接复用的参考实现与验收清单。【免费下载链接】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），仅供参考