Claude Agent接入Chat SDK：无需自建会话库

结论先行

Anthropic 最近在 anthropics/claude-quickstarts 仓库的 managed-agents/chat-sdk 示例中，展示了如何把 Claude Managed Agents 与 Vercel Chat SDK 组合使用。这套架构的核心变化是：聊天界面只管接入用户，Agent 的循环控制、会话保持、沙箱检索、压缩和可选记忆全部由服务端承担，应用侧不需要再为每个聊天软件维护一套会话状态。

具体来说，Chat SDK 提供类型安全的 onDirectMessage 处理器和覆盖 Slack、Teams、Discord、网页等十余个平台的适配器；Managed Agents 负责 Agent 循环、沙箱检索、自动压缩和可选记忆。网页端 useChat 的会话 ID 直接对应 Managed Agents 的 session ID，服务端可以不落盘对话正文。使用网页适配器时，不需要注册第三方应用、验证 webhook 或开隧道，认证只需要 Anthropic 登录态或 API key。

聊天层与 Agent 层解耦

这个结构可以比作前台和后厨。Chat SDK 是前台，负责各聊天平台的接入和消息格式转换；Managed Agents 是后厨，负责真正执行工具调用和维持 session 上下文。过去为 Slack、Discord、Teams 分别写线程状态、验签、网关和流式输出的重复工作，现在被抽象成适配器。官方说法是提供了一个类型安全 handler 和 15+ 适配器，Vercel 还给了 Slack 研究 Bot 模板，同一套 Agent 逻辑改几行就能搬到其他渠道。

解耦之后有几个直接收益：

• 追问时不需要客户端把上下文再传一遍，服务端 session 保留了检索材料。
• 侧边栏的会话列表来自 sessions API，历史回放用 event log。
• 压缩和 prompt caching 发生在 session 内部，不需要应用层拼消息数组。

风险点是 session 所有权在服务端，应用一旦把 ID 映射错，用户看到的就是空会话。

会话 ID 就是会话本身

网页 Demo 中，useChat 的 conversation ID 直接复用 Managed Agents 的 session ID。这不是少建一张表那么简单：Agent 在沙箱里检索网页、调用工具甚至写入记忆，这些痕迹全部挂在同一个 session 上。用户第二天回来继续问，Agent 读取的是同一份工作现场，而不是应用从数据库拼出来的摘要。

实现上，示例本地进程包含：

• src/bot.ts：实例化 Chat SDK，实现 getUser，处理进线消息。
• src/managed-agents.ts：把一轮对话交给 Managed Agents 的 turn loop，处理 token 预览并核对 session 归属。
• API 层用 Hono，路由包括 /api/chat、/api/sessions、/api/history、/api/activity。
• Agent 名称、模型和系统提示在 setup/agent-config.ts 配置，修改后运行 npm run update-agent 发布新版本。

需要留意，token 预览是按组织逐步开放的，2026-07-01 的更新之后才陆续放量。如果还没开放，回复会整段落下来，但活动流仍然存在。

由于一轮研究可能耗时较长，/api/chat 需要保持连接直到整轮结束。Hono 应用本身部署在哪都行，但必须让函数时长够用。Vercel 上建议把页面和 API 拆开，用 vercel.json 将 /api/* 代理到独立服务，并拉长流式响应的超时时间。本地默认监听 127.0.0.1，getUser 是安全边界，Demo 只信任回环地址；没有换成真实会话校验前，不要改成 0.0.0.0。

本地跑通步骤

环境要求：Node.js 22.9 或更高，以及 Anthropic 认证（API key 或 ant auth login）。

1. 进入示例目录并安装依赖：

cd managed-agents/chat-sdk
npm install

2. 复制环境文件：

cp .env.example .env

已执行过 ant auth login 可不填 ANTHROPIC_API_KEY，否则补上。

3. 创建 Agent 与环境：

npm run setup

把输出中的 CLAUDE_AGENT_ID 和 CLAUDE_ENVIRONMENT_ID 填回 .env。

4. 启动开发服务：

npm run dev

打开 http://localhost:3000，请求一份主题 brief。如果看到流式正文和工具轨迹，说明 token 预览已开启；只看到整段回复，多半是组织还没开通预览。

5. 改名或改提示词后：

npm run update-agent

不要重复运行 npm run setup。

可选参数有 <PORT>、<HOST>、<QUICKSTART_MODEL>。端口默认 3000，主机默认回环地址，模型覆盖只在 setup/update-agent 时生效。

自托管沙箱的取舍

如果不想用 Anthropic 官方托管的工具执行环境，社区也存在自托管沙箱方案。anthropics/claude-cookbooks 的 managed_agents/self_hosted_sandboxes/vercel 示例走的是 webhook 路线：

• 验证 Standard Webhooks 签名；
• 拉取 work.poll() 队列，单次最多 25 条；
• 确认后启动 Vercel Sandbox，上传 runner/runner.mjs 并在沙箱内执行；
• 沙箱内使用 EnvironmentWorker.handleItem() 和 betaAgentToolset20260401() 工具集，通过 bash、read、write、edit、glob、grep 访问真实文件系统；
• 工作目录 /mnt/session 和 /workspace 都是临时目录，沙箱停止后数据消失，因为 Vercel Sandbox 没有 volume API。

部署流程是：先 vercel link，写入 ANTHROPIC_WEBHOOK_SECRET、ANTHROPIC_ENVIRONMENT_ID、ANTHROPIC_ENVIRONMENT_KEY，再 vercel deploy --prod，最后把 https://<PROJECT>.vercel.app/api/webhook 登记为 session.status_run_started 回调。控制台签发的 secret 要写回生产环境并重新部署。测试时创建一个指向该 environment 的 session，发一条 ls -la，观察 runner 是否正常启动。

沙箱冷启动加上安装依赖通常需要十几秒到二十多秒，vercel.json 的 maxDuration 建议设为 60。如果接了 Vercel KV，webhook 会保存 session_id → sandbox_id，下一轮 run_started 可以复用仍存活的沙箱并 extendTimeout()；不接 KV 则每次都要新开，虽然能跑但比较浪费。空闲策略沿用 SDK 默认：session.status_idle 且 stop_reason 为 end_turn 后 60 秒退出，其他事件会重置计时。控制面和 runner 共用同一把 environment key，而不是组织级 API key。

选择哪种方式，取决于你能否接受沙箱工作树随虚拟机关闭而消失，以及是否愿意用 KV 来减少冷启动。

上线前注意

网页 Demo 足够用来观察分流和工具轨迹。如果要上 Slack，官方指向 vercel-labs/cma-chat-sdk：用它管理应用凭证，用 Redis 做订阅、去重和 thread 到 session 的映射。注意该模板的运行时要求比 quickstart 的 Node 22.9 更高，环境变量不要混用。

建议先只跑通网页这条线，确认 session ID 对得上，再换适配器。Agent 配置只动 setup/agent-config.ts，聊天面换适配器，工具执行再决定用内置环境还是自建沙箱。三件事分开改，出问题才能快速定位是哪一层。