Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
預設情況下，Managed Agents 會在 Anthropic 管理的雲端沙箱內執行工具和程式碼。自架沙箱（self-hosted sandbox）將協調工作保留在 Anthropic 端，但將工具執行移至您控制的基礎設施中，因此代理程式的程式碼、檔案系統和網路出口流量永遠不會離開您的環境。
工具執行保留在您的主機上：代理程式讀寫的檔案系統、其產生的程序，以及其可存取的網路都在您的控制之下。工具的輸入和輸出仍會流向 Anthropic 的控制平面（Claude 執行的地方），以便模型可以看到結果並決定下一步該做什麼。請參閱安全模型以了解完整的資料流邊界。
自架沙箱支援 Managed Agents 中所有可用的 Claude 模型，包括 Claude Opus 4.8。模型是在代理程式上設定的，而不是在環境上。
| 雲端環境 | 自架沙箱 | |
|---|---|---|
| 工具執行位置 | Anthropic 管理的沙箱 | 您的基礎設施 |
| 網路可及範圍 | Anthropic 的出口控制 | 您的網路政策 |
| 檔案和 GitHub 儲存庫掛載 | 由 Anthropic 管理 | 由您管理 |
| 生命週期 | 由 Anthropic 管理 | 由您管理 |
當代理程式需要操作無法離開您網路邊界的資料、存取無法公開路由的內部服務，或在您組織自己的合規和稽核控制下執行時，自架是一個很好的選擇。
關於零資料保留（Zero Data Retention）和 HIPAA BAA 資格，請參閱 API 與資料保留。
自架控制的是代理程式的程式碼在哪裡執行。MCP 通道控制的是 Anthropic 如何存取您網路中的 MCP 伺服器。兩者是獨立的：在 Anthropic 雲端沙箱中執行的工作階段仍然可以透過通道存取私有 MCP 伺服器，而自架工作階段可以使用通道式或公開的 MCP 伺服器。當您希望執行和工具存取都保留在您的邊界內時，請同時使用兩者。
本指南說明如何使用任何通用沙箱平台建置工作程式（worker）。另有針對特定平台的指南可供參考：AWS Lambda MicroVMs、Blaxel、Cloudflare、Daytona、E2B、GKE Agent Sandbox、Modal、Namespace、Superserve 和 Vercel。
環境工作程式（environment worker）是您在自己的基礎設施上執行的程序。它從 Anthropic 接收工具執行請求並在本機執行。self_hosted 環境充當工作佇列：當工作階段被指派給它時，Anthropic 會將該工作階段作為工作項目加入佇列。您的工作程式從該佇列中認領工作項目，為每個項目產生執行上下文，下載代理程式的技能（可重複使用、基於檔案系統的資源，為代理程式提供特定領域的專業知識），執行工具呼叫，並將結果回傳。
工作項目是透過輪詢環境的佇列來認領的：可以由持續輪詢的常駐工作程式（always-on worker）認領，或由在 session.status_run_started 時喚醒並開始輪詢的 webhook 觸發處理程式認領。
CLI 和 SDK 都附帶預先建置的工作程式。ant CLI 僅支援常駐模式；SDK 同時支援常駐和 webhook 觸發模式。兩者都可設定：請參閱參考文件中的自架工作程式以了解 CLI 旗標，以及本頁的 SDK 輔助工具以了解 SDK 選項。如需更多控制，請直接呼叫 Environments Work 端點並實作您自己的工作程式。
/workspace：**工具執行和技能下載的系統預設工作目錄。CLI 的 --workdir 旗標預設為目前目錄；傳入 --workdir /workspace 以符合系統預設值。技能會下載到 <workdir>/skills/<name>/。如果您使用不同的工作目錄，請更新代理程式的系統提示，以便 Claude 可以找到技能檔案。/mnt/session/outputs：**工作程式框架會指示 Claude 將最終交付成果寫入此處。在沙箱模式下，將主機目錄掛載到此路徑，以便在工作階段結束後取得輸出。在程序內（in-process）模式下，工作程式的檔案工具會改為寫入工作目錄下，因此此路徑不適用。您需要：
/bin/bash 位於該確切路徑。工作程式的 bash 工具會直接呼叫它，而不會查詢 PATH。TypeScript SDK 另外需要 PATH 上有 unzip 和 tar，以及 Node.js 22 或更新版本；Python 和 Go SDK 使用其標準函式庫進行封存檔解壓縮，沒有額外的二進位檔需求。ant CLI 或 Anthropic SDK（Python、TypeScript 或 Go）。在 Claude Platform on AWS 上，工作程式使用 AWS IAM（SigV4）或在 AWS Console 中產生的 API 金鑰進行驗證，而不是環境金鑰。將 AnthropicSelfHostedEnvironmentAccess 受管政策附加到您的工作程式執行時所使用的 IAM 主體。在 Claude Console 中產生的環境金鑰無法用於 Claude Platform on AWS 端點。
技能可以包含代理程式可能直接執行的可執行檔。CLI 和 SDK 工作程式在解壓縮技能套件時會保留其中記錄的可執行權限。如果您手動實作技能下載，則您需要負責設定可執行權限。
選擇常駐模式以獲得最簡單的設定：一個長時間執行的程序持續輪詢佇列，且只需要對外的 HTTPS。選擇 webhook 觸發模式以避免執行閒置的輪詢程式；它需要一個 Anthropic 可以存取的 webhook 端點（請參閱 Webhooks 以了解端點設定和簽章驗證）。
SDK 提供三種不同控制層級的輔助工具。EnvironmentWorker 涵蓋大多數使用情境；當您需要啟動自己的每工作階段程序，或對已認領的工作階段執行工具時，可降級使用較低層級的輔助工具。
EnvironmentWorker：**開箱即用的工作程式。端到端處理輪詢、設定和執行。
.run()：無限期執行，在工作階段到達時接收它們。.handle_item()：處理單一已認領的工作項目然後結束。明確傳入工作、工作階段和環境識別碼，或讓它讀取 ant beta:worker poll --on-work 為其產生的程序所設定的 ANTHROPIC_* 變數。work.poller()：**代表您輪詢工作佇列，並將每個已認領的工作階段交給您。當您想要決定每個工作階段要做什麼時使用此工具，例如啟動沙箱而不是在程序內執行工具。
drain：是否在佇列清空後停止輪詢，而不是等待新工作。當您想要啟動自己的每工作階段程序時，請直接使用工作輪詢程式，例如為每個已認領的工作階段啟動一個沙箱：
AgentToolContext 是工具呼叫的執行上下文。它定義工作目錄和路徑政策，並可以下載工作階段的技能。beta_agent_toolset_20260401(env) 接受一個 AgentToolContext 並回傳標準工具實作（bash、read、write、edit、glob、grep）。
**使用 EnvironmentWorker：**兩者都會自動管理。傳入 tools 工廠函式以自訂工具清單：
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])**使用 work.poller() 和 tool_runner()：**將工具清單作為 tools 傳給 client.beta.sessions.events.tool_runner()。要建立該清單，請自行設定 AgentToolContext 並呼叫 beta_agent_toolset_20260401(env)：
從另一個 shell 中，將 ANTHROPIC_API_KEY 設定為您的 Claude API 金鑰（不是環境金鑰），確認 workers_polling 至少為 1：
ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"如果 workers_polling 保持為 0，表示工作程式無法連線到佇列：請確認工作程式主機上已設定 ANTHROPIC_ENVIRONMENT_KEY 和 ANTHROPIC_ENVIRONMENT_ID。請參閱讀取佇列深度以了解完整的統計資料回應和其他語言範例。
工作程式執行後，建立一個以該環境為目標的工作階段。將 AGENT_ID 設定為您在開始之前中記下的代理程式 ID。工作階段會進入環境的工作佇列並在那裡等待，直到有工作程式認領它；如果沒有工作程式連線，工作階段會保持在佇列中而不會失敗。
Anthropic 不會將檔案或 GitHub 儲存庫掛載到自架沙箱中。若要提供工作階段特定的檔案，請在工作階段的 metadata 欄位中傳入檔案參照（例如 S3 路徑或 commit SHA）。您的產生指令碼或 --on-work 處理程式會從已認領的工作項目中讀取該中繼資料（CLI 輪詢程式會將工作項目的 JSON 透過管道傳送到指令碼的 stdin，而 SDK 處理程式可以透過 Environments Work 端點讀取它），並在工具執行開始之前將檔案暫存到工作目錄中。
記憶目前不支援自架沙箱。
請參閱參考文件中的自架工作程式以了解完整的 CLI 旗標清單，以及 SDK 輔助工具以了解 SDK 輔助工具選項。
這些呼叫從您的監控或維運工具執行，使用您的 Claude API 金鑰進行驗證，以觀察和管理工作程式叢集。認領和保持連線（keep-alive）迴圈由工作程式輔助工具內部處理，因此您不需要直接呼叫這些端點。
這些端點使用您的組織 API 金鑰進行驗證，而不是環境金鑰。請從工作程式主機外部呼叫它們。在工作程式主機上設定 ANTHROPIC_API_KEY 會將組織範圍的憑證暴露給代理程式的工具呼叫。
work.stats 回傳環境的佇列狀態：
depth 是等待被認領的項目數量。根據此值擴展您的工作程式叢集或針對積壓發出警報。pending 是工作程式已認領且目前正在處理的項目數量。oldest_queued_at 是仍在佇列中或正在處理的最舊項目的時間戳記，若沒有則為 null。workers_polling 是在過去 30 秒內進行過輪詢的工作程式數量。使用此值進行存活性警報。{
"type": "work_queue_stats",
"depth": 0,
"pending": 0,
"oldest_queued_at": null,
"workers_polling": 0
}使用 work.stop 要求處理特定工作階段的工作程式乾淨地關閉它。工作程式會完成任何進行中的工具呼叫、發送最終狀態，並釋放工作階段。在請求主體中傳入 force: true（使用 CLI 時，傳入 --force）以立即中斷，而不是等待目前的工具呼叫完成。
由於這些呼叫是從您的維運工具而非工作程式主機執行的，ANTHROPIC_WORK_ID 不會自動設定。在執行以下範例之前，請將其設定為目標工作項目的 ID。若要尋找工作項目的 ID，請透過 Environments Work 端點列出環境的工作項目。
自架沙箱環境的共同責任模型。
建立工作階段以執行您的代理程式並開始執行任務。
安全地將 Claude 連接到在您私有網路中執行的 MCP 伺服器，無需開放入站連接埠或將服務暴露到公開網際網路。
Was this page helpful?
建立自架環境
在 Console 中：Workspace > Environments > New > Self-hosted
或透過 API：
client = anthropic.Anthropic()
environment = client.beta.environments.create(
name="self-hosted", config={"type": "self_hosted"}
)
print(environment.id)產生環境金鑰
在 Console 中，開啟該環境並點擊 Generate environment key。無論您是透過 Console 還是 API 建立環境，金鑰產生都僅限於 Console。然後在工作程式主機上匯出環境 ID 和金鑰：
export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
export ANTHROPIC_ENVIRONMENT_ID="env_..."安裝 ant CLI
在工作程式主機上執行此操作。
對於 Linux 環境，直接下載發行版二進位檔。
VERSION=1.15.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
x86_64) ARCH=amd64 ;;
aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
| sudo tar -xz -C /usr/local/bin ant您可以在 GitHub 發行頁面上找到所有發行版。
執行工作程式
程序內（In-process）
ant beta:worker poll 會認領指派給該環境的工作項目、下載技能、在工作目錄中執行工具呼叫，並將結果回傳。它會從環境變數中讀取 ANTHROPIC_ENVIRONMENT_KEY 和 ANTHROPIC_ENVIRONMENT_ID。
ant beta:worker poll \
--workdir "/workspace"工作程式在收到 SIGTERM 或 SIGINT 時會乾淨地結束，在停止前會先完成進行中的工具呼叫。
每個工作階段一個沙箱
如果您需要更強的隔離（全新的檔案系統、資源限制或每個工作階段的網路控制），請在各自的沙箱中執行每個工作階段。建置一個安裝了 ant 的映像檔，並以 ant beta:worker run 作為進入點。基礎映像檔必須提供 /bin/bash；curl 僅在建置時使用。當沙箱啟動時，它會從環境變數讀取工作階段詳細資訊、處理該工作階段，然後結束：
FROM your-base-image
ARG ANT_VERSION=1.15.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 /mnt/session/outputs
ENTRYPOINT ["ant", "beta:worker", "run"]然後撰寫一個產生指令碼（spawn script），將工作階段詳細資訊轉發到全新的沙箱中。輪詢程式會將 ANTHROPIC_SESSION_ID、ANTHROPIC_WORK_ID、ANTHROPIC_ENVIRONMENT_ID 和 ANTHROPIC_ENVIRONMENT_KEY 注入到指令碼的環境中。ANTHROPIC_BASE_URL 是選用的，只有在輪詢程式主機上有設定時才會傳遞；它會覆寫預設的 API 端點。在此範例中，/host/outputs 是您選擇的主機目錄；它會被繫結掛載（bind-mount）到沙箱的 /mnt/session/outputs，以便您在沙箱結束後取得工作階段的交付成果。
#!/bin/bash
# spawn.sh：每個已認領的工作項目會呼叫一次
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 \
-v "/host/outputs/$ANTHROPIC_SESSION_ID":/mnt/session/outputs \
your-image啟動指向該指令碼的輪詢程式：
ant beta:worker poll \
--on-work ./spawn.shblock_msnullNoneparam.Null[int64]()reclaim_older_than_ms：重新認領已被認領但在此毫秒數內從未被確認的工作項目。auto_stop：是否在您的迴圈主體處理完每個工作項目後發送停止訊號。Go 輪詢程式沒有停用選項，總是會發送停止訊號，因此請在迴圈主體中阻塞直到工作階段完成，而不是分離出去。client.beta.sessions.events.tool_runner()：**在給定工作階段 ID 和工具清單的情況下，為單一工作階段執行工具呼叫。當您已經認領了工作且只需要執行層時使用。import asyncio
import os
from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork
async def launch_container(work: BetaSelfHostedWork) -> None:
# 請替換為您自己的每個工作階段沙箱啟動器。將
# ANTHROPIC_ENVIRONMENT_KEY 傳入啟動的沙箱，切勿傳入
# 您的 API 金鑰。
print(f"claimed session {work.data.id}")
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())from anthropic.lib.tools.agent_toolset import (
AgentToolContext,
beta_agent_toolset_20260401,
)
async with AgentToolContext(
workdir="/workspace", client=client, session_id=work.data.id
) as env:
# skills 已下載至 /workspace/skills/<name>/
tools = beta_agent_toolset_20260401(env)session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
metadata={"input_file": "s3://my-bucket/data.csv"},
)import os
import anthropic
client = anthropic.Anthropic()
stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")import os
import anthropic
client = anthropic.Anthropic()
work = client.beta.environments.work.stop(
os.environ["ANTHROPIC_WORK_ID"],
environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)