copilot-kit-ag-ui 端到端验证指南用真实服务器驱动 Claude Managed Agents 与 CopilotKit 演示【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts本指南基于 managed-agents/copilot-kit-ag-ui/.claude/skills/verify/SKILL.md 编写围绕如何验证对 copilot-kit-ag-ui 演示项目的改动这一主题展开。该项目是一个由 Claude Managed Agent 驱动的个人理财助手聊天应用Anthropic 托管 Agent 循环与容器CopilotKit 渲染聊天界面回复逐 token 流式输出Agent 需要展示数字时会在对话内联渲染交互式图表。读完本文你将掌握一套无凭据冒烟验证 有凭据真实对话验证的双路径验证方法理解每个探针背后的源码链路并能在改动后快速判断服务端、前端与 Agent 集成是否端到端可用。验证的第一原则构建并驱动真实服务器SKILL.md 开门见山给出了一条铁律Build and drive the real server.npm run typecheckis CIs job, not evidence.意思是类型检查是 CI 的职责不是验证证据。要验证改动必须真正构建前端、启动真实服务器并用 HTTP 请求驱动它走完路由到 SDK 的完整路径。这与仓库的设计一致——CLAUDE.md 明确写着There are no tests. Verify changes by running the app项目没有测试用例验证方式就是运行应用。因此验证的基本流程固定在两条路径上一是无 Anthropic 凭据时的冒烟验证覆盖除真实 Agent 对话外的全部接线二是有真实凭据时的端到端对话验证覆盖含真实 Agent 回合的完整链路。两条路径都以 README.md 中的命令体系为基础npm install安装全部 workspacenpm run setup一次性预置环境与 Agentnpm run dev启动开发服务器runtime 在 :8787web 在 :5173npm run build构建前端到web/distnpm start以单端口运行生产服务器。无凭据路径用 stub ID 启动服务器并逐项探测没有 Anthropic 凭据或尚未预置 Agent 时服务器依然可以启动并服务除真实 Agent 回合之外的一切。因为服务器的启动只要求Agent 身份存在ID 类环境变量或agent-ids.json并不要求身份真实有效——真正的 API 调用发生在聊天消息发出之时。启动命令在仓库根目录的 managed-agents/copilot-kit-ag-ui 下执行npm install npm run build ANTHROPIC_API_KEYsk-ant-test ANTHROPIC_ENVIRONMENT_IDenv_x \ ANTHROPIC_AGENT_IDagent_x ANTHROPIC_AGENT_VERSION1 PORT8799 npm startnpm run build先把 web workspace 构建出web/dist——这是后面静态服务探针的前提见 Gotchas 一节ANTHROPIC_API_KEYsk-ant-test是无效的测试凭据仅供冒烟测试验证时用假值即可ANTHROPIC_ENVIRONMENT_ID、ANTHROPIC_AGENT_ID、ANTHROPIC_AGENT_VERSION1三个 stub ID 让 server/src/setup.ts 中的loadAgentIds()走env vars first分支——三个变量全部设置时优先于agent-ids.json且三者必须同时出现只设置其中一部分会被视为部署配置错误直接抛异常PORT8799覆盖默认端口 8787避免与开发服务器冲突对应 server/src/index.ts 的process.env.PORT ?? 8787。服务器启动时loadAgentIds()会在模块顶层执行server/src/index.ts 的Fail fast设计ID 缺失会立刻报No agent configured并退出——这是刻意为之启动期报错好过聊到一半才报错。探针一根路径返回构建后的前端GET :8799/期望返回构建好的web/dist/index.html。注意仓库没有 SPA catch-all 路由未知路径一律 404。对应源码在 server/src/index.tsfs.existsSync(webDist)成立时挂载express.static(webDist)仅当web/dist存在时静态服务才会激活。探针二info 端点列出已注册 AgentGET :8799/api/copilotkit/info期望返回已注册的 Agent 列表。这个探针的价值在于不发起任何 API 调用就能确认 Agent 的 ID 与类注册是否正确。它验证的是 server/src/index.ts 中CopilotSseRuntime的接线——agents里注册了financial-assistant键对应一个ManagedAgentsAgent实例来自上游ag-ui/claude-managed-agents包并传入managedAgentId、agentVersion、environmentId与backendTools: vizTools。探针三POST run 端点走通完整路由并收到 Anthropic 401POST :8799/api/copilotkit/agent/financial-assistant/run Content-Type: application/json {threadId:t1,runId:r1,messages:[{id:m1,role:user,content:hi}],state:{},tools:[],context:[],forwardedProps:{}}请求体是标准的AG-UI 消息结构thread/run 标识 消息数组 state/tools/context/forwardedProps。期望结果请求到达 AG-UI 适配器随后因无效的sk-ant-test凭据从 Anthropic 返回401这个 401 以 SSE 的RUN_ERROR事件形式回传。这个探针是整个无凭据路径的核心一个来自 Anthropic 的 401 恰恰证明了浏览器 → CopilotKit runtime → AG-UI 适配器 → Anthropic SDK的完整路由是通的——链路接线正确只是凭据无效。探针四CORS 行为验证OPTIONS :8799/api/copilotkit Origin: https://example.com期望行为设置ALLOWED_ORIGINS时允许列表内的 Origin 收到回显的Access-Control-Allow-Origin头列表外的 Origin 不收到该头。对应 server/src/index.ts 的 CORS 逻辑ALLOWED_ORIGINS按逗号切分、trim、过滤空值后作为cors.origin白名单未设置时默认放行所有 Originpermissive CORS本地开发没问题设置但为空则拒绝所有跨域。由于该端点没有鉴权且每条消息都会消耗 API 额度公开部署时必须设置ALLOWED_ORIGINS。探针五构建期烘焙 runtime URLVITE_COPILOT_RUNTIME_URL... npm run build grep web/dist/assets -r 你的URL期望在web/dist/assets的产物中 grep 到该 URL确认前端构建期就把 runtime 地址写死。对应前端源码 web/src/App.tsximport.meta.env.VITE_COPILOT_RUNTIME_URL || /api/copilotkit。默认同源路径/api/copilotkit同时适用于开发代理与单进程部署只有当前端与 runtime 分开托管时才需要在构建时注入该变量。有凭据路径真实 Agent 回合与内联图表有真实凭据时按 README.md 的正常流程走npm run setup # 一次性预置环境 Agent npm run dev # runtime :8787web :5173打开 http://localhost:5173发送一个会触发可视化工具的问题例如show me a growth projection for $500/month at 7%期望结果是图表在对话内联渲染。这条路径验证的是生成式 UIGenerative UI的完整闭环Agent 调用show_growth_projection可视化工具——四个可视化工具payoff timeline 债务清偿、growth projection 增长预测、budget breakdown 预算分解、comparison 场景对比定义在 server/src/vizTools.ts作为backendTools传给 AG-UI 适配器适配器把每次调用以TOOL_CALL_*事件流式推送到浏览器前端 web/src/viz/renderers.tsx 中的useRenderTool注册把工具调用映射为 React 组件CopilotChat将其内联挂载组件的滑块在客户端重新计算图表纯前端财务数学见 web/src/viz/finance.ts无需再发起 Agent 回合handler 的 ack 回传会话回合继续流动。一个有真实凭据的回合还应该验证会话记忆每个聊天线程映射一个 managed session追问那如果我每月投 1000 呢应能基于上文回答。服务器每次创建新会话时会在日志打印 Console trace URL见 server/src/index.ts 的 sessionStore 包装可以并排观察原始 Agent 活动。Gotchas验证中常见的三个坑SKILL.md 明确记录了三个最容易踩的坑验证时务必对照检查启动强制要求 Agent 身份。要么运行过npm run setup生成了agent-ids.json要么显式设置ANTHROPIC_ENVIRONMENT_ID、ANTHROPIC_AGENT_ID、ANTHROPIC_AGENT_VERSION三个环境变量。两者都缺失是刻意设计的启动失败——loadAgentIds()server/src/setup.ts会抛出No agent configured错误三个变量只设部分同样报错。静态服务仅在web/dist存在时激活。npm start不会自动构建前端所以先npm run build再跑探针否则GET /会 404。补充一个从源码与 CLAUDE.md 中归纳的关联注意点workspace 根 package.json 通过overrides把rxjs钉在 7.8.1——AG-UI 客户端与 CopilotKit runtime 之间交换 RxJS observable若依赖树中出现两份 rxjs 会导致instanceof检查失败。遇到 Observable 相关的 instanceof 报错从 workspace 根重新安装让 overrides 生效。配置速查验证与部署相关的环境变量结合 README.md 的配置表与源码验证/部署相关的变量如下变量作用于默认值说明ANTHROPIC_API_KEYserverant auth login配置文件API 凭据冒烟测试可填sk-ant-test假值ANTHROPIC_ENVIRONMENT_IDserver读自agent-ids.json无持久磁盘平台的环境 IDANTHROPIC_AGENT_IDserver读自agent-ids.jsonAgent ID与其余两个 ID 变量成组设置ANTHROPIC_AGENT_VERSIONserver读自agent-ids.jsonAgent 版本整数非整数启动即报错PORTserver8787runtime 端口ALLOWED_ORIGINSserver放行所有逗号分隔的 CORS 白名单设空 拒绝跨域VITE_COPILOT_RUNTIME_URLweb 构建/api/copilotkit前端单独托管时的 runtime 地址构建期烘焙npm run setup结束时会打印三个ANTHROPIC_*ID 值可直接粘贴到部署平台的 env 配置中三个变量全部设置时优先于agent-ids.jsonserver/src/setup.ts。验证路径背后的源码支撑无凭据探针之所以能以假乱真地验证大部分接线根源在于 server/src/index.ts 的分层设计会话层InMemorySessionStore被包装成自定义SessionStore只为在每个新会话创建时打印 Console trace URLget/set/delete转发给内存实现运行时层CopilotSseRuntime注册ManagedAgentsAgent后者负责 AG-UI 线程 ↔ managed session 的全部翻译——文本增量流、TOOL_CALL_*事件、REASONING_*事件、断线中断、回合时长上限单回合 5 分钟都封装在上游包中本仓库不含任何桥接代码工具层server/src/vizTools.ts 的四个BackendCustomTool是只渲染工具——渲染本身就是结果所以 handler 忽略输入、只返回rendered to the user确认。它们不在setup时注册到 Agent 上而是由适配器在每个会话作为工具覆盖合并进 Agent 自带工具集因此修改工具契约无需重新预置 Agent渲染层web/src/viz/renderers.tsx 对四个可视化工具各注册一个useRenderTool外加一个name: *的通配注册把内置工具调用web_search、bash、文件操作渲染为可折叠的活动行ToolActivity避免工具调用在对话中消失。值得一提的实现细节renderers.tsx用带 coercion 的 zod schema解析工具参数而不是盲目展开props.parameters——因为 CopilotKit runtime 各版本传递工具参数的形状不同typed 对象、数字全字符串化的对象、嵌套数组以 JSON 字符串到达的对象z.coerce负责把字符串化的数字转回数值asRecord/parseStructured负责规整嵌套结构。这正是真实服务器驱动验证优于类型检查的又一例证类型在编译期检查而线格式在运行时才暴露。总结copilot-kit-ag-ui 的验证哲学可以概括为三句话typecheck 不是证据跑起来才是没有凭据也能验证除真实回合外的全部接线有凭据时用一个触发可视化工具的问题即可验证生成式 UI 的完整闭环。按本文的无凭据五探针 有凭据真实对话路径执行配合 Gotchas 清单排查即可在改动后快速、确定地回答这个演示还能端到端跑通吗。【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考