托管 Agent SDK¶

生产环境部署 Agent SDK：子进程架构、会话持久化、扩容、可观测性和多租户隔离，适用于 Docker、Kubernetes 和沙箱提供商。

Agent SDK 生成并管理一个 claude CLI 子进程，该进程拥有 shell、工作目录和磁盘上的会话文件。 托管它不同于托管无状态 API 包装器。每个运行中的 Agent 都是一个与本地状态绑定的长生命期进程，这决定了你如何分配资源、持久化会话和跨租户扩展。

本页涵盖在你自己的基础设施上自托管：理解 子进程模型、选择会话模式、配置容器，以及处理 生产关注点（持久化、可观测性、认证和多租户隔离）。可部署的 Dockerfile 和 Kubernetes manifest 见 托管 cookbook。

如果你不需要基础设施控制、自定义隔离或自有数据面，可以考虑 Managed Agents：Anthropic 托管的 REST API，由 Anthropic 运行 Agent 和沙箱，你的应用只需发送事件和接收流式结果，无需操作托管基础设施。

关于沙箱之外的安全加固（网络控制、凭证管理和隔离选项），见 安全部署。

子进程模型¶

本页所有托管决策都源于 SDK 运行 Agent 的方式。 当你的代码调用 query() 时，SDK 生成一个独立的 claude CLI 进程并通过 stdio 通信。该子进程拥有 shell、工作目录和本地磁盘上的 JSONL 会话 transcript。

一个 Agent 会话对应一个子进程。运行 N 个并发会话意味着 N 个子进程，每个都有自己的进程树和 transcript 文件。默认情况下它们都继承你应用的工作目录，因此当会话需要独立文件系统时在每个 query() 调用上传入 cwd：

query({ prompt, options: { cwd: "/work/session-a" } })

query(prompt=prompt, options=ClaudeAgentOptions(cwd="/work/session-a"))

驻留在本地磁盘的状态¶

三类 Agent 状态默认存在于容器文件系统上。它们都不会在容器重启、缩容或迁移到不同节点后存活。

要跨主机持久化 transcript，配置 SessionStore 适配器。记忆文件和其他工作目录产物需要自己的存储策略，如挂载卷或对象存储同步。

关于会话、恢复和分叉在 API 层面的工作方式，见 Sessions。

选择会话模式¶

以下四种模式涵盖会话生命周期：容器存活时间与其服务的会话之间的关系。 关于容器在哪里运行，托管 cookbook 有针对本地 Docker、Modal 和 Kubernetes 的 可部署代码。在此选择会话模式，从 cookbook 选择部署目标。

临时会话（Ephemeral）¶

为每个用户任务创建容器，任务完成后销毁。 适合一次性任务。用户在任务进行中仍可与 AI 交互，但完成后容器即销毁。

示例负载：bug 调查与修复、发票/收据提取、文档翻译、媒体转换。

容器运行一个调用 SDK 后退出的一次性入口。以下是最小化的 TypeScript 版本：

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = process.env.TASK_PROMPT!;
for await (const message of query({ prompt, options: { maxTurns: 20 } })) {
  console.log(message);
}

长期会话（Long-running）¶

运行持久容器实例，通常每容器托管多个 SDK 进程，服务持续工作。 适合执行自主操作、提供内容或处理高流量消息流的 Agent。

示例负载：分诊和回复来信的邮件 Agent、通过容器端口为用户托管可编辑站点的建站器、处理来自 Slack 等平台持续流量的聊天机器人。

容器暴露 HTTP 或 WebSocket 端点，将每个活跃会话映射到长生命期的 query 及其背后的子进程。TypeScript 中用 streamInput() 向活跃会话添加 turn，用 startup() 在流量到来前预热子进程。Python 中用 ClaudeSDKClient 跨 turn 保持会话打开。调整容器大小以容纳最大并发会话数。

混合会话（Hybrid）¶

临时容器在启动时从 SessionStore 恢复水合，并将更新持久化回去。 适合跨多次交互但在两次交互之间空闲的会话。容器在空闲时缩减，用户返回时重新启动。

示例负载：间歇性签到的个人项目经理、跨数小时暂停和恢复的深度研究、跨交互加载工单历史的客服 Agent。

调整提供商的空闲超时，匹配你预期用户返回的频率。未配置 SessionStore 时缩减容器会丢失 transcript，因此对此模式来说 store 是必需的而非可选的。

此模式的关键在于通过 ID 恢复会话并挂载共享 store：

import { query, type SessionStore } from "@anthropic-ai/claude-agent-sdk";

declare const userInput: string;
declare const sessionId: string;          // 从你的数据库按用户查找
declare const sessionStore: SessionStore; // S3、Redis、Postgres 或你自己的适配器

for await (const message of query({
  prompt: userInput,
  options: { resume: sessionId, sessionStore },
})) {
  // ...
}

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt=user_input,
    options=ClaudeAgentOptions(
        resume=session_id,            # 从你的数据库按用户查找
        session_store=session_store,  # S3、Redis、Postgres 或你自己的适配器
    ),
):
    ...

完整 SessionStore 接口和参考适配器见 Session storage。

多代理容器（Multi-agent）¶

在一个容器内运行多个 SDK 子进程。 适合必须紧密协作的代理，例如代理在共享环境中相互交互的多代理模拟。

给每个代理独立的工作目录以避免互相覆盖文件，隔离设置加载以防单个代理的 CLAUDE.md 文件泄漏到其他代理。具体选项见 多租户隔离。

配置容器¶

基于容器的沙箱¶

在沙箱容器内运行 SDK 以获得进程隔离、资源限制、网络控制和临时文件系统。 多个提供商专门提供适合 Agent SDK 模型的沙箱容器环境。

选择提供商时需要回答的问题：

可评估的提供商：

• Modal Sandbox（附 演示实现）
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

自托管选项如 Docker、gVisor 和 Firecracker，以及详细的隔离配置，见 隔离技术。

运行时依赖¶

容器只需要你 SDK 的语言运行时：

• Python SDK 需要 Python 3.10+，TypeScript SDK 需要 Node.js 18+
• 两个 SDK 包都内置了目标平台的原生 Claude Code 二进制文件，因此子进程无需单独安装 Claude Code 或 Node.js

内置二进制文件锁定到 SDK 包版本，因此更新 SDK 就是更新 CLI。SDK 遵循 semver：持续采用 patch 版本，在采用 minor 版本前审查 TypeScript 或 Python changelog。

资源¶

1 GiB 内存、5 GiB 磁盘和 1 CPU 每代理是新启动实例的合理起点。 内存使用随会话长度和工具活动增长，因此根据你实际需要的会话长度和并发数来规划，而非空闲基线。扩容计算见 扩容与并发。

网络¶

SDK 需要到 api.anthropic.com 的出站 HTTPS 访问，或在 Amazon Bedrock 或 Google Cloud Agent Platform 上运行时需要到提供商区域端点的访问。如果 Agent 使用 MCP 服务器 或外部工具，还需要到这些端点的出站访问。生产环境中，通过出口代理路由出站流量，强制执行域名白名单、注入凭证并记录请求。详见 安全部署。

对于入站流量，在容器上暴露 HTTP 或 WebSocket 端口。你的应用在该端口处理客户端请求并在内部调用 SDK；子进程本身不监听网络。

处理生产关注点¶

在发布自托管 Agent 之前需要处理以下决策。

会话与状态持久化¶

默认本地磁盘在重启、缩容或迁移到不同节点后丢失。 对于用户期望恢复的任何会话，通过 SessionStore 适配器 将 transcript 镜像到持久存储。S3、Redis 和 Postgres 适配器及一致性套件见 参考实现。

SessionStore 行为的三个要点：

可观测性¶

Agent SDK 是长生命期进程，跨多次 API 往返生成工具调用。 没有遥测你无法看到哪些工具运行了、每个花了多长时间、或会话在哪里卡住了。

SDK 从环境继承 OpenTelemetry 配置。在容器或编排器层设置 OTEL 环境变量，每次 query() 调用都会导出 span、metrics 和 log 事件到你的 collector。以下示例为三个信号启用 OTLP 导出。CLAUDE_CODE_ENHANCED_TELEMETRY_BETA 仅 trace 需要；如果只导出 metrics 和 logs 可省略。

CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318

Prompt 文本和工具输入默认不包含在导出中。详见 控制导出中的敏感数据 和 可观测性 完整信号目录。

认证与密钥¶

托管时有三个认证关注点：

扩容与并发¶

每个会话在自己的子进程中运行，因此主机上的并发受限于 RAM 能容纳多少子进程。

每主机容量计算公式：

每主机代理数 = (主机 RAM - 开销) / (每会话 RAM 上限)

通过运行代表性会话到目标长度、在预期工具负载下记录峰值 RSS 来测量每会话上限。资源 中的 1 GiB 起点是下限而非上限。

水平扩展路由取决于你的模式。 对于长期会话（容器承载多个会话），在负载均衡器后运行容器池，通过 sessionId 的一致性哈希将会话固定到某容器。固定的会话持续命中同一容器（同一运行中的子进程），直到被驱逐或容器重启。

单个会话的大规模并发 子代理 扇出可能触发 API 限流。将工作分成较小批次而非一次大范围调度。

成本¶

Anthropic token 成本通常比容器基础设施成本高一个数量级或更多。 最低配置容器约每小时 $0.05，而单个长 Agent 会话可花费数美元的 token。详见 成本追踪。

多租户隔离¶

默认 SDK 行为从文件系统读取设置和 CLAUDE.md 记忆文件。 在服务多租户的共享容器中，这些文件可能将一个租户的上下文泄漏到另一个租户的会话中。

在共享容器内隔离租户的方法：

以下示例同时应用四个 SDK 级选项。构造 tenantDir 和 configDir 使每个租户获得其他租户无法读取的路径。TypeScript 中 env 替换子进程环境，因此展开 ...process.env 以保留 PATH 和 ANTHROPIC_API_KEY 等继承变量。Python 中 env 合并到继承环境之上。

import { query } from "@anthropic-ai/claude-agent-sdk";

declare const prompt: string;
declare const tenantDir: string;
declare const configDir: string;

for await (const message of query({
  prompt,
  options: {
    cwd: tenantDir,
    settingSources: [],
    env: {
      ...process.env,
      CLAUDE_CONFIG_DIR: configDir,
      CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
    },
  },
})) {
  // ...
}

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt=prompt,
    options=ClaudeAgentOptions(
        cwd=tenant_dir,
        setting_sources=[],
        env={
            "CLAUDE_CONFIG_DIR": config_dir,
            "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
        },
    ),
):
    ...

租户级网络控制详见 安全部署。

已知限制¶

在部署设计中规划以下限制：

后续步骤¶

• 托管 cookbook：notebook 演练，附 Docker、Modal 和 Kubernetes 的 可部署代码
• Session storage：通过 SessionStore 适配器跨主机持久化 transcript
• 可观测性：导出 OTEL trace、metrics 和 logs 到你的 collector
• 安全部署：网络控制、凭证管理和隔离加固
• 成本追踪：每会话 token 和成本核算