Claude Agent SDK 与传统的无状态 LLM API 不同，它维护对话状态并在持久化环境中执行命令。本指南涵盖了在生产环境中部署基于 SDK 的代理的架构、托管注意事项和最佳实践。
托管要求
基于容器的沙箱
为了安全性和隔离性，SDK 应在沙箱容器环境中运行。这提供了进程隔离、资源限制、网络控制和临时文件系统。
SDK 还支持用于命令执行的编程式沙箱配置。
系统要求
每个 SDK 实例需要：
-
运行时依赖
- Python 3.10+（用于 Python SDK）或 Node.js 18+（用于 TypeScript SDK）
- Node.js（Claude Code CLI 所需）
- Claude Code CLI：
npm install -g @anthropic-ai/claude-code
-
资源分配
- 推荐：1GiB 内存、5GiB 磁盘空间和 1 个 CPU（根据您的任务需要进行调整）
-
网络访问
- 到
api.anthropic.com的出站 HTTPS - 可选：访问 MCP 服务器或外部工具
- 到
理解 SDK 架构
与无状态 API 调用不同，Claude Agent SDK 作为一个长时间运行的进程运行，它：
- 在持久化 shell 环境中执行命令
- 在工作目录中管理文件操作
- 利用先前交互的上下文处理工具执行
沙箱提供商选项
多家提供商专门提供用于 AI 代码执行的安全容器环境：
有关自托管选项（Docker、gVisor、Firecracker）和详细的隔离配置，请参阅隔离技术。
生产部署模式
模式 1：临时会话
为每个用户任务创建一个新容器，完成后销毁。
最适合一次性任务，用户在任务完成期间仍可与 AI 交互，但一旦完成，容器即被销毁。
示例：
- Bug 调查与修复：使用相关上下文调试和解决特定问题
- 发票处理：从收据/发票中提取和结构化数据，用于会计系统
- 翻译任务：在语言之间翻译文档或内容批次
- 图像/视频处理：对媒体文件应用转换、优化或提取元数据
模式 2：长时间运行会话
为长时间运行的任务维护持久化容器实例。通常根据需求在容器内运行_多个_ Claude Agent 进程。
最适合无需用户输入即可主动采取行动的代理、提供内容的代理或处理大量消息的代理。
示例：
- 邮件代理：监控收到的邮件，并根据内容自主分类、回复或采取行动
- 网站构建器：为每个用户托管自定义网站，通过容器端口提供实时编辑功能
- 高频聊天机器人：处理来自 Slack 等平台的持续消息流，快速响应时间至关重要
模式 3：混合会话
使用历史记录和状态填充的临时容器，可能来自数据库或 SDK 的会话恢复功能。
最适合用户间歇性交互的容器，用户启动工作，工作完成后容器关闭，但可以继续。
示例：
- 个人项目经理：通过间歇性检查帮助管理正在进行的项目，维护任务、决策和进度的上下文
- 深度研究：执行数小时的研究任务，保存发现并在用户返回时恢复调查
- 客户支持代理：处理跨多次交互的支持工单，加载工单历史和客户上下文
模式 4：单容器
在一个全局容器中运行多个 Claude Agent SDK 进程。
最适合需要紧密协作的代理。这可能是最不常用的模式，因为您需要防止代理之间相互覆盖。
示例：
- 模拟：在视频游戏等模拟中相互交互的代理。
常见问题
如何与沙箱通信？
在容器中托管时，暴露端口以与 SDK 实例通信。您的应用程序可以为外部客户端暴露 HTTP/WebSocket 端点，而 SDK 在容器内部运行。
托管容器的成本是多少？
我们发现服务代理的主要成本是 token，容器成本因您的配置而异，但最低成本大约为每小时运行 5 美分。
何时应该关闭空闲容器而不是保持预热？
这可能取决于提供商，不同的沙箱提供商允许您设置不同的空闲超时标准，超时后沙箱可能会关闭。 您需要根据预期的用户响应频率来调整此超时时间。
应该多久更新一次 Claude Code CLI？
Claude Code CLI 使用 semver 版本控制，因此任何破坏性更改都会进行版本控制。
如何监控容器健康状况和代理性能？
由于容器本质上就是服务器，您用于后端的相同日志基础设施也适用于容器。
代理会话在超时前可以运行多长时间？
代理会话不会超时，但我们建议设置 ‘maxTurns’ 属性以防止 Claude 陷入循环。