Claude Platform Docs
Managed Agents自托管沙箱

每个会话运行一个沙箱

通过 Kubernetes 上的 Helm chart、启动脚本或 SDK 轮询器,为每个会话提供其专属的自托管沙箱。

在"sandbox-per-session"(每个会话一个沙箱)模式中,每个会话都在一个全新的沙箱中运行,该沙箱可以拥有自己的文件系统、资源限制和网络控制。要将其与其他模式进行比较,请参阅选择部署模式。

您可以通过三种方式进行设置:

  • Kubernetes 上的 Helm chart: Anthropic 的调度器(dispatcher)认领工作,并在您的集群上为每个会话启动一个 pod。
  • 启动脚本: ant CLI 认领工作并调用您的脚本,由脚本在任意平台上启动沙箱。
  • SDK 轮询器: 由您自己的代码认领工作并启动沙箱。

在 Kubernetes 上运行沙箱之后的各节适用于启动脚本和 SDK 轮询器。

在 Kubernetes 上运行沙箱

Anthropic 发布了一个 Helm chart cma-sandboxes 及其镜像。该 chart 在您自己的 Kubernetes 集群上为每个会话运行一个沙箱。它的调度器轮询环境的工作队列,并为每个会话分配一个专属的 pod:

  • 隔离: 每个 pod 都在 gVisor 下运行,并受 chart 的网络策略保护。它拥有自己的文件系统和资源限制。只有调度器持有环境密钥。
  • 会话亲和性: 会话中的每条消息都会发送到该会话的沙箱。会话空闲 30 分钟后(chart 的 sandbox.idleTimeout 设置的默认值),其 pod 会停止。其 /workspace 卷会一直保留,直到会话结束。下一条消息会在同一个卷上启动一个 pod。
  • 预热池: 除 Google Kubernetes Engine (GKE) 外,chart 会保留两个就绪的 pod 供新会话使用(chart 的 sandbox.warmPoolSize 设置的默认值)。

沙箱 pod 运行 ant CLI worker。它们支持使用默认同步设置的记忆存储,但不支持自定义工具。

安装 chart

该 chart 可在 GKE、Amazon EKS 及其他集群上运行。安装之前,请先完成以下设置:

  • 在集群中: Agent Sandbox 控制器(在 GKE 上为 Agent Sandbox 插件)、运行 gVisor 的节点,以及强制执行 NetworkPolicy 的网络插件。
  • 在您自己的命名空间中: Restricted Pod Security Standard 标签、包含环境 ID 和环境密钥的 Secret,以及调度器的 TLS 证书。

GitHub 上的安装指南提供了每种集群的设置步骤,还涵盖了升级和密钥轮换。

将您的设置保存为 cma-values.yaml。如果此文件中缺少这三项设置,安装将失败:

cma-values.yaml
platform: gke             # or eks, or generic for any other cluster
egress:
  # The chart already blocks the private ranges. List your other addresses
  # that sandboxes must not reach.
  clusterCIDRs:
    - 203.0.113.10/32     # your cluster's Kubernetes API endpoint
  cmaServer:
    public: true          # the Claude API has a public address

安装指南列出了取决于您集群的设置,例如 GKE Autopilot 上的 gke.dns。它还说明了何时用 egress.clusterIsPrivate: true 代替 egress.clusterCIDRs。

然后,安装 chart:

helm install cma \
  oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
  --version 0.1.0 \
  --namespace cma \
  -f cma-values.yaml \
  --wait

安装完成后,运行安装指南中描述的预检检查。

向沙箱镜像添加工具

发布的沙箱镜像是包含 bash、curl、jq 和 ant CLI 的 Alpine Linux。chart 以只读根文件系统和非 root 用户身份运行它,因此智能体无法在会话期间安装软件包。

要为您的智能体提供更多工具(例如 Python 或 Git),请基于该版本标签从仓库构建这两个镜像。安装指南的 Install 部分提供了相关命令。将镜像以 cma-dispatcher 和 cma-sandbox 为名推送到您的镜像仓库,并使用 chart 的版本作为标签。然后,将 image.registry 设置为该镜像仓库。如果您固定了镜像摘要,请使用您自己镜像的摘要。

限制网络出站流量

默认情况下,chart 的网络策略允许沙箱访问公共 IPv4 互联网。它们会阻止私有地址范围、云元数据服务器以及 egress.clusterCIDRs 中的地址。遭受"prompt injection"(提示注入)的智能体可以将其读取的内容发送到其沙箱能够访问的任何地址。安装指南中的 Network egress 提供了详细信息。

  • 启用 Dataplane V2 的 GKE: 设置 egress.mode: fqdnGke,将连接限制为 egress.fqdnGke.hosts 中主机的 443 端口。请在该列表中保留 api.anthropic.com,并添加您的智能体命令所需的每个主机。与默认模式不同,此模式没有阻止范围列表。它允许所列主机名称解析到的任何地址,因此只列出您信任其 DNS 的主机。沙箱仍然可以通过 DNS 查询向外发送数据。
  • 其他集群和未启用 Dataplane V2 的 GKE: 默认模式是唯一的模式。
  • 所有集群: 网络策略不涵盖集群自身节点监听的端口。请参阅安装指南中的 Node isolation you own。

使用启动脚本启动沙箱

主机上的轮询器认领工作,并为每个工作项调用一次您的脚本。该脚本为这一个会话启动一个沙箱。

  1. 构建沙箱镜像

    安装 ant 并将 ant beta:worker run 设置为入口点。沙箱启动时,它会从环境变量中读取会话详细信息,处理该会话,然后退出。基础镜像必须提供 /bin/bash;构建过程仅使用 curl 下载 ant。

    Dockerfile
    FROM your-base-image
    ARG ANT_VERSION=2.11.0
    ARG TARGETARCH
    RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \
        curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \
          | tar -xz -C /usr/local/bin ant
    WORKDIR /workspace
    VOLUME /workspace
    ENTRYPOINT ["ant", "beta:worker", "run"]
  2. 编写启动脚本

    该脚本将会话详细信息转发到一个全新的沙箱中。它要求轮询器主机上安装 jq。

    spawn.sh
    #!/bin/bash
    # spawn.sh:每个已认领的工作项调用一次
    # 已认领的工作项以 JSON 形式通过 stdin 传入。
    ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
    export ANTHROPIC_WORK_SECRET
    mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
    exec docker run --rm \
      -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
      -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
      -e ANTHROPIC_WORK_SECRET \
      -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
      your-image

    轮询器会设置 ANTHROPIC_WORK_ID、ANTHROPIC_ENVIRONMENT_ID、ANTHROPIC_SESSION_ID 和 ANTHROPIC_ENVIRONMENT_KEY。只有当您在轮询器主机上设置了 ANTHROPIC_BASE_URL 时,它才会传递给脚本。脚本从标准输入上工作项的 JSON 中读取 ANTHROPIC_WORK_SECRET。请参阅环境变量。

    /host/outputs 是您选择的主机目录。将其挂载到 /workspace 后,您可以在沙箱退出后取回会话的交付成果。该挂载还会包含下载的 skills/ 目录树以及所有中间文件。

  3. 启动轮询器

    ant beta:worker poll --on-work ./spawn.sh

转发工作项的机密

每个被认领的工作项都可以携带一个 Anthropic 为该会话签发的 secret。运行该会话的 worker 需要它来挂载记忆存储。

在同一进程中认领并运行会话的 worker 会自行传递该机密。使用 run() 的 EnvironmentWorker 就是这样的 worker,不带 --on-work 的 ant beta:worker poll 也是。当您自己的代码位于认领和 worker 之间时,需要由您转发该机密:

您认领工作的方式机密的到达形式传递给 worker 的方式
ant beta:worker poll --on-work脚本标准输入上工作项 JSON 的 secret 字段沙箱环境中的 ANTHROPIC_WORK_SECRET
Python、TypeScript 或 Go SDK 的 work.poller()每个被认领工作项的 secret 字段沙箱环境中的 ANTHROPIC_WORK_SECRET,或 handle_item() 的 work_secret 参数

只将机密传入为该会话服务的沙箱,并且切勿记录它。有关它与环境密钥的关系,请参阅安全模型。

从 SDK 轮询器启动沙箱

要从您自己的代码而不是 ant beta:worker poll --on-work 认领工作,请使用 Python、TypeScript 或 Go SDK 中的轮询器:work.poller()。它轮询队列并将每个被认领的会话交给您,由您启动沙箱:

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork

SANDBOX_ENV = (
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
)


async def launch_container(work: BetaSelfHostedWork) -> None:
    print(f"claimed session {work.data.id}")
    # 将 `docker run` 替换为您自己的沙箱启动器。转发环境
    # 密钥(切勿转发您的 API 密钥)以及工作项的每会话机密:沙箱内的 worker
    # 需要该机密来挂载会话的记忆存储。
    env = os.environ | {
        "ANTHROPIC_WORK_ID": work.id,
        "ANTHROPIC_SESSION_ID": work.data.id,
        "ANTHROPIC_WORK_SECRET": work.secret or "",
    }
    forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
    launcher = await asyncio.create_subprocess_exec(
        "docker", "run", "--rm", "--detach", *forward, "your-image", env=env
    )
    await launcher.wait()


async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key) as client:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

在沙箱内运行 SDK worker

当沙箱必须提供自定义工具或使用非默认的记忆同步设置时,请将 ant beta:worker run 入口点替换为 SDK 入口点。该入口点构造 EnvironmentWorker 并调用 handle_item(),后者读取启动脚本所转发的相同 ANTHROPIC_* 变量。

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


async def main() -> None:
    async with AsyncAnthropic(
        auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    ) as client:
        worker = EnvironmentWorker(client, workdir="/workspace")
        # 不带参数时,handle_item() 会读取启动脚本转发的
        # ANTHROPIC_* 变量,包括 ANTHROPIC_WORK_SECRET。
        task = asyncio.create_task(worker.handle_item())
        # 在容器停止时取消任务,可让 worker 在退出前上传
        # 已更改的记忆文件并删除存储目录。
        loop = asyncio.get_running_loop()
        for signum in (signal.SIGINT, signal.SIGTERM):
            loop.add_signal_handler(signum, task.cancel)
        with contextlib.suppress(asyncio.CancelledError):
            await task


asyncio.run(main())

为会话准备文件

Anthropic 不会将文件或 GitHub 仓库挂载到自托管沙箱中。要提供会话特定的文件:

  1. 在会话的 metadata 字段中传递文件引用,例如 S3 路径或提交 SHA。
  2. 在您的启动脚本或 --on-work 处理程序中,获取会话(GET /v1/sessions/{session_id})并读取 metadata。被认领的工作项携带会话 ID,但不携带元数据。
  3. 在任何工具运行之前,将文件准备到工作目录中。

cURL 示例从 ANTHROPIC_AUTH_TOKEN 读取访问令牌。要获取访问令牌,请按照设置联合中的说明,使用默认的 workspace:developer 范围设置 Workload Identity Federation。然后,按照从您的工作负载进行身份验证中所示,将您工作负载的身份令牌交换为访问令牌。仅在运行 cURL 示例的 shell 中设置 ANTHROPIC_AUTH_TOKEN,因为它的优先级高于您的联合设置。身份验证列出了 API 接受的其他凭据,例如快速入门中的 API 密钥。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

后续步骤

读取队列深度,干净地停止会话和 worker,并修复常见故障。

此页面对您有帮助吗?