CopilotKit 只读 Agent Context 实战用 useAgentContext 把前端状态安全地暴露给 CrewAI 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 的 CrewAI Conversational Flows 集成演示位于 showcase/integrations/crewai-conversational-flows中readonly-state-agent-context是一个专门验证「前端只读上下文」特性的端到端示例前端通过useAgentContext把用户名、时区、最近活动等字段持续发布给 AgentAgent 可以读取并据此作答但无法修改这些字段。读完本文你将掌握useAgentContext的调用方式、上下文在 CopilotKit Runtime 与 CrewAI Flow 之间的流转链路以及如何用 e2e 测试锁定「读得到、改不了」这一核心行为。这个 Demo 在验证什么readonly-state-agent-context的 QA 检查清单qa/readonly-state-agent-context.md给出了五个核心验证目标访问/demos/readonly-state-agent-context页面页面正常加载左侧渲染Agent Context卡片data-testidcontext-card名称输入框data-testidctx-name、时区下拉框data-testidctx-timezone、最近活动复选框以及 State JSON 面板全部可见把名称改为 Alexctx-state-json实时更新向 Agent 提问 What do you know about me from my context?Agent 的回答能引用名称、时区、最近活动。这五点实际上覆盖了只读上下文特性的完整链路UI 渲染 → 状态变更发布 → JSON 广播 → Agent 语义消费。下面结合该仓库的源码逐一展开。前端发布只读上下文useAgentContext 的调用方式演示页面的入口组件位于 src/app/demos/readonly-state-agent-context/page.tsx。核心代码只有三处useAgentContext调用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的两个关键设计每条上下文都由descriptionvalue构成。description是给 AgentLLM看的人类可读语义说明帮助模型理解这个值的含义与使用场景value是实际的数据值。这种「带解释的数据」设计让 Agent 不需要猜测字段含义。Hook 是声明式的、随状态实时更新。组件内部的userName、userTimezone、recentActivity分别由useState管理默认值为Atai、America/Los_Angeles以及预置的若干活动项任何一次前端状态变更都会让useAgentContext重新发布最新值Agent 在下一次对话轮次中就能读到。这些 Hook 全部来自copilotkit/react-core/v2同一文件第 6–9 行的导入语句可证import { CopilotKit, CopilotPopup, useAgentContext, } from copilotkit/react-core/v2;整个 Demo 被包在CopilotKitProvider 中并指定了runtimeUrl/api/copilotkit与agentreadonly-state-agent-context页面右下角挂载了一个默认展开的CopilotPopup聊天输入框占位符为 Ask about your context...引导用户直接询问 Agent 对自己了解多少。Agent Context InspectorUI 结构与状态广播的可视化与useAgentContext配套的 UI 位于 src/app/demos/readonly-state-agent-context/demo-layout.tsx。这个组件把「正在发布给 Agent 的上下文」完全可视化分为三块Identity 卡片名称输入框ctx-name、时区下拉框ctx-timezone、头像预览。时区下拉框的候选项来自文件顶部定义的TIMEZONES常量America/Los_Angeles、America/New_York、Europe/London、Europe/Berlin、Asia/Tokyo、Australia/Sydney六个 IANA 时区头像则取用户名的首字母大写。Recent Activity 卡片五个预置活动项ACTIVITIES常量各对应一个复选框例如 Viewed the pricing page、Added Pro Plan to cart、Watched the product demo video、Started the 14-day free trial、Invited a teammate。勾选状态直接决定 Agent 能看到哪些近期行为。Published Context 面板底部通栏的 JSON 视图data-testidctx-state-json把当前上下文序列化后实时展示。这正是 QA 清单第 4 步「改名称后ctx-state-json更新」的可视化依据——每次编辑JSON 面板都会立即反映新的name、timezone、recentActivity。UI 顶部的徽章标注了该 Demo 的两个核心语义Read-only Agent Context与useAgentContext。组件内的说明文字也明确写道Agent 可以读取这些字段但不能修改它们can read this context, butcannot modifyit。上下文如何抵达 CrewAI AgentRuntime 路由与服务端 Flow前端发布的上下文并不会自己跑到 Agent 那里中间需要 CopilotKit Runtime 做代理。在 src/app/api/copilotkit/route.ts 中readonly-state-agent-context被注册为一个前端可见的 agent 别名第 59 行并通过HttpAgent转发到 Python 后端function createAgent(path /chat) { const feature path.replace(/^\//, ); return new HttpAgent({ url: ${AGENT_URL}/conversational_flows/${feature}, }); }后端进程默认监听AGENT_URL缺省为http://localhost:8000运行时通过 AG-UI 协议与 CrewAI Flow 通信。也就是说前端useAgentContext发布的上下文会随对话请求一起经由/api/copilotkit→ AG-UI →conversational_flows后端最终注入到对应的 CrewAI Flow 中。服务端如何「只读」地消费上下文可以参考同仓库中 src/agents/shared_state_read.py 的实现模式Flow 通过继承CopilotKitState获得前端状态在每次对话轮次开始时把状态序列化并拼进 system prompt明确告诉模型「这是前端持有的状态读取它来回答问题但永远不要声称自己修改过它」SYSTEM_PROMPT ( You are a concise recipe assistant. The frontend-owned recipe state is included below. Read it when answering, but never claim to have edited the recipe because this demo intentionally gives the agent read-only access.\n\nCurrent recipe state:\n{recipe} )随后 Flow 用copilotkit_stream包裹流式补全请求把system prompt 历史消息 copilotkit actions一并交给模型modelopenai/gpt-5.4从而保证 Agent 的每一次回答都能「看见」最新一次前端广播的状态同时没有任何写入路径——这正是「只读」的工程落地方式。用 e2e 测试锁定「读得到、改不了」的行为仅靠人工 QA 不足以保证这个特性长期不回归。仓库为它准备了完整的 Playwright 测试tests/e2e/readonly-state-agent-context.spec.ts共五个用例正好与 QA 清单一一对应页面加载断言context-card与聊天输入框占位符 Ask about your context...可见编辑即更新向ctx-name填入 Jamie断言ctx-state-json包含name: Jamie通过selectOption(Asia/Tokyo)切换时区断言 JSON 面板包含timezone: Asia/Tokyo——直接验证 QA 清单第 4 步身份卡片与 Who am I? 建议先断言默认身份名字 Atai、时区 America/Los_Angeles、头像 A点击 Who am I? 建议 pill 后断言助手回复以 I see youre Atai 开头——验证 Agent 确实读到了上下文中的名称默认活动勾选断言 Viewed the pricing page 与 Watched the product demo video 两个复选框默认选中Suggest next steps 建议点击后断言助手回复以 Since you recently viewed the pricing page and watched the product demo video 开头——证明 Agent 的回复被recentActivity上下文所 grounding。值得注意的一个细节是测试文件头部的注释说明了确定性回复的来源——两个建议 prompt 都固定到 aimock fixtureshowcase/aimock/d5-all.json使 CI 中的回复首句保持稳定而在 Railway 等真实环境里同样的 prompt 会得到真实 LLM 回复从而端到端证明useAgentContext的接线是通的。这种「mock 稳定 真实验证」的双轨设计值得在集成测试中复用。引导提问的建议提示Suggestions配置为了让用户和测试方便地触发 Agent 对上下文的引用Demo 通过 src/app/demos/readonly-state-agent-context/suggestions.ts 配置了三条建议提示useConfigureSuggestions({ suggestions: [ { title: Who am I?, message: What do you know about me from my context? }, { title: Suggest next steps, message: Based on my recent activity, what should I try next? }, { title: Plan my morning, message: What time is it in my timezone and what should I do for the next hour? }, ], available: always, });三条建议分别从三个角度考验只读上下文Who am I? 要求 Agent 引用name与身份信息Suggest next steps 要求 Agent 基于recentActivity给出建议Plan my morning 要求 Agent 结合timezone时区做时间相关的推理。QA 清单第 5 步使用的正是第一条建议对应的完整 promptWhat do you know about me from my context?可见建议提示既是用户体验入口也是验证 Agent 上下文感知能力的标准测试语料。小结一套可复制的「只读上下文」落地模板综合来看readonly-state-agent-context这个 Demo 给出了 CopilotKit 只读 Agent Context 的完整参考实现可以提炼为四步模板前端发布在组件中调用useAgentContext({ description, value })声明式地把用户画像数据持续广播给 Agent可视化仪表盘用输入框、下拉框、复选框 实时 JSON 面板把「正在发布什么」展示给用户方便调试与演示Runtime 接线在 src/app/api/copilotkit/route.ts 中把 demo 名注册为 agent 别名通过 AG-UI 协议转发到 CrewAI Flow 后端服务端只读消费在 Flow 的 system prompt 中注入前端状态并显式声明「只读」让 Agent 读取但没有任何写入路径。再配合 tests/e2e/readonly-state-agent-context.spec.ts 的自动化断言即可把「读得到、改不了」这个行为固化下来。如果你正在构建需要感知用户上下文、又必须保证上下文所有权仍在前端的 CopilotKit 应用这个 Demo 及其 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），仅供参考 CopilotKit 只读 Agent Context 实战：用 useAgentContext 把前端状态安全地暴露给 CrewAI Agent
CopilotKit 只读 Agent Context 实战用 useAgentContext 把前端状态安全地暴露给 CrewAI 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 的 CrewAI Conversational Flows 集成演示位于 showcase/integrations/crewai-conversational-flows中readonly-state-agent-context是一个专门验证「前端只读上下文」特性的端到端示例前端通过useAgentContext把用户名、时区、最近活动等字段持续发布给 AgentAgent 可以读取并据此作答但无法修改这些字段。读完本文你将掌握useAgentContext的调用方式、上下文在 CopilotKit Runtime 与 CrewAI Flow 之间的流转链路以及如何用 e2e 测试锁定「读得到、改不了」这一核心行为。这个 Demo 在验证什么readonly-state-agent-context的 QA 检查清单qa/readonly-state-agent-context.md给出了五个核心验证目标访问/demos/readonly-state-agent-context页面页面正常加载左侧渲染Agent Context卡片data-testidcontext-card名称输入框data-testidctx-name、时区下拉框data-testidctx-timezone、最近活动复选框以及 State JSON 面板全部可见把名称改为 Alexctx-state-json实时更新向 Agent 提问 What do you know about me from my context?Agent 的回答能引用名称、时区、最近活动。这五点实际上覆盖了只读上下文特性的完整链路UI 渲染 → 状态变更发布 → JSON 广播 → Agent 语义消费。下面结合该仓库的源码逐一展开。前端发布只读上下文useAgentContext 的调用方式演示页面的入口组件位于 src/app/demos/readonly-state-agent-context/page.tsx。核心代码只有三处useAgentContext调用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的两个关键设计每条上下文都由descriptionvalue构成。description是给 AgentLLM看的人类可读语义说明帮助模型理解这个值的含义与使用场景value是实际的数据值。这种「带解释的数据」设计让 Agent 不需要猜测字段含义。Hook 是声明式的、随状态实时更新。组件内部的userName、userTimezone、recentActivity分别由useState管理默认值为Atai、America/Los_Angeles以及预置的若干活动项任何一次前端状态变更都会让useAgentContext重新发布最新值Agent 在下一次对话轮次中就能读到。这些 Hook 全部来自copilotkit/react-core/v2同一文件第 6–9 行的导入语句可证import { CopilotKit, CopilotPopup, useAgentContext, } from copilotkit/react-core/v2;整个 Demo 被包在CopilotKitProvider 中并指定了runtimeUrl/api/copilotkit与agentreadonly-state-agent-context页面右下角挂载了一个默认展开的CopilotPopup聊天输入框占位符为 Ask about your context...引导用户直接询问 Agent 对自己了解多少。Agent Context InspectorUI 结构与状态广播的可视化与useAgentContext配套的 UI 位于 src/app/demos/readonly-state-agent-context/demo-layout.tsx。这个组件把「正在发布给 Agent 的上下文」完全可视化分为三块Identity 卡片名称输入框ctx-name、时区下拉框ctx-timezone、头像预览。时区下拉框的候选项来自文件顶部定义的TIMEZONES常量America/Los_Angeles、America/New_York、Europe/London、Europe/Berlin、Asia/Tokyo、Australia/Sydney六个 IANA 时区头像则取用户名的首字母大写。Recent Activity 卡片五个预置活动项ACTIVITIES常量各对应一个复选框例如 Viewed the pricing page、Added Pro Plan to cart、Watched the product demo video、Started the 14-day free trial、Invited a teammate。勾选状态直接决定 Agent 能看到哪些近期行为。Published Context 面板底部通栏的 JSON 视图data-testidctx-state-json把当前上下文序列化后实时展示。这正是 QA 清单第 4 步「改名称后ctx-state-json更新」的可视化依据——每次编辑JSON 面板都会立即反映新的name、timezone、recentActivity。UI 顶部的徽章标注了该 Demo 的两个核心语义Read-only Agent Context与useAgentContext。组件内的说明文字也明确写道Agent 可以读取这些字段但不能修改它们can read this context, butcannot modifyit。上下文如何抵达 CrewAI AgentRuntime 路由与服务端 Flow前端发布的上下文并不会自己跑到 Agent 那里中间需要 CopilotKit Runtime 做代理。在 src/app/api/copilotkit/route.ts 中readonly-state-agent-context被注册为一个前端可见的 agent 别名第 59 行并通过HttpAgent转发到 Python 后端function createAgent(path /chat) { const feature path.replace(/^\//, ); return new HttpAgent({ url: ${AGENT_URL}/conversational_flows/${feature}, }); }后端进程默认监听AGENT_URL缺省为http://localhost:8000运行时通过 AG-UI 协议与 CrewAI Flow 通信。也就是说前端useAgentContext发布的上下文会随对话请求一起经由/api/copilotkit→ AG-UI →conversational_flows后端最终注入到对应的 CrewAI Flow 中。服务端如何「只读」地消费上下文可以参考同仓库中 src/agents/shared_state_read.py 的实现模式Flow 通过继承CopilotKitState获得前端状态在每次对话轮次开始时把状态序列化并拼进 system prompt明确告诉模型「这是前端持有的状态读取它来回答问题但永远不要声称自己修改过它」SYSTEM_PROMPT ( You are a concise recipe assistant. The frontend-owned recipe state is included below. Read it when answering, but never claim to have edited the recipe because this demo intentionally gives the agent read-only access.\n\nCurrent recipe state:\n{recipe} )随后 Flow 用copilotkit_stream包裹流式补全请求把system prompt 历史消息 copilotkit actions一并交给模型modelopenai/gpt-5.4从而保证 Agent 的每一次回答都能「看见」最新一次前端广播的状态同时没有任何写入路径——这正是「只读」的工程落地方式。用 e2e 测试锁定「读得到、改不了」的行为仅靠人工 QA 不足以保证这个特性长期不回归。仓库为它准备了完整的 Playwright 测试tests/e2e/readonly-state-agent-context.spec.ts共五个用例正好与 QA 清单一一对应页面加载断言context-card与聊天输入框占位符 Ask about your context...可见编辑即更新向ctx-name填入 Jamie断言ctx-state-json包含name: Jamie通过selectOption(Asia/Tokyo)切换时区断言 JSON 面板包含timezone: Asia/Tokyo——直接验证 QA 清单第 4 步身份卡片与 Who am I? 建议先断言默认身份名字 Atai、时区 America/Los_Angeles、头像 A点击 Who am I? 建议 pill 后断言助手回复以 I see youre Atai 开头——验证 Agent 确实读到了上下文中的名称默认活动勾选断言 Viewed the pricing page 与 Watched the product demo video 两个复选框默认选中Suggest next steps 建议点击后断言助手回复以 Since you recently viewed the pricing page and watched the product demo video 开头——证明 Agent 的回复被recentActivity上下文所 grounding。值得注意的一个细节是测试文件头部的注释说明了确定性回复的来源——两个建议 prompt 都固定到 aimock fixtureshowcase/aimock/d5-all.json使 CI 中的回复首句保持稳定而在 Railway 等真实环境里同样的 prompt 会得到真实 LLM 回复从而端到端证明useAgentContext的接线是通的。这种「mock 稳定 真实验证」的双轨设计值得在集成测试中复用。引导提问的建议提示Suggestions配置为了让用户和测试方便地触发 Agent 对上下文的引用Demo 通过 src/app/demos/readonly-state-agent-context/suggestions.ts 配置了三条建议提示useConfigureSuggestions({ suggestions: [ { title: Who am I?, message: What do you know about me from my context? }, { title: Suggest next steps, message: Based on my recent activity, what should I try next? }, { title: Plan my morning, message: What time is it in my timezone and what should I do for the next hour? }, ], available: always, });三条建议分别从三个角度考验只读上下文Who am I? 要求 Agent 引用name与身份信息Suggest next steps 要求 Agent 基于recentActivity给出建议Plan my morning 要求 Agent 结合timezone时区做时间相关的推理。QA 清单第 5 步使用的正是第一条建议对应的完整 promptWhat do you know about me from my context?可见建议提示既是用户体验入口也是验证 Agent 上下文感知能力的标准测试语料。小结一套可复制的「只读上下文」落地模板综合来看readonly-state-agent-context这个 Demo 给出了 CopilotKit 只读 Agent Context 的完整参考实现可以提炼为四步模板前端发布在组件中调用useAgentContext({ description, value })声明式地把用户画像数据持续广播给 Agent可视化仪表盘用输入框、下拉框、复选框 实时 JSON 面板把「正在发布什么」展示给用户方便调试与演示Runtime 接线在 src/app/api/copilotkit/route.ts 中把 demo 名注册为 agent 别名通过 AG-UI 协议转发到 CrewAI Flow 后端服务端只读消费在 Flow 的 system prompt 中注入前端状态并显式声明「只读」让 Agent 读取但没有任何写入路径。再配合 tests/e2e/readonly-state-agent-context.spec.ts 的自动化断言即可把「读得到、改不了」这个行为固化下来。如果你正在构建需要感知用户上下文、又必须保证上下文所有权仍在前端的 CopilotKit 应用这个 Demo 及其 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），仅供参考