自架沙箱

預設情況下，Managed Agents 會在 Anthropic 管理的雲端沙箱中執行工具和程式碼。自架沙箱（self-hosted sandboxes）將協調工作保留在 Anthropic 端，但將工具執行移至您控制的基礎設施中，因此代理程式的程式碼、檔案系統和網路出口流量永遠不會離開您的環境。

工具執行保留在您的主機上：代理程式讀寫的檔案系統、它產生的程序，以及它可以存取的網路都在您的控制之下。工具的輸入和輸出仍會流向 Anthropic 的控制平面（Claude 執行的地方），以便模型可以看到結果並決定下一步該做什麼。請參閱安全模型以了解完整的資料流邊界。



與雲端環境的差異

當代理程式需要操作無法離開您網路邊界的資料、存取無法公開路由的內部服務，或在您組織自己的合規和稽核控制下執行時，自架是一個很好的選擇。

關於零資料保留（Zero Data Retention）和 HIPAA BAA 資格，請參閱 API 與資料保留。



何時與 MCP 通道結合使用

自架控制的是代理程式的程式碼在哪裡執行。MCP 通道控制的是 Anthropic 如何存取您網路中的 MCP 伺服器。它們是獨立的：在 Anthropic 雲端沙箱中執行的工作階段仍然可以透過通道存取私有 MCP 伺服器，而自架工作階段可以使用通道式或公開的 MCP 伺服器。當您希望執行和工具存取都保留在您的邊界內時，請同時使用兩者。若要在不執行通道的情況下，讓代理程式使用您網路內 MCP 伺服器的工具，您也可以將伺服器包裝為自訂工具，由您的 worker 提供服務。



環境 worker

環境 worker 是您在自己的基礎設施上執行的程序。它從 Anthropic 接收工具執行請求並在本機執行。self_hosted 環境充當工作佇列：當工作階段被指派給它時，Anthropic 會將該工作階段作為工作項目加入佇列。您的 worker 從該佇列認領工作項目，為每個項目產生執行上下文，下載代理程式的技能（可重複使用、基於檔案系統的資源，為代理程式提供特定領域的專業知識），執行工具呼叫，並將結果回傳。

工作項目是透過輪詢環境的佇列來認領的：可以由持續輪詢的常駐 worker，或由在 session.status_run_started 時喚醒並開始輪詢的 webhook 觸發處理程式來完成。

CLI 和 SDK 都附帶預先建置的 worker。ant CLI 僅支援常駐模式；SDK 同時支援常駐和 webhook 觸發模式。兩者都可以設定：請參閱參考文件中的自架 worker 以了解 CLI 旗標，以及本頁的 SDK 輔助工具以了解 SDK 選項。若需要更多控制，請直接呼叫 Environments Work 端點並實作您自己的 worker。



沙箱檔案系統

• **/workspace：**工具執行和技能下載的系統預設工作目錄。CLI 的 --workdir 旗標預設為目前目錄；傳入 --workdir /workspace 以符合系統預設值。技能會下載到 <workdir>/skills/<name>/。如果您使用不同的工作目錄，請更新代理程式的系統提示，以便 Claude 可以找到技能檔案。
• **輸出：**在自架環境中，工作階段的系統提示會省略 Anthropic 管理沙箱上使用的 /mnt/session/outputs 指示，因此最終交付成果會落在代理程式在您沙箱檔案系統中寫入的任何位置，通常在工作目錄下。



開始之前

您需要：

• **一個現有的代理程式。**如果您還沒有，請先完成快速入門並記下其代理程式 ID。
• 一台 Linux 主機，且 /bin/bash 位於該確切路徑。worker 的 bash 工具會直接呼叫它，而不會查詢 PATH。TypeScript SDK 另外需要 PATH 上有 unzip 和 tar，以及 Node.js 22 或更新版本；Python 和 Go SDK 使用其標準函式庫進行封存檔解壓縮，沒有額外的二進位檔需求。
• ant CLI 或 Anthropic SDK（Python、TypeScript 或 Go）安裝在 worker 主機上。
• **兩個憑證：**環境金鑰（在後續步驟中於 Console 產生）用於向其佇列驗證 worker 身分；您的 Claude API 金鑰（API key）用於從 worker 主機外部建立工作階段和讀取佇列統計資料。金鑰產生僅能在 Console 中進行。



執行 worker

選擇常駐模式以獲得最簡單的設定：一個長時間執行的程序持續輪詢佇列，只需要對外的 HTTPS。選擇 webhook 觸發模式以避免執行閒置的輪詢器；它需要一個 Anthropic 可以存取的 webhook 端點（請參閱 Webhooks 以了解端點設定和簽章驗證）。



SDK 輔助工具

SDK 提供三種不同控制層級的輔助工具。EnvironmentWorker 涵蓋大多數使用案例；當您需要啟動自己的每工作階段程序，或對已認領的工作階段執行工具時，再使用較低層級的輔助工具。

• **EnvironmentWorker：**開箱即用的 worker。端到端處理輪詢、設定和執行。
  • .run()：無限期執行，在工作階段到達時接手處理。
  • .handle_item()：處理單一已認領的工作項目後結束。明確傳入工作、工作階段和環境識別碼，或讓它讀取 ant beta:worker poll --on-work 為其產生的程序所設定的 ANTHROPIC_* 變數。
• **work.poller()：**代您輪詢工作佇列，並將每個已認領的工作階段交給您。當您想決定每個工作階段要做什麼時使用此工具，例如啟動沙箱而不是在程序內執行工具。
  • drain：是否在佇列清空後停止輪詢，而不是等待新工作。
  • block_ms：在返回之前等待工作到達的時間（毫秒）。必須介於 1 到 999 之間（每次輪詢的等待時間；輔助工具會自動重新輪詢）。傳入 null（Python 中為 None，Go 中為 param.Null[int64]()）進行非阻塞檢查；省略此參數則使用預設的 999 毫秒長輪詢。
  • 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())

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)：

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)



驗證 worker 已連線

從另一個 shell，將 ANTHROPIC_API_KEY 設定為您的 Claude API 金鑰（不是環境金鑰），確認 workers_polling 至少為 1：

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

如果 workers_polling 保持為 0，表示 worker 沒有連上佇列：請確認 worker 主機上已設定 ANTHROPIC_ENVIRONMENT_KEY 和 ANTHROPIC_ENVIRONMENT_ID。請參閱讀取佇列深度以了解完整的統計回應和其他語言範例。



啟動工作階段

當您的 worker 執行後，建立一個以該環境為目標的工作階段。將 AGENT_ID 設定為您在開始之前記下的代理程式 ID。工作階段會進入環境的工作佇列，並在那裡等待直到有 worker 認領它；如果沒有 worker 連線，工作階段會保持在佇列中而不會失敗。

Anthropic 不會將檔案或 GitHub 儲存庫掛載到自架沙箱中。若要提供工作階段特定的檔案，請在工作階段的 metadata 欄位中傳入檔案參照（例如 S3 路徑或 commit SHA）。已認領的工作項目不會攜帶工作階段的 metadata，但會攜帶工作階段 ID：您的產生指令碼或 --on-work 處理程式可以取得工作階段（GET /v1/sessions/{session_id}）以讀取 metadata 欄位，然後在工具執行開始之前將檔案準備到工作目錄中。

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

請參閱參考文件中的自架 worker 以了解完整的 CLI 旗標清單，以及 SDK 輔助工具以了解 SDK 輔助工具選項。



從您的沙箱提供自訂工具

自訂工具是由您自己的程式碼執行的工具：代理程式發出 agent.custom_tool_use 事件並等待對應的 user.custom_tool_result。worker 可以就是那段程式碼，而且因為它在您的沙箱內執行，該工具可以存取您為沙箱設定的內部服務、憑證和網路出口流量，僅此而已。環境金鑰授權發佈自訂工具結果，因此您的 Claude API 金鑰不需要放在 worker 主機上。

worker 只會回應向它註冊的工具。在代理程式上宣告但沒有向任何 worker 或用戶端註冊的自訂工具，會讓工作階段以 requires_action 停止原因暫停，直到有東西發佈其結果；請參閱處理自訂工具呼叫以了解事件流程。



將 MCP 伺服器包裝為自訂工具

MCP 連接器從 Anthropic 端連接到 MCP 伺服器，因此伺服器必須公開一個 Anthropic 可以直接或透過 MCP 通道存取的 HTTP 端點。若要使用只有您的網路可以存取的伺服器，請改讓 worker 成為 MCP 用戶端，並將伺服器的工具宣告為自訂工具。MCP 伺服器不需要來自您網路外部的入站連線；Anthropic 會收到您在代理程式上宣告的工具定義、每次呼叫的輸入，以及您的 worker 回傳的結果。在執行時，模型會像呼叫任何其他自訂工具一樣呼叫被包裝的工具：

1. 代理程式發出 agent.custom_tool_use 事件。
2. 在您沙箱內的 worker 透過其開啟的 MCP 工作階段，將呼叫轉發到您網路上的伺服器。
3. worker 將伺服器的回應作為 user.custom_tool_result 發佈。

SDK 的用戶端 MCP 輔助工具會將伺服器的工具轉換為 worker 接受的可執行工具；請在 Anthropic SDK 旁安裝 MCP SDK（pip install "anthropic[mcp]" "mcp>=1.24"、npm install @modelcontextprotocol/sdk、go get github.com/modelcontextprotocol/go-sdk）。範例在沒有驗證的情況下連線；若要傳送憑證，請設定您交給 MCP 傳輸層的 HTTP 用戶端或請求選項（Python 中為 http_client，TypeScript 中為 requestInit，Go 中為 HTTPClient）。

包裝 MCP 伺服器時請注意以下事項：

• **工具是宣告的，而不是在執行時探索的。**worker 在啟動時列出 MCP 伺服器的工具一次，無法向執行中的工作階段新增工具。當伺服器的工具變更時，請在代理程式上或透過更新代理程式設定在閒置的工作階段上重新宣告它們，然後重新啟動 worker。
• **名稱和描述必須符合 Managed Agents API。**自訂工具名稱在每個代理程式中是唯一的，並使用字母、數字、底線和連字號（1–128 個字元）；描述是必填的（1–4,096 個字元）；代理程式的 tools 陣列最多接受 128 個項目（每個被包裝的工具是一個項目，內建工具集再算一個）。API 會拒絕重複使用工具名稱、以內建代理程式工具（如 bash 或 read）命名自訂工具，或使用保留的 mcp__ 前綴的宣告。MCP 輔助工具會保留伺服器的名稱和描述，因此請視需要重新命名或修剪。當兩個伺服器公開相同的工具名稱時，請自行以帶前綴的名稱定義包裝器，並讓它呼叫伺服器的原始工具名稱。
• **大多數 schema 可以原樣通過。**API 接受 MCP 伺服器常見發出的 JSON Schema 關鍵字，例如 additionalProperties 和 title。它會拒絕自訂工具 input_schema 中任何位置的參照關鍵字（如 $ref），因此請將 pydantic 等產生器分解到 $defs 中的 schema 內聯展開。它也會拒絕頂層的 oneOf、anyOf 和 allOf，以及不在字母、數字、底線、點和連字號範圍內的屬性名稱（1–64 個字元）。
• **工具失敗會以錯誤工具結果呈現。**當 MCP 伺服器回報工具錯誤時，worker 會發佈一個模型可以回應的錯誤工具結果。沒有對應工具結果的 MCP 內容（例如音訊區塊和資源連結）也會以錯誤呈現。請在 MCP 用戶端上設定逾時以獲得更快、更清楚的失敗訊息，如 Python worker 範例中使用 read_timeout_seconds 所做的那樣。如果沒有設定，掛起的呼叫只有在 TypeScript MCP SDK 的預設請求逾時觸發時（約一分鐘），或 worker 自己的後備機制觸發時才會變成錯誤結果：Python 中約兩分半鐘，Go 中為兩分鐘，worker 會取消超過其 120 秒預設值的工具呼叫並發佈錯誤結果。
• **只包裝您營運或信任的伺服器。**被包裝工具的名稱、描述和結果會像任何其他工具一樣進入模型的上下文：不受信任的輸入可能會影響代理程式使用其他工具（包括 worker 主機上的 bash）的行為。只宣告您打算讓代理程式使用的工具。
• 權限政策不適用於自訂工具。權限政策管理內建和 MCP 工具集；worker 會執行模型發出的每個被包裝工具呼叫，因此請將任何核准步驟放在您自己的工具程式碼中。



監控與營運

這些呼叫從您的監控或營運工具執行，使用您的 Claude API 金鑰進行驗證，以觀察和管理 worker 機群。認領和保持連線的迴圈由 worker 輔助工具內部處理，因此您不需要直接呼叫那些端點。



讀取佇列深度

work.stats 回傳環境的佇列狀態：

• depth 是等待被認領的項目數量。根據此值擴展您的 worker 機群或針對積壓發出警報。
• pending 是已被 worker 認領但尚未確認的項目數量。worker 輔助工具會在處理每個項目之前確認它，因此在正常運作下此值會保持接近零；持續的非零值表示有 worker 在認領和確認之間停滯。
• oldest_queued_at 是仍在佇列中最舊項目的時間戳記，該項目正在等待被認領或已被認領但尚未確認，若沒有則為 null。
• workers_polling 是在過去 30 秒內進行過輪詢的 worker 數量。使用此值進行存活性警報。

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}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}



優雅地停止工作階段

使用 work.stop 要求處理特定工作階段的 worker 將其關閉。預設情況下，工作項目會移至 stopping 狀態：worker 會在下一次租約心跳（lease heartbeat）時注意到，取消該工作階段進行中的工具呼叫，並確認關閉，此時工作項目會變為 stopped。在請求主體中傳入 force: true（使用 CLI 時，傳入 --force）可立即將工作項目標記為 stopped，而不需等待 worker 的確認。

由於這些呼叫是從您的維運工具執行，而非 worker 主機，因此 ANTHROPIC_WORK_ID 不會自動設定。在執行以下範例之前，請將其設定為目標工作項目的 ID。若要尋找工作項目的 ID，請透過 Environments Work 端點列出該環境的工作項目。

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)



後續步驟