Appearance
Claude Agent SDK 不是无状态 API，而是需要持久化 Shell 环境和文件系统的长进程。生产部署必须使用容器沙箱（如 Docker、Modal、E2B），每个 SDK 实例推荐 1GiB RAM、5GiB 磁盘、1 CPU。根据使用场景选择临时会话（一次任务即销毁）、长期会话（高频消息流）、混合会话（从数据库恢复状态）或单容器多代理模式。出站 HTTPS 必须允许 api.anthropic.com，可选连接 MCP 服务器。容器空闲成本约每小时 5 美分，建议设置 maxTurns 防止死循环。
Claude Agent SDK 部署与托管：生产环境配置指南
部署并托管 Claude Agent SDK，使其在生产环境中稳定运行。
Claude Agent SDK 与传统无状态 LLM API 不同，它维护会话状态并在持久化环境中执行命令。本文介绍生产部署 SDK 型代理的架构、托管方案和最佳实践。
关于更高级的沙箱安全加固（包括网络控制、凭据管理、隔离选项），见安全部署。
托管要求
容器沙箱
出于安全隔离需要，SDK 应运行在沙箱化的容器环境中。容器提供进程隔离、资源限制、网络控制和临时文件系统。
SDK 也支持编程式沙箱配置来控制命令执行。
系统需求
每个 SDK 实例需要：
运行时依赖
- Python SDK：Python 3.10+
- TypeScript SDK：Node.js 18+
- 两个 SDK 包都内嵌了对应平台的 Claude Code 原生二进制，因此启动的 CLI 无需额外安装 Claude Code 或 Node.js。
资源分配（推荐，实际按任务调整）
- 内存：1GiB
- 磁盘：5GiB
- CPU：1 核
网络访问
- 出站 HTTPS 到
api.anthropic.com - 可选：访问 MCP 服务器或外部工具
- 出站 HTTPS 到
理解 SDK 架构
与无状态 API 调用不同，Claude Agent SDK 作为长进程运行，具备以下特性：
- 在持久化 Shell 环境中执行命令
- 在工作目录中管理文件操作
- 处理工具调用，并保留之前交互的上下文
沙箱提供商选择
多家服务商提供专为 AI 代码执行设计的容器环境：
如需自托管方案（Docker、gVisor、Firecracker）及详细的隔离配置，见隔离技术。
生产部署模式
模式 1：临时会话
为每个用户任务创建新容器，任务完成后销毁。
适合一次性任务。用户可以在任务执行期间与 AI 交互，但任务结束即销毁容器。
示例：
- 故障排查与修复：调试并解决特定问题，附带上下文
- 发票处理：从收据/发票中提取结构化数据用于会计系统
- 翻译任务：在语言间翻译文档或批量内容
- 图片/视频处理：应用变换、优化或提取媒体文件元数据
模式 2：长期会话
维护持久容器实例用于长期任务。通常在一个容器内根据需求运行多个 Claude Agent 进程。
适合主动采取行动的代理（无需用户输入）、提供内容的代理，或处理大量消息的代理。
示例：
- 邮件代理：监控收件箱，自动分类、回复或根据内容执行操作
- 网站构建器：为用户托管自定义网站，通过容器端口提供实时编辑功能
- 高频聊天机器人：处理来自 Slack 等平台的持续消息流，要求响应速度快
模式 3：混合会话
临时容器，但恢复历史记录和状态——可以从数据库或 SDK 的会话恢复功能中获取。
适合间歇性交互的容器：用户发启任务后容器运行，任务完成则关闭，但后续可以继续。
示例：
- 个人项目管理器：管理持续项目，间歇性检查进度，保持任务、决策和进展的上下文
- 深度研究：进行数小时的研究任务，保存发现，用户返回时继续调查
- 客户支持代理：处理跨多次互动的工单，加载工单历史与客户上下文
模式 4：单容器多代理
在单个全局容器内运行多个 Claude Agent SDK 进程。
适合需要紧密协作的代理。这可能是最不常用的模式，因为你必须防止代理之间互相覆盖。
示例：
- 模拟：代理之间在模拟环境（如视频游戏）中交互
常见问题
怎么与沙箱通信？
托管在容器中时，暴露端口来与 SDK 实例通信。你的应用可以对外暴露 HTTP/WebSocket 端点，SDK 在容器内部运行。
托管一个容器成本多少？
服务代理的主要成本是 token 消耗；容器本身费用取决于你配置的资源，最低大约每小时 5 美分。
什么时候应关闭空闲容器，什么时候保持热启动？
这通常取决于沙箱提供商。不同沙箱提供商允许设置不同的空闲超时策略，超时后沙箱可能被关闭。你需要根据用户响应频率来调整这个超时值。
应该多久更新一次 Claude Code CLI？
Claude Code CLI 使用语义化版本管理，因此破坏性变更会反映在版本号上。
怎么监控容器健康状态和代理性能？
容器本质上就是服务器，使用后端所用的日志基础设施即可监控它。
代理会话运行多久会超时？
代理会话不会主动超时，但建议设置 maxTurns 属性，防止 Claude 陷入死循环。