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 叢集上為每個工作階段執行一個沙箱。它的 dispatcher 會輪詢環境的工作佇列,並為每個工作階段提供專屬的 pod:

  • 隔離: 每個 pod 都在 gVisor 下執行,並受到 chart 的網路政策保護。它擁有自己的檔案系統和資源限制。只有 dispatcher 持有環境金鑰。
  • 工作階段親和性: 工作階段中的每則訊息都會傳送到該工作階段的沙箱。在工作階段閒置 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,以及 dispatcher 的 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 的名稱推送到您的 registry,並以 chart 的版本作為標籤。接著,將 image.registry 設定為該 registry。如果您固定映像檔摘要,請使用您自己映像檔的摘要。

限制網路輸出

預設情況下,chart 的網路政策允許沙箱連線到公用 IPv4 網際網路。它們會封鎖私有位址範圍、雲端中繼資料伺服器,以及 egress.clusterCIDRs 中的位址。遭到提示注入的代理可以將其讀取的內容傳送到其沙箱可連線的任何位址。詳細資訊請參閱安裝指南中的 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 設為 entrypoint。沙箱啟動時,會從環境變數讀取工作階段詳細資訊、處理該工作階段,然後結束。基礎映像檔必須提供 /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 entrypoint 替換為 SDK entrypoint。該 entrypoint 會建構 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 路徑或 commit 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,並修正常見的失敗。

這個頁面有幫助嗎?