指南

托管 Agent SDK

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

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 陷入循环。

后续步骤

安全部署 - 网络控制、凭证管理和隔离加固
TypeScript SDK - 沙箱设置 - 以编程方式配置沙箱
会话指南 - 了解会话管理
权限 - 配置工具权限
成本跟踪 - 监控 API 使用情况
MCP 集成 - 使用自定义工具进行扩展

Was this page helpful?

指南

托管 Agent SDK

在生产环境中部署和托管 Claude Agent 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 陷入循环。

后续步骤

安全部署 - 网络控制、凭证管理和隔离加固
TypeScript SDK - 沙箱设置 - 以编程方式配置沙箱
会话指南 - 了解会话管理
权限 - 配置工具权限
成本跟踪 - 监控 API 使用情况
MCP 集成 - 使用自定义工具进行扩展

Was this page helpful?