如何用 deployedApi() 把 Chat SDK × Managed Agents 的 API 核心挂载到非 Node 服务器环境？

如何用 deployedApi() 把 Chat SDK × Managed Agents 的 API 核心挂载到非 Node 服务器环境【免费下载链接】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在 claude-quickstarts 的managed-agents/chat-sdk这个 quickstart 里/api/chat、/api/sessions、/api/history、/api/activity四条路由被写成一个平台中立的 Hono 应用src/app.ts仓库自带的 Node 服务器 src/main.ts 只是它的宿主。当你不想跑这个 Node 进程、而是想把 API 核心挂到任何能运行 fetch handler的服务器上serverless 函数、容器化宿主等时文档给出的路径是用deployedApi()代替api并把聊天页面改为静态服务。本文按 skill.md 与源码注释把这条路径走一遍准备凭据、挂载应用、静态页面配方、时长上限与验证方式。前提本地有 Node 22.9一次性 provisioning 用、Anthropic 凭据以及一个能运行 fetch handler、能设置环境变量或 secrets 的目标宿主。api 与 deployedApi() 的区别两个导出都来自 src/app.ts指向同一个四条路由的 Hono 应用api中间件每请求调用missingConfig()检查CLAUDE_AGENT_ID、CLAUDE_ENVIRONMENT_ID是否已设置且不再是agent_...占位符缺失时返回 500 并在响应体中点名变量Server misconfigured: CLAUDE_AGENT_ID is not set。deployedApi()在api外面多包一层检查——ANTHROPIC_API_KEY与ANTHROPIC_AUTH_TOKENSDK 接受的 bearer 形式都没设时返回 500Server misconfigured: ANTHROPIC_API_KEY is not set然后app.route(/, api)挂上原应用。这层检查存在的原因写在源码注释里本地 Anthropic SDK 能自动发现ant auth login留下的 CLI 凭据而部署宿主上没有凭据文件没有这层检查缺失的 key 会穿过配置守卫、在第一次 SDK 调用深处才失败。deployedApi()让缺配置在门口就以 500 变量名失败。挂载形态可参考 src/main.ts 对应用的消费方式——Node 的serve接收的是fetch: app.fetch。部署宿主上换成deployedApi()外层包装按平台自己的 fetch handler 约定写下式为示意import { deployedApi } from ./app; // 即 managed-agents/chat-sdk/src/app.ts // Hono 应用暴露标准 fetch handlermain.ts 正是把 app.fetch 传给 serve 的 export default { fetch: deployedApi().fetch, };一个来自 src/app.ts 注释的路由细节四条路由自带完整/api/...路径宿主的路由重写必须转发原始请求 URL因此挂载在根路径即可不需要前缀处理。三个变量设为平台配置部署宿主上凭据是平台配置而不是.env。skill.md Deploying off the Node server 一节要求设置ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKENCLAUDE_AGENT_ID、CLAUDE_ENVIRONMENT_ID——两者由一次性的npm run setup打印。先在本地managed-agents/chat-sdk目录完成 provisioning 并做一次本地验证npm install cp .env.example .env # add ANTHROPIC_API_KEY, or skip it after ant auth login npm run setup # one-time: creates the agent environment; prints their IDs npm run dev # open http://localhost:3000确认本地链路先跑通把打印的CLAUDE_AGENT_ID与CLAUDE_ENVIRONMENT_ID填入.env.env.example 中默认是agent_.../env_...占位符missingConfig()会把仍结尾...的值判为未设置再把同名两个值作为 secrets 配到平台上。对宿主有一个硬性要求src/managed-agents.ts 中 Anthropic 客户端在模块作用域构造第 14 行export const client new Anthropic();它在 import 时读process.env。所以所有 secrets 必须在 import 执行前就位——在非 Node 运行时上启用平台的 Node 兼容 env shim。静态服务页面从 bundleApp 提取的 esbuild 配方deployedApi()只覆盖四条/api路由页面资产web/需要静态服务。skill.md 说从 src/main.ts 的bundleApp里提取 esbuild 配方const result await esbuild.build({ entryPoints: [webFile(app.tsx)], // main.ts 中 webFile 解析到 ../web/ 下的文件 bundle: true, format: esm, sourcemap: PRODUCTION ? false : inline, minify: PRODUCTION, // Reacts entry points branch on this at require time; without the // define, the browser bundle would reference a process that isnt there. define: { process.env.NODE_ENV: JSON.stringify(NODE_ENV) }, write: false, });其中process.env.NODE_ENV这条define对 React 是 load-bearing 的去掉它浏览器 bundle 会引用不存在的process。本地main.ts用同样的 bundle 服务三个入口/返回web/index.html、/app.css返回web/app.css、/app.js返回 bundle。静态宿主按同样三个路径提供即可。时长上限/api/chat 的响应会保持数分钟一次 research turn 会把响应保持打开数分钟。仓库的 Node 宿主靠requestTimeout: 0src/main.ts 中禁用 Node 的请求超时处理这一点离开 Node 服务器后要注意两件事前置了反向代理或负载均衡器时为这条路由调高它的 idle/read 超时。否则代理会按自己的默认值常为 60 秒收割安静的响应浏览器会在 brief 即将到达时报网络错误。serverless 宿主的同步函数时长限制通常只有数秒。skill.md 的要求是在依赖它之前先验证平台允许长流式响应否则把 turn 移到队列里处理。访问控制在部署暴露之前先设闸门srс/bot.ts 里的 demogetUser信任每个调用方返回固定的local用户本地默认只绑 loopback 正是这个原因。部署宿主若无保护地暴露 URL任何能触达的人都能用你的账单跑 research turn、列出并回放所有会话。文档给出的顺序是先开启平台的访问保护作为临时闸门直到把getUser换成真实的 session lookup替换后对匿名请求返回null所有会话路由会因此 401并在创建 session 时把解析出的用户 ID 写入 session 的metadata在listSessions/ownedSession里按它过滤做到按用户隔离会话。结果验证配置守卫本身就是第一级冒烟测试三个变量未配齐时任何/api/*请求返回 500响应体点名缺失变量Server misconfigured: ANTHROPIC_API_KEY is not set或CLAUDE_AGENT_ID/CLAUDE_ENVIRONMENT_ID。这是部署宿主期望的失败形态缺配置在门口大声失败而不是死在 SDK 深处。换入真实getUser后匿名请求得到 401。skill.md 的调试表说明demogetUser永远不会 401看到 401 说明你的鉴权路径已生效。然后跑一次真实 turnNew chat就任意主题要一份 brief。期望行为与 skill.md 本地npm run dev检查清单一致——确认宿主先满足允许长流式响应的前提下确认消息acknowledgment数秒内到达activity feed 出现一两分钟的检索活动brief 逐字打出turn 以折叠的工具调用轨迹和Brief ready卡片收尾。运行中遇到下列现象时摘自 skill.md 的调试表现象文档给出的判断ack 到达随后报网络错误而不是 brief浏览器与服务器之间的某个环节收割了长响应。直连服务器或调高代理 idle 超时。turn 仍在服务端完成从侧边栏重新打开会话即可看到回复回复到达但从不过流整段出现组织未开启 session streamingevent_start从不出现或node_modules里的anthropic-ai/sdk早于 0.109.0、不认识event_deltas。其余功能不受影响/api/history对 Console 里可见的 session 返回 404ownedSession拒绝该 session 属于与CLAUDE_AGENT_ID不同的 agent或已归档限制宿主不止一个实例时两处状态是 per-instance 的skill.md 的 Production notes 给出了对应做法activity feed 的扇出在进程内src/activity.ts。宿主若把/api/activity路由到与 turn 的/api/chat不同的实例该 turn 的 feed 是空的——只是表象聊天通道不受影响。Chat SDK 的消息去重活在createMemoryState()里。同一条消息 ID 被重复投递时每次都可能各起一个 turnuseChat每条消息只发一次所以这条只在加重试或第二入口时才咬人修法是createRedisState()设置REDIS_URL。多实例部署时这两项与 sticky sessions把同一会话固定路由到一个实例一起配置。若宿主无法保持长流式响应skill.md 给出的替代路径是 VM 或容器跑npm start把HOST设为绑定地址默认127.0.0.1是有意只绑 loopback以一个长驻进程运行流按 turn 需要保持多久就保持多久。【免费下载链接】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），仅供参考