{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 托管 Agent SDK

> 在生产环境中部署和托管 Claude Agent SDK

Claude Agent SDK 与传统的无状态 LLM API 不同，它维护对话状态并在持久环境中执行命令。本指南涵盖在生产中部署基于 SDK 的智能体的架构、托管注意事项和最佳实践。

<Info>
  有关超越基本沙盒的安全加固（包括网络控制、凭证管理和隔离选项），请参阅[安全部署](/en/agent-sdk/secure-deployment)。
</Info>

## 托管要求

### 基于容器的沙盒

为了安全和隔离，SDK 应在沙盒化的容器环境中运行。这提供了进程隔离、资源限制、网络控制和临时文件系统。

SDK 还支持[编程式沙盒配置](/en/agent-sdk/typescript#sandboxsettings)用于命令执行。

### 系统要求

每个 SDK 实例需要：

* **运行时依赖**
  * Python SDK 需要 Python 3.10+，TypeScript SDK 需要 Node.js 18+
  * 两个 SDK 包都为主机平台捆绑了原生 Claude Code 二进制文件，因此生成的 CLI 不需要单独安装 Claude Code 或 Node.js

* **资源分配**
  * 推荐：1GiB RAM、5GiB 磁盘和 1 个 CPU（根据需要根据您的任务调整）

* **网络访问**
  * 出站 HTTPS 到 `api.anthropic.com`
  * 可选：访问 MCP 服务器或外部工具

## 了解 SDK 架构

与无状态 API 调用不同，Claude Agent SDK 作为一个**长时间运行的进程**运行，它：

* 在持久 shell 环境中**执行命令**
* 在工作目录内**管理文件操作**
* 使用先前交互的上下文**处理工具执行**

## 沙盒提供商选项

多家提供商专门提供用于 AI 代码执行的安全容器环境：

* **[Modal Sandbox](https://modal.com/docs/guide/sandbox)** - [演示实现](https://modal.com/docs/examples/claude-slack-gif-creator)
* **[Cloudflare Sandboxes](https://github.com/cloudflare/sandbox-sdk)**
* **[Daytona](https://www.daytona.io/)**
* **[E2B](https://e2b.dev/)**
* **[Fly Machines](https://fly.io/docs/machines/)**
* **[Vercel Sandbox](https://vercel.com/docs/functions/sandbox)**

有关自托管选项（Docker、gVisor、Firecracker）和详细的隔离配置，请参阅[隔离技术](/en/agent-sdk/secure-deployment#isolation-technologies)。

## 生产部署模式

### 模式 1：临时会话

为每个用户任务创建新容器，完成后销毁。

最适合一次性任务，用户可以在任务完成期间与 AI 交互，但完成后容器即被销毁。

**示例：**

* Bug 调查与修复：使用相关上下文调试和解决特定问题
* 发票处理：从收据/发票中提取和结构化数据以用于会计系统
* 翻译任务：在语言之间翻译文档或内容批次
* 图像/视频处理：对媒体文件应用转换、优化或提取元数据

### 模式 2：长时间运行的会话

为长时间运行的任务维护持久的容器实例。通常根据需求在容器内运行*多个* Claude Agent 进程。

最适合主动采取行动而无需用户输入的智能体、提供内容的智能体或处理大量消息的智能体。

**示例：**

* 邮件智能体：监控传入邮件并根据内容自主分类、响应或采取行动
* 网站构建器：通过容器端口为每个用户托管具有实时编辑功能的自定义网站
* 高频聊天机器人：处理来自 Slack 等平台的持续消息流，其中快速响应时间至关重要

### 模式 3：混合会话

临时容器注入历史和状态，可能来自数据库或 SDK 的会话恢复功能。

最适合与用户间歇性交互的容器，启动工作并在工作完成后停止，但可以继续。

**示例：**

* 个人项目经理：帮助管理进行中的项目，间歇性检查，维护任务、决策和进度的上下文
* 深度研究：进行多小时的研究任务，保存发现并在用户返回时恢复调查
* 客户支持智能体：处理跨多次交互的支持工单，加载工单历史和客户上下文

### 模式 4：单一容器

在一个全局容器中运行多个 Claude Agent SDK 进程。

最适合必须紧密协作的智能体。这可能是最不受欢迎的模式，因为您需要防止智能体相互覆盖。

**示例：**

* **模拟**：在视频游戏等模拟中相互交互的智能体。

## 常见问题

### 如何与沙盒通信？

在容器中托管时，暴露端口以与 SDK 实例通信。您的应用程序可以为外部客户端暴露 HTTP/WebSocket 端点，同时 SDK 在容器内部运行。

### 托管容器的成本是多少？

服务智能体的主要成本是令牌；容器根据您的配置而异，但最低成本大约为每小时运行 5 美分。

### 何时应关闭空闲容器 vs 保持其热状态？

这可能取决于提供商，不同的沙盒提供商允许您设置不同的空闲超时标准，之后沙盒可能会停止。

您需要根据用户响应频率来调整此超时。

### 应多久更新一次 Claude Code CLI？

Claude Code CLI 使用语义版本控制，因此任何破坏性变更都会有版本控制。

### 如何监控容器健康和智能体性能？

由于容器只是服务器，您用于后端的相同日志记录基础设施将适用于容器。

### 智能体会话可以运行多长时间才会超时？

智能体会话不会超时，但考虑设置 `maxTurns` 属性以防止 Claude 陷入循环。

## 后续步骤

* [安全部署](/en/agent-sdk/secure-deployment) - 网络控制、凭证管理和隔离加固
* [TypeScript SDK - 沙盒设置](/en/agent-sdk/typescript#sandboxsettings) - 以编程方式配置沙盒
* [会话指南](/en/agent-sdk/sessions) - 了解会话管理
* [权限](/en/agent-sdk/permissions) - 配置工具权限
* [成本跟踪](/en/agent-sdk/cost-tracking) - 监控 API 使用
* [MCP 集成](/en/agent-sdk/mcp) - 使用自定义工具扩展