CopilotKit 与 Langroid 集成实战用 useAgentContext 实现只读 Agent 上下文Readonly State【免费下载链接】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 展示项目showcase中 Langroid 集成模块的只读 Agent 上下文功能展开讲解如何通过useAgentContext将前端 UI 状态用户身份、时区、最近活动等以单向、只读的方式发布给后端 Langroid Agent并详细拆解官方 QA 验证清单showcase/integrations/langroid/qa/readonly-state-agent-context.md中每一条测试步骤的预期行为与底层实现。读完本文你将掌握useAgentContext的调用方式、上下文数据的传输链路Next.js Runtime → AG-UI → Langroid Agent Server以及如何用 Playwright E2E 测试固化这类只读上下文行为。一、功能定位让 Agent知道但不能改的 UI 状态在 CopilotKit 的前端框架体系中Agent 有时需要了解用户当前在界面上看到了什么例如当前登录用户的显示名identity用户所在的 IANA 时区用于回答现在几点这类问题用户在应用内的最近活动记录用于推荐下一步操作。这些值属于纯输入inputAgent 只需要读取绝不应该被 LLM 通过工具调用反向修改。为此CopilotKit 提供了useAgentContext—— 一条单向的 UI → Agent 通道。官方文档showcase/shell-docs/src/content/docs/shared-state/agent-readonly.mdx对它的设计定位概括为props for the agent给 Agent 传的 props。与完整的共享状态shared stateAgent 可以调用工具把状态写回 UI不同useAgentContext发布的值在每一轮对话中都会通过运行时的上下文注入被 Agent 看到没有任何 setter也没有任何可写回的工具组件卸载时自动注销例如离开当前页面当前记录上下文随之消失。因此它天然适合用户身份、功能开关、当前选中的记录、滚动位置这类UI 拥有、Agent 只读的数据。二、核心 APIuseAgentContext 的调用方式与参数Langroid 集成模块的 demo 页面位于 showcase/integrations/langroid/src/app/demos/readonly-state-agent-context/page.tsx其核心调用如下useAgentContext({ 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, });每个useAgentContext调用只接受两个字段参数含义注意事项description一段简短的人类可读标签Agent 会与 value 一起看到官方文档强调它像参数 docstring 一样重要直接影响 LLM 理解该值的用途value要发布的实际值字符串、数组等值变化时React 重渲染自动刷新注册项组件卸载时自动移除从 demo 可以看到三处调用的value分别来自三个独立的useStateconst [userName, setUserName] useState(Atai); const [userTimezone, setUserTimezone] useState(America/Los_Angeles); const [recentActivity, setRecentActivity] useStatestring[]([ ACTIVITIES[0], // Viewed the pricing page ACTIVITIES[2], // Watched the product demo video ]);官方文档同时指出useAgentContext并不关心 value 来自哪里——可以是本地useState、React Context、Redux、查询缓存等任意来源唯一要求是值的标识足够稳定避免 React 渲染循环。在真实应用中这些值通常会来自 auth provider、路由 hook 或领域状态仓库。三、demo 界面Context 卡片与实时 JSON 预览demo 页面布局由 demo-layout.tsx 实现整个界面被称为 Agent Context Inspector包含三张卡片Identity 卡片展示 Name文本框与 Timezone下拉选择包含America/Los_Angeles、Asia/Tokyo等 6 个时区以及一个根据名字首字母和时区区域动态渲染的头像Recent Activity 卡片5 项可勾选的活动如 Viewed the pricing page、Started the 14-day free trial勾选状态决定该活动是否Visible to the agentPublished Context 卡片全宽度的 JSON 预览区实时展示真正广播给 Agent 的载荷{ name: Atai, timezone: America/Los_Angeles, recentActivity: [Viewed the pricing page, Watched the product demo video] }这个 JSON 预览是 QA 验证的核心观察点——所有字段编辑都会立即反映到该 JSON 中形成所见即 Agent 所得的可视化反馈闭环。demo 还在 suggestions.ts 中通过useConfigureSuggestions预置了三条与只读上下文强相关的建议提问Who am I? → What do you know about me from my context?Suggest next steps → Based on my recent activity, what should I try next?Plan my morning → What time is it in my timezone and what should I do for the next hour?这三条建议恰好覆盖了 QA 清单中要验证的 Agent 行为身份识别、活动推荐、时区感知。四、数据链路上下文如何从 UI 到达 Langroid Agent只读上下文并不直接拼进前端代码而是走一条完整的前后端链路由两部分组成4.1 前端运行时代理Next.js route.tsshowcase/integrations/langroid/src/app/api/copilotkit/route.ts 使用copilotkit/runtime/v2的CopilotRuntime与createCopilotRuntimeHandler创建单一路由mode: single-route并通过HttpAgent来自ag-ui/client将请求按AG-UI 协议代理到后端 Langroid Agent Server默认http://localhost:8000可用环境变量AGENT_URL覆盖const AGENT_URL process.env.AGENT_URL || http://localhost:8000; function createAgent(path /) { return new HttpAgent({ url: ${AGENT_URL}${path} }); }该 route 将包括readonly-state-agent-context在内的 30 余个 demo agent 名称统一注册到同一个后端统一 Agent 上代码注释明确说明Read-only agent context — frontend exposes useAgentContext; same agent。也就是说只读上下文完全由前端运行时注入后端 Agent 本身不需要任何专用工具。4.2 后端 Langroid Agent Serveragent_server.pyshowcase/integrations/langroid/src/agent_server.py 是一个 FastAPI 服务。由于 Langroid 没有原生的 AG-UI 适配器它实现了一个自定义 SSE 端点把 Langroid 的ChatAgent与 AG-UI 事件流相互转换。文件头注释明确指出The Next.js CopilotKit runtime proxies requests here via AG-UI protocol.从 agui_adapter.py 的代码可以看到app.post(/)的run_agent会把请求体强转为RunAgentInputRunAgentInput(**body)再进入 AG-UI 的 SSE 事件管道。前端运行时在每一轮将useAgentContext注册的条目注入消息历史后Agent 便能在该轮回答中感知到这些上下文值——这正是 QA 中Agent 能引用上下文的底层原因。4.3 页面接线demo 页面的外层通过CopilotKit runtimeUrl/api/copilotkit agentreadonly-state-agent-context绑定运行时与 Agent再挂载CopilotPopup占位提示为 Ask about your context...作为对话入口。整个结构是React 状态 → useAgentContext 注册 → CopilotKit runtime 注入 → AG-UI 代理 → Langroid 统一 Agent 读取。五、QA 验证清单逐条拆解默认值、操作与预期原 QA 文档showcase/integrations/langroid/qa/readonly-state-agent-context.md定义了 6 条人工验收步骤下面逐条给出其预期行为与源码依据。5.1 导航到 /demos/readonly-state-agent-context页面路由由src/app/demos/readonly-state-agent-context/page.tsx提供浏览器访问后应渲染出三张 Context 卡片与右下角的 Copilot 弹出式聊天窗。5.2 验证 context card 默认 Name 为 AtaiuseState(Atai)是 Name 的默认值Identity 卡片与 Published Context JSON 中的name: Atai应同时呈现。E2E 测试用page.getByTestId(identity-name)断言其文本为 Atai见下文测试章节。5.3 将 Name 改为 Jordan验证 published JSON 更新修改 Name 输入框会触发setUserNameuseAgentContext注册项随之刷新Published Context 的 JSON 预览立即变为name: Jordan。这说明上下文与 UI 状态是实时绑定的无需重新刷新页面或重新建立会话。5.4 切换 recent-activity 复选框验证 JSON 更新toggleActivity对recentActivity数组做包含/排除切换const toggleActivity (activity: string) { setRecentActivity((prev) prev.includes(activity) ? prev.filter((a) a ! activity) : [...prev, activity], ); };每次勾选/取消recentActivity数组变化JSON 预览中的活动列表同步增减。默认勾选的是ACTIVITIES[0]Viewed the pricing page与ACTIVITIES[2]Watched the product demo video。5.5 提问 What do you know about me?Agent 应引用上下文值这是整个功能的核心验证点击 Who am I? 建议后Agent 的回答应包含从上下文读到的身份信息如名字。在真实 LLM 环境下回答会引用当前发布的 context 字段在 CI 的 aimock 录制环境下该提示词对应固定的 fixture回复以 I see youre Atai 开头见 E2E 测试注释证明useAgentContext的数据确实到达了模型侧。5.6 修改时区后提问 What time is it for me?Agent 应反映新时区将 Timezone 从默认的America/Los_Angeles改为其他时区如Asia/Tokyo后userTimezone上下文更新Agent 回答时间类问题时将基于新的时区作答。这验证了 descriptionThe users IANA timezone (used when mentioning times)对模型行为的指导作用。六、E2E 测试把 QA 清单固化为可回归的断言QA 清单的人工步骤在 showcase/integrations/langroid/tests/e2e/readonly-state-agent-context.spec.ts 中被完整自动化测试文件头注释明确标注 QA reference: qa/readonly-state-agent-context.md。测试覆盖了四个关键场景页面加载断言context-card可见、composer 占位符 Ask about your context... 可见编辑联动将 Name 填入 Jamie 后断言 JSON 出现name: Jamie将时区切换为Asia/Tokyo后断言 JSON 出现timezone: Asia/Tokyo身份问答先断言 Identity 卡默认显示 Atai / America/Los_Angeles / 头像 A再点击 Who am I? 建议断言助手回复以 I see youre Atai 开头aimock fixture 固定输出活动勾选默认值断言 pricing page 与 product demo video 两个复选框默认处于 checked 状态活动问答点击 Suggest next steps 后断言助手回复引用默认活动Since you recently viewed the pricing page and watched the product demo video...。测试注释还特别说明了测试策略两个建议提示词被固定映射到 aimock 确定性 fixture以保证 CI 稳定性在 Railway 真实部署上同样的提示词会得到引用已发布上下文字段的真实 LLM 回复——证明端到端 useAgentContext 接线正确。七、只读上下文与共享状态的选择边界Langroid 集成模块同时提供了共享状态的同类 demo如 shared-state-read-write.py 对应的读写 demo后端通过set_notes等工具写回状态并发射STATE_SNAPSHOT事件。两者边界可归纳为维度useAgentContext只读Shared State读写方向UI → Agent 单向UI ↔ Agent 双向Agent 可否修改不能无 setter、无写回工具可以通过工具调用 mutate典型场景登录用户、时区、功能开关、当前记录需要双方协作编辑的工作区笔记、偏好、进度卸载行为组件卸载自动注销显式管理官方文档agent-readonly.mdx给出的选择建议是当值是一个输入而非字段——即每一轮传给 Agent 的上下文对象而不是双方共同编辑的工作区——时优先使用useAgentContext当需要同时支持读与写时才升级为完整的 共享状态。八、小结Langroid 集成中的 Readonly State (Agent Context) demo 完整演示了 CopilotKit 只读上下文的标准用法前端通过useAgentContext({ description, value })发布身份、时区、活动等 UI 状态Next.js Runtime 借助 AG-UI 协议代理到 Langroid Agent Server使 Agent 每一轮都能感知这些值但永远无法修改它们。QA 清单的 6 条步骤导航、默认值校验、字段编辑联动、JSON 实时更新、身份问答、时区感知问答既是人工验收的 checklist也在 E2E 测试中固化为自动化断言。对于任何需要让 Agent 理解当前 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CopilotKit 与 Langroid 集成实战：用 useAgentContext 实现只读 Agent 上下文（Readonly State）
CopilotKit 与 Langroid 集成实战用 useAgentContext 实现只读 Agent 上下文Readonly State【免费下载链接】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 展示项目showcase中 Langroid 集成模块的只读 Agent 上下文功能展开讲解如何通过useAgentContext将前端 UI 状态用户身份、时区、最近活动等以单向、只读的方式发布给后端 Langroid Agent并详细拆解官方 QA 验证清单showcase/integrations/langroid/qa/readonly-state-agent-context.md中每一条测试步骤的预期行为与底层实现。读完本文你将掌握useAgentContext的调用方式、上下文数据的传输链路Next.js Runtime → AG-UI → Langroid Agent Server以及如何用 Playwright E2E 测试固化这类只读上下文行为。一、功能定位让 Agent知道但不能改的 UI 状态在 CopilotKit 的前端框架体系中Agent 有时需要了解用户当前在界面上看到了什么例如当前登录用户的显示名identity用户所在的 IANA 时区用于回答现在几点这类问题用户在应用内的最近活动记录用于推荐下一步操作。这些值属于纯输入inputAgent 只需要读取绝不应该被 LLM 通过工具调用反向修改。为此CopilotKit 提供了useAgentContext—— 一条单向的 UI → Agent 通道。官方文档showcase/shell-docs/src/content/docs/shared-state/agent-readonly.mdx对它的设计定位概括为props for the agent给 Agent 传的 props。与完整的共享状态shared stateAgent 可以调用工具把状态写回 UI不同useAgentContext发布的值在每一轮对话中都会通过运行时的上下文注入被 Agent 看到没有任何 setter也没有任何可写回的工具组件卸载时自动注销例如离开当前页面当前记录上下文随之消失。因此它天然适合用户身份、功能开关、当前选中的记录、滚动位置这类UI 拥有、Agent 只读的数据。二、核心 APIuseAgentContext 的调用方式与参数Langroid 集成模块的 demo 页面位于 showcase/integrations/langroid/src/app/demos/readonly-state-agent-context/page.tsx其核心调用如下useAgentContext({ 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, });每个useAgentContext调用只接受两个字段参数含义注意事项description一段简短的人类可读标签Agent 会与 value 一起看到官方文档强调它像参数 docstring 一样重要直接影响 LLM 理解该值的用途value要发布的实际值字符串、数组等值变化时React 重渲染自动刷新注册项组件卸载时自动移除从 demo 可以看到三处调用的value分别来自三个独立的useStateconst [userName, setUserName] useState(Atai); const [userTimezone, setUserTimezone] useState(America/Los_Angeles); const [recentActivity, setRecentActivity] useStatestring[]([ ACTIVITIES[0], // Viewed the pricing page ACTIVITIES[2], // Watched the product demo video ]);官方文档同时指出useAgentContext并不关心 value 来自哪里——可以是本地useState、React Context、Redux、查询缓存等任意来源唯一要求是值的标识足够稳定避免 React 渲染循环。在真实应用中这些值通常会来自 auth provider、路由 hook 或领域状态仓库。三、demo 界面Context 卡片与实时 JSON 预览demo 页面布局由 demo-layout.tsx 实现整个界面被称为 Agent Context Inspector包含三张卡片Identity 卡片展示 Name文本框与 Timezone下拉选择包含America/Los_Angeles、Asia/Tokyo等 6 个时区以及一个根据名字首字母和时区区域动态渲染的头像Recent Activity 卡片5 项可勾选的活动如 Viewed the pricing page、Started the 14-day free trial勾选状态决定该活动是否Visible to the agentPublished Context 卡片全宽度的 JSON 预览区实时展示真正广播给 Agent 的载荷{ name: Atai, timezone: America/Los_Angeles, recentActivity: [Viewed the pricing page, Watched the product demo video] }这个 JSON 预览是 QA 验证的核心观察点——所有字段编辑都会立即反映到该 JSON 中形成所见即 Agent 所得的可视化反馈闭环。demo 还在 suggestions.ts 中通过useConfigureSuggestions预置了三条与只读上下文强相关的建议提问Who am I? → What do you know about me from my context?Suggest next steps → Based on my recent activity, what should I try next?Plan my morning → What time is it in my timezone and what should I do for the next hour?这三条建议恰好覆盖了 QA 清单中要验证的 Agent 行为身份识别、活动推荐、时区感知。四、数据链路上下文如何从 UI 到达 Langroid Agent只读上下文并不直接拼进前端代码而是走一条完整的前后端链路由两部分组成4.1 前端运行时代理Next.js route.tsshowcase/integrations/langroid/src/app/api/copilotkit/route.ts 使用copilotkit/runtime/v2的CopilotRuntime与createCopilotRuntimeHandler创建单一路由mode: single-route并通过HttpAgent来自ag-ui/client将请求按AG-UI 协议代理到后端 Langroid Agent Server默认http://localhost:8000可用环境变量AGENT_URL覆盖const AGENT_URL process.env.AGENT_URL || http://localhost:8000; function createAgent(path /) { return new HttpAgent({ url: ${AGENT_URL}${path} }); }该 route 将包括readonly-state-agent-context在内的 30 余个 demo agent 名称统一注册到同一个后端统一 Agent 上代码注释明确说明Read-only agent context — frontend exposes useAgentContext; same agent。也就是说只读上下文完全由前端运行时注入后端 Agent 本身不需要任何专用工具。4.2 后端 Langroid Agent Serveragent_server.pyshowcase/integrations/langroid/src/agent_server.py 是一个 FastAPI 服务。由于 Langroid 没有原生的 AG-UI 适配器它实现了一个自定义 SSE 端点把 Langroid 的ChatAgent与 AG-UI 事件流相互转换。文件头注释明确指出The Next.js CopilotKit runtime proxies requests here via AG-UI protocol.从 agui_adapter.py 的代码可以看到app.post(/)的run_agent会把请求体强转为RunAgentInputRunAgentInput(**body)再进入 AG-UI 的 SSE 事件管道。前端运行时在每一轮将useAgentContext注册的条目注入消息历史后Agent 便能在该轮回答中感知到这些上下文值——这正是 QA 中Agent 能引用上下文的底层原因。4.3 页面接线demo 页面的外层通过CopilotKit runtimeUrl/api/copilotkit agentreadonly-state-agent-context绑定运行时与 Agent再挂载CopilotPopup占位提示为 Ask about your context...作为对话入口。整个结构是React 状态 → useAgentContext 注册 → CopilotKit runtime 注入 → AG-UI 代理 → Langroid 统一 Agent 读取。五、QA 验证清单逐条拆解默认值、操作与预期原 QA 文档showcase/integrations/langroid/qa/readonly-state-agent-context.md定义了 6 条人工验收步骤下面逐条给出其预期行为与源码依据。5.1 导航到 /demos/readonly-state-agent-context页面路由由src/app/demos/readonly-state-agent-context/page.tsx提供浏览器访问后应渲染出三张 Context 卡片与右下角的 Copilot 弹出式聊天窗。5.2 验证 context card 默认 Name 为 AtaiuseState(Atai)是 Name 的默认值Identity 卡片与 Published Context JSON 中的name: Atai应同时呈现。E2E 测试用page.getByTestId(identity-name)断言其文本为 Atai见下文测试章节。5.3 将 Name 改为 Jordan验证 published JSON 更新修改 Name 输入框会触发setUserNameuseAgentContext注册项随之刷新Published Context 的 JSON 预览立即变为name: Jordan。这说明上下文与 UI 状态是实时绑定的无需重新刷新页面或重新建立会话。5.4 切换 recent-activity 复选框验证 JSON 更新toggleActivity对recentActivity数组做包含/排除切换const toggleActivity (activity: string) { setRecentActivity((prev) prev.includes(activity) ? prev.filter((a) a ! activity) : [...prev, activity], ); };每次勾选/取消recentActivity数组变化JSON 预览中的活动列表同步增减。默认勾选的是ACTIVITIES[0]Viewed the pricing page与ACTIVITIES[2]Watched the product demo video。5.5 提问 What do you know about me?Agent 应引用上下文值这是整个功能的核心验证点击 Who am I? 建议后Agent 的回答应包含从上下文读到的身份信息如名字。在真实 LLM 环境下回答会引用当前发布的 context 字段在 CI 的 aimock 录制环境下该提示词对应固定的 fixture回复以 I see youre Atai 开头见 E2E 测试注释证明useAgentContext的数据确实到达了模型侧。5.6 修改时区后提问 What time is it for me?Agent 应反映新时区将 Timezone 从默认的America/Los_Angeles改为其他时区如Asia/Tokyo后userTimezone上下文更新Agent 回答时间类问题时将基于新的时区作答。这验证了 descriptionThe users IANA timezone (used when mentioning times)对模型行为的指导作用。六、E2E 测试把 QA 清单固化为可回归的断言QA 清单的人工步骤在 showcase/integrations/langroid/tests/e2e/readonly-state-agent-context.spec.ts 中被完整自动化测试文件头注释明确标注 QA reference: qa/readonly-state-agent-context.md。测试覆盖了四个关键场景页面加载断言context-card可见、composer 占位符 Ask about your context... 可见编辑联动将 Name 填入 Jamie 后断言 JSON 出现name: Jamie将时区切换为Asia/Tokyo后断言 JSON 出现timezone: Asia/Tokyo身份问答先断言 Identity 卡默认显示 Atai / America/Los_Angeles / 头像 A再点击 Who am I? 建议断言助手回复以 I see youre Atai 开头aimock fixture 固定输出活动勾选默认值断言 pricing page 与 product demo video 两个复选框默认处于 checked 状态活动问答点击 Suggest next steps 后断言助手回复引用默认活动Since you recently viewed the pricing page and watched the product demo video...。测试注释还特别说明了测试策略两个建议提示词被固定映射到 aimock 确定性 fixture以保证 CI 稳定性在 Railway 真实部署上同样的提示词会得到引用已发布上下文字段的真实 LLM 回复——证明端到端 useAgentContext 接线正确。七、只读上下文与共享状态的选择边界Langroid 集成模块同时提供了共享状态的同类 demo如 shared-state-read-write.py 对应的读写 demo后端通过set_notes等工具写回状态并发射STATE_SNAPSHOT事件。两者边界可归纳为维度useAgentContext只读Shared State读写方向UI → Agent 单向UI ↔ Agent 双向Agent 可否修改不能无 setter、无写回工具可以通过工具调用 mutate典型场景登录用户、时区、功能开关、当前记录需要双方协作编辑的工作区笔记、偏好、进度卸载行为组件卸载自动注销显式管理官方文档agent-readonly.mdx给出的选择建议是当值是一个输入而非字段——即每一轮传给 Agent 的上下文对象而不是双方共同编辑的工作区——时优先使用useAgentContext当需要同时支持读与写时才升级为完整的 共享状态。八、小结Langroid 集成中的 Readonly State (Agent Context) demo 完整演示了 CopilotKit 只读上下文的标准用法前端通过useAgentContext({ description, value })发布身份、时区、活动等 UI 状态Next.js Runtime 借助 AG-UI 协议代理到 Langroid Agent Server使 Agent 每一轮都能感知这些值但永远无法修改它们。QA 清单的 6 条步骤导航、默认值校验、字段编辑联动、JSON 实时更新、身份问答、时区感知问答既是人工验收的 checklist也在 E2E 测试中固化为自动化断言。对于任何需要让 Agent 理解当前 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考