---
title: 每個工作階段執行一個沙箱
url: https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-per-session
description: 透過 Kubernetes 上的 Helm chart、啟動指令碼或 SDK 輪詢器，為每個工作階段提供其專屬的自行託管沙箱。
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: 不具 ZDR 適用資格，自行託管的 Managed Agents 除外。工作階段是具狀態的資源；對話記錄會保留至您將其刪除為止。
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
---

在「sandbox-per-session」（每個工作階段一個沙箱）模式中，每個工作階段都在全新的沙箱中執行，該沙箱可以擁有自己的檔案系統、資源限制和網路控制。若要將其與其他模式比較，請參閱[選擇部署模式](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern)。

您可以透過三種方式進行設定：

* **[Kubernetes 上的 Helm chart](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes)：** Anthropic 的 dispatcher 會認領工作，並在您的叢集上為每個工作階段啟動一個 pod。
* **[啟動指令碼](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script)：** `ant` CLI 會認領工作並呼叫您的指令碼，由該指令碼在任何平台上啟動沙箱。
* **[SDK 輪詢器](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-from-the-sdk-poller)：** 由您自己的程式碼認領工作並啟動沙箱。

[在 Kubernetes 上執行沙箱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes)之後的各節適用於啟動指令碼和 SDK 輪詢器。

## 在 Kubernetes 上執行沙箱

Anthropic 發佈了一個 Helm chart `cma-sandboxes` 及其映像檔。此 chart 會在您自己的 Kubernetes 叢集上為每個工作階段執行一個沙箱。它的 dispatcher 會輪詢環境的工作佇列，並為每個工作階段提供專屬的 pod：

* **隔離：** 每個 pod 都在 [gVisor](https://gvisor.dev/) 下執行，並受到 chart 的網路政策保護。它擁有自己的檔案系統和資源限制。只有 dispatcher 持有環境金鑰。
* **工作階段親和性：** 工作階段中的每則訊息都會傳送到該工作階段的沙箱。在工作階段閒置 30 分鐘後（chart 的 `sandbox.idleTimeout` 設定的預設值），其 pod 會停止。其 `/workspace` 磁碟區會保留到工作階段結束為止。下一則訊息會在同一個磁碟區上啟動 pod。
* **暖池：** 除了在 Google Kubernetes Engine (GKE) 上以外，chart 會保留兩個就緒的 pod 供新工作階段使用（chart 的 `sandbox.warmPoolSize` 設定的預設值）。

沙箱 pod 執行 `ant` CLI worker。它們支援採用預設同步設定的[記憶儲存區](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory)，但不支援[自訂工具](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-custom-tools)。

### 安裝 chart

此 chart 可在 GKE、Amazon EKS 和其他叢集上執行。安裝前請先設定以下項目：

* **在叢集中：** [Agent Sandbox](https://github.com/kubernetes-sigs/agent-sandbox) 控制器（在 GKE 上為 Agent Sandbox 附加元件）、執行 gVisor 的節點，以及會強制執行 NetworkPolicy 的網路外掛程式。
* **在您自己的命名空間中：** Restricted Pod Security Standard 標籤、包含環境 ID 和[環境金鑰](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes#run-your-first-session)的 Secret，以及 dispatcher 的 TLS 憑證。

[GitHub 上的安裝指南](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md)提供了各類叢集的設定步驟，也涵蓋了升級和金鑰輪替。

將您的設定儲存為 `cma-values.yaml`。若此檔案中缺少這三項設定，安裝將會失敗：

<File filename="cma-values.yaml">
  ```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
  ```
</File>

安裝指南列出了取決於您叢集的設定，例如 GKE Autopilot 上的 `gke.dns`。它也說明了何時應以 `egress.clusterIsPrivate: true` 取代 `egress.clusterCIDRs`。

接著，安裝 chart：

```bash
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
```

安裝完成後，請執行安裝指南所述的預檢檢查。

<Warning>
  請勿單獨使用 `helm uninstall` 移除 chart。該指令會刪除網路政策，使工作階段的沙箱在沒有網路政策的情況下繼續執行。請先停止 dispatcher 並刪除沙箱，順序依照[安裝指南的 Removal 一節](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#removal)所述。
</Warning>

### 在沙箱映像檔中加入工具

已發佈的沙箱映像檔是包含 `bash`、`curl`、`jq` 和 `ant` CLI 的 Alpine Linux。chart 以唯讀根檔案系統及非 root 使用者身分執行它，因此代理無法在工作階段期間安裝套件。

若要為您的代理提供更多工具（例如 Python 或 Git），請從該版本標籤的儲存庫建置兩個映像檔。[安裝指南的 Install 一節](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#install)提供了相關指令。將映像檔以 `cma-dispatcher` 和 `cma-sandbox` 的名稱推送到您的 registry，並以 chart 的版本作為標籤。接著，將 `image.registry` 設定為該 registry。如果您固定映像檔摘要，請使用您自己映像檔的摘要。

### 限制網路輸出

預設情況下，chart 的網路政策允許沙箱連線到公用 IPv4 網際網路。它們會封鎖私有位址範圍、雲端中繼資料伺服器，以及 `egress.clusterCIDRs` 中的位址。遭到提示注入的代理可以將其讀取的內容傳送到其沙箱可連線的任何位址。詳細資訊請參閱安裝指南中的 [Network egress](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#network-egress)。

* **具備 Dataplane V2 的 GKE：** 設定 `egress.mode: fqdnGke`，將連線限制為 `egress.fqdnGke.hosts` 中主機的 443 連接埠。請將 `api.anthropic.com` 保留在該清單中，並加入您代理的指令所需的每個主機。與預設模式不同，此模式沒有封鎖範圍清單。它會允許所列主機名稱解析到的任何位址，因此請只列出您信任其 DNS 的主機。沙箱仍可透過 DNS 查詢向外傳送資料。
* **其他叢集及不具備 Dataplane V2 的 GKE：** 預設模式是唯一的模式。
* **所有叢集：** 網路政策不涵蓋叢集本身節點所監聽的連接埠。請參閱安裝指南中的 [Node isolation you own](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#node-isolation-you-own)。

## 使用啟動指令碼啟動沙箱

主機上的輪詢器會認領工作，並為每個工作項目呼叫一次您的指令碼。該指令碼會為該工作階段啟動一個沙箱。

<Steps>
  <Step title="建置沙箱映像檔">
    安裝 `ant` 並將 `ant beta:worker run` 設為 entrypoint。沙箱啟動時，會從環境變數讀取工作階段詳細資訊、處理該工作階段，然後結束。基礎映像檔必須提供 `/bin/bash`；建置過程僅使用 `curl` 來下載 `ant`。

    <File filename="Dockerfile">
      ```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"]
      ```
    </File>
  </Step>

  <Step title="撰寫啟動指令碼">
    此指令碼會將工作階段詳細資訊轉送到全新的沙箱中。它需要輪詢器主機上有 `jq`。

    <File filename="spawn.sh">
      ```bash
      #!/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
      ```
    </File>

    輪詢器會設定 `ANTHROPIC_WORK_ID`、`ANTHROPIC_ENVIRONMENT_ID`、`ANTHROPIC_SESSION_ID` 和 `ANTHROPIC_ENVIRONMENT_KEY`。只有當您在輪詢器的主機上設定了 `ANTHROPIC_BASE_URL` 時，它才會傳到指令碼。指令碼會從標準輸入上工作項目的 JSON 讀取 `ANTHROPIC_WORK_SECRET`。請參閱[環境變數](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-reference#environment-variables)。

    `/host/outputs` 是您選擇的主機目錄。將其掛載到 `/workspace` 可讓您在沙箱結束後取得工作階段的交付成果。此掛載也會包含下載的 `skills/` 樹狀結構和任何中間檔案。
  </Step>

  <Step title="啟動輪詢器">
    ```bash
    ant beta:worker poll --on-work ./spawn.sh
    ```
  </Step>
</Steps>

## 轉送工作項目的密鑰

每個已認領的工作項目都可以攜帶一個由 Anthropic 為該工作階段核發的 `secret` (csharp, go: `Secret`)。執行該工作階段的 worker 需要它來掛載[記憶儲存區](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory)。

在同一個處理程序中認領並執行工作階段的 worker 會自行傳遞密鑰。搭配 `run()` (go: `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()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`) | 每個已認領工作項目的 `secret` (go: `Secret`) 欄位 | 沙箱環境中的 `ANTHROPIC_WORK_SECRET`，或 `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) 的 `work_secret` (typescript: `workSecret`; go: `WorkSecret`) 引數 |

請只將密鑰傳入服務該工作階段的沙箱，且絕不要將其記錄到日誌中。關於它與環境金鑰的關係，請參閱[安全模型](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-security)。

## 從 SDK 輪詢器啟動沙箱

若要從您自己的程式碼認領工作，而非使用 `ant beta:worker poll --on-work`，請使用 Python、TypeScript 或 Go SDK 中的輪詢器：`work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`)。它會輪詢佇列並將每個已認領的工作階段交給您，由您啟動沙箱：

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    以迴圈認領工作並為每個工作階段啟動沙箱，所需的邏輯超出單一 shell 指令所能處理的範圍。若要從 shell 執行，請搭配啟動指令碼執行 `ant beta:worker poll --on-work`，如[使用啟動指令碼啟動沙箱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script)所示。
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    若要從 shell 認領工作並為每個工作階段啟動沙箱，請搭配啟動指令碼執行 `ant beta:worker poll --on-work`。請參閱[使用啟動指令碼啟動沙箱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script)。
  </CodeGroupItem>

  ```python Python
  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())
  ```

  ```typescript TypeScript
  import { spawn } from "node:child_process";
  import { once } from "node:events";
  import Anthropic from "@anthropic-ai/sdk";
  import { WorkPoller } from "@anthropic-ai/sdk/helpers/beta/environments";
  import type { BetaSelfHostedWork } from "@anthropic-ai/sdk/resources/beta/environments";

  const 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
  ];

  const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
  const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
  const client = new Anthropic({ authToken: environmentKey });

  async function launchContainer(work: BetaSelfHostedWork): Promise<void> {
    console.log(`claimed session ${work.data.id}`);
    // 將 `docker run` 替換為您自己的沙箱啟動器。轉送環境
    // 金鑰（切勿轉送您的 API 金鑰）以及工作項目的每工作階段密鑰：內部的 worker
    // 需要此密鑰才能掛載該工作階段的記憶儲存區。
    const env = {
      ...process.env,
      ANTHROPIC_WORK_ID: work.id,
      ANTHROPIC_SESSION_ID: work.data.id,
      ANTHROPIC_WORK_SECRET: work.secret ?? ""
    };
    const forward = SANDBOX_ENV.flatMap((name) => ["-e", name]);
    const launcher = spawn("docker", ["run", "--rm", "--detach", ...forward, "your-image"], {
      env,
      stdio: "inherit"
    });
    await once(launcher, "close");
  }

  const poller = new WorkPoller({
    client,
    environmentId,
    environmentKey,
    autoStop: false // the launched sandbox owns the stop call
  });

  for await (const work of poller) {
    await launchContainer(work);
  }
  ```

  <CodeGroupItem language="C#">
    C# SDK 沒有輪詢工作的輔助工具。若要從您自己的程式碼認領工作，請呼叫 [Environments Work 端點](https://platform.claude.com/docs/zh-TW/api/beta/environments/work)來輪詢項目並確認它。
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"fmt"
  	"log"
  	"os"
  	"os/exec"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  	"github.com/anthropics/anthropic-sdk-go/v2/packages/param"
  )

  var sandboxEnv = []string{
  	"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
  }

  func launchContainer(ctx context.Context, work *anthropic.BetaSelfHostedWork) error {
  	fmt.Printf("claimed session %s\n", work.Data.ID)
  	// 將 `docker run` 替換為您自己的沙箱啟動器。轉送環境
  	// 金鑰（切勿轉送您的 API 金鑰）以及工作項目的每工作階段密鑰：內部的
  	// worker 需要此密鑰才能掛載工作階段的記憶儲存區。
  	args := []string{"run", "--rm", "--detach"}
  	for _, name := range sandboxEnv {
  		args = append(args, "-e", name)
  	}
  	launcher := exec.CommandContext(ctx, "docker", append(args, "your-image")...)
  	launcher.Env = append(os.Environ(),
  		"ANTHROPIC_WORK_ID="+work.ID,
  		"ANTHROPIC_SESSION_ID="+work.Data.ID,
  		"ANTHROPIC_WORK_SECRET="+work.Secret,
  	)
  	launcher.Stdout, launcher.Stderr = os.Stdout, os.Stderr
  	return launcher.Run()
  }

  func main() {
  	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
  	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")

  	client := anthropic.NewClient(option.WithAuthToken(environmentKey))

  	ctx := context.Background()

  	poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{
  		EnvironmentID:  environmentID,
  		EnvironmentKey: environmentKey,
  		AutoStop:       param.NewOpt(false), // the launched sandbox owns the stop call
  	})
  	defer poller.Close()

  	for work, err := range poller.All() {
  		if err != nil {
  			log.Fatal(err)
  		}
  		if err := launchContainer(ctx, work); err != nil {
  			log.Fatal(err)
  		}
  	}
  }
  ```

  <CodeGroupItem language="Java">
    Java SDK 沒有輪詢工作的輔助工具。若要從您自己的程式碼認領工作，請呼叫 [Environments Work 端點](https://platform.claude.com/docs/zh-TW/api/beta/environments/work)來輪詢項目並確認它。
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    PHP SDK 沒有輪詢工作的輔助工具。若要從您自己的程式碼認領工作，請呼叫 [Environments Work 端點](https://platform.claude.com/docs/zh-TW/api/beta/environments/work)來輪詢項目並確認它。
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Ruby SDK 沒有輪詢工作的輔助工具。若要從您自己的程式碼認領工作，請呼叫 [Environments Work 端點](https://platform.claude.com/docs/zh-TW/api/beta/environments/work)來輪詢項目並確認它。
  </CodeGroupItem>
</CodeGroup>

## 在沙箱內執行 SDK worker

當沙箱必須[提供自訂工具](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-custom-tools)或使用[非預設的記憶同步設定](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory#configure-sync)時，請將 `ant beta:worker run` entrypoint 替換為 SDK entrypoint。該 entrypoint 會建構 `EnvironmentWorker` 並呼叫 `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`)，後者會讀取啟動指令碼所轉送的相同 `ANTHROPIC_*` 變數。

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    worker 是長時間執行的處理程序，而非單一的 HTTP 請求。若要提供自訂工具或變更記憶同步設定，請使用 Python、TypeScript 或 Go SDK 中的 `EnvironmentWorker`。
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    `ant` CLI worker（`ant beta:worker run`）無法提供自訂工具或變更記憶同步設定。若要執行其中任一項，請使用 Python、TypeScript 或 Go SDK 中的 `EnvironmentWorker`。
  </CodeGroupItem>

  ```python Python
  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())
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";
  import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

  const client = new Anthropic({ authToken: process.env.ANTHROPIC_ENVIRONMENT_KEY });
  const controller = new AbortController();
  // 在容器停止時中止，可讓 worker 在結束前上傳已變更的記憶
  // 檔案並移除儲存區目錄。
  process.once("SIGTERM", () => controller.abort());
  process.once("SIGINT", () => controller.abort());

  // 不帶參數時，handleItem() 會讀取啟動指令碼
  // 轉送的 ANTHROPIC_* 變數，包括 ANTHROPIC_WORK_SECRET。
  await new EnvironmentWorker({
    client,
    workdir: "/workspace",
    signal: controller.signal
  }).handleItem();
  ```

  <CodeGroupItem language="C#">
    C# SDK 沒有 `EnvironmentWorker`。
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"log"
  	"os"
  	"os/signal"
  	"syscall"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  )

  func main() {
  	// 在容器停止時取消 context，可讓 worker 上傳
  	// 已變更的記憶檔案，並在結束前移除儲存區目錄。
  	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
  	defer stop()

  	client := anthropic.NewClient(option.WithAuthToken(os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")))
  	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
  		Workdir: "/workspace",
  	})
  	// 使用零值選項時，HandleItem 會讀取啟動指令碼
  	// 轉送的 ANTHROPIC_* 變數，包括 ANTHROPIC_WORK_SECRET。
  	if err := worker.HandleItem(ctx, environments.HandleItemOptions{}); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    Java SDK 沒有 `EnvironmentWorker`。
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    PHP SDK 沒有 `EnvironmentWorker`。
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Ruby SDK 沒有 `EnvironmentWorker`。
  </CodeGroupItem>
</CodeGroup>

## 為工作階段準備檔案

Anthropic 不會將檔案或 GitHub 儲存庫掛載到自行託管的沙箱中。若要提供工作階段專屬的檔案：

1. 在工作階段的 `metadata` (csharp, go: `Metadata`) 欄位中傳遞檔案參照，例如 S3 路徑或 commit SHA。
2. 在您的啟動指令碼或 `--on-work` 處理常式中，取得工作階段（`GET /v1/sessions/{session_id}`）並讀取 `metadata` (csharp, go: `Metadata`)。已認領的工作項目攜帶工作階段 ID，但不包含中繼資料。
3. 在任何工具執行之前，將檔案準備到工作目錄中。

cURL 範例會從 `ANTHROPIC_AUTH_TOKEN` 讀取存取權杖。若要取得權杖，請依照[設定聯合](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation#set-up-federation)所述，以預設的 `workspace:developer` 範圍設定 Workload Identity Federation。接著，依照[從您的工作負載進行驗證](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation#authenticate-from-your-workload)所示，將您工作負載的身分權杖交換為存取權杖。請只在執行 cURL 範例的 shell 中設定 `ANTHROPIC_AUTH_TOKEN`，因為它的優先順序高於您的聯合設定。[身份驗證](https://platform.claude.com/docs/zh-TW/manage-claude/authentication)列出了 API 接受的其他憑證，例如快速入門中的 API 金鑰。

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "environment_id": "env_01595EKxaaTTGwwY3kyXdtbs",
      "metadata": {"input_file": "s3://my-bucket/data.csv"}
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent agent_011CYm1BLqPXpQRk5khsSXrs \
    --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
    --metadata '{"input_file": "s3://my-bucket/data.csv"}'
  ```

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

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

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      Metadata = new Dictionary<string, string> { ["input_file"] = "s3://my-bucket/data.csv" },
  });
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
  	EnvironmentID: environment.ID,
  	Metadata: map[string]string{
  		"input_file": "s3://my-bucket/data.csv",
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .metadata(SessionCreateParams.Metadata.builder()
          .putAdditionalProperty("input_file", JsonValue.from("s3://my-bucket/data.csv"))
          .build())
      .build());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      metadata: ['input_file' => 's3://my-bucket/data.csv'],
  );
  ```

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

## 後續步驟

<CardGroup cols={2}>
  <Card title="監控自行託管的 worker 並進行疑難排解" icon="lightning" href="https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-operations">
    讀取佇列深度、乾淨地停止工作階段和 worker，並修正常見的失敗。
  </Card>
</CardGroup>
