自託管沙箱

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

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

與雲端環境的差異

當代理程式需要處理不能離開您網路邊界的資料、存取無法公開路由的內部服務，或在您組織自己的合規與稽核控制下執行時，自託管是一個合適的選擇。

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

何時搭配 MCP 通道使用

自託管控制的是代理程式的程式碼在哪裡執行。MCP 通道控制的是 Anthropic 如何連線到您網路中的 MCP 伺服器。兩者是獨立的：在 Anthropic 雲端沙箱中執行的工作階段仍可透過通道連線到私有 MCP 伺服器，而自託管的工作階段可以使用通道式或公開的 MCP 伺服器。當您希望執行和工具存取都保留在您的邊界內時，請同時使用兩者。

環境工作程式

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

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

CLI 和 SDK 都隨附預先建置的工作程式。ant CLI 僅支援常駐模式；SDK 同時支援常駐和 webhook 觸發模式。兩者皆可設定：請參閱參考文件中的自託管工作程式以了解 CLI 旗標，以及本頁的 SDK 輔助工具以了解 SDK 選項。如需更多控制權，請直接呼叫 Environments Work 端點並實作您自己的工作程式。在 Claude Platform on AWS 上，GET /v1/environments/{id}/work 列表端點及其 SDK 對應項目目前不可用；其他工作端點（poll、ack、heartbeat、stop、post results、per-item get 和 stats）正常運作。

沙箱檔案系統

• /workspace： 工具執行和技能下載的系統預設工作目錄。CLI 的 --workdir 旗標預設為目前目錄；傳入 --workdir /workspace 以符合系統預設值。技能會下載到 <workdir>/skills/<name>/。如果您使用不同的工作目錄，請更新代理程式的系統提示，以便 Claude 能夠找到技能檔案。
• /mnt/session/outputs： 工作程式框架會指示 Claude 將最終交付成果寫入此處。在沙箱模式下，請在此路徑掛載主機目錄，以便在工作階段結束後擷取輸出。在程序內模式下，工作程式的檔案工具會改為寫入工作目錄下，因此此路徑不適用。

開始之前

您需要：

• 一個現有的代理程式。 如果您還沒有，請先完成快速入門並記下其代理程式 ID。
• 一台 Linux 主機，且 /bin/bash 位於該確切路徑。TypeScript SDK 另外需要 unzip、tar 和 Node.js 22 或更新版本；Python SDK 使用標準函式庫進行封存檔解壓縮，沒有額外的二進位檔需求。這些相依性會在固定路徑解析，不會遵循 PATH 覆寫。
• 工作程式主機上安裝 ant CLI 或 Anthropic SDK（Python、TypeScript 或 Go）。
• 兩組憑證： 環境金鑰（在接下來的步驟中產生）用於驗證工作程式對其佇列的存取；您的 Claude API 金鑰用於從工作程式主機外部建立工作階段和讀取佇列統計資料。

執行工作程式

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

SDK 輔助工具

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

• EnvironmentWorker： 開箱即用的工作程式。端對端處理輪詢、設定和執行。
  • .run()：無限期執行，在工作階段到達時接收處理。收到 SIGTERM 時正常結束。
  • .handle_item()：接收一個待處理的工作階段、處理它，然後結束。
• work.poller()： 代替您輪詢工作佇列，並將每個已認領的工作階段交給您。當您想要決定每個工作階段的處理方式時使用此工具，例如啟動沙箱而非在程序內執行工具。
  • drain：是否在佇列清空後停止輪詢，而非等待新工作。
  • block_ms：等待工作到達的時間長度（以毫秒為單位），之後才返回。必須介於 1 到 999 之間（每次輪詢的等待時間；輔助工具會自動重新輪詢）。傳入 null（Python 中為 None，Go 中為 param.Null[int64]()）以進行非阻塞檢查；省略此參數則使用預設的 999 毫秒長輪詢。
  • ：重新認領已租給停止回應之工作程式的工作項目。

當您想要啟動自己的每個工作階段程序時（例如為每個已認領的工作階段啟動一個沙箱），請直接使用工作輪詢程式：

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，使用您的 Claude API 金鑰（而非環境金鑰），確認 workers_polling 至少為 1：

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

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

啟動工作階段

工作程式執行後，建立一個以該環境為目標的工作階段。工作階段會進入環境的工作佇列並在那裡等待，直到有工作程式認領它；如果沒有工作程式連線，工作階段會保持在佇列中而非失敗。

Anthropic 不會將檔案或 GitHub 儲存庫掛載到自託管沙箱中。若要提供工作階段特定的檔案，請在工作階段的 metadata 欄位中傳入檔案參照（例如 S3 路徑或 commit SHA）。您的產生指令碼或 --on-work 處理程式會從已認領的工作項目中讀取該中繼資料（透過 Environments Work 端點），並在工具執行開始前將檔案準備到工作目錄中。

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

監控與維運

這些呼叫從您的監控或維運工具執行，使用您的 Claude API 金鑰進行驗證，以觀察和管理工作程式叢集。認領和保持連線的迴圈是在工作程式輔助工具內部處理的，因此您不需要直接呼叫這些端點。

讀取佇列深度

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 以立即中斷，而非等待目前的工具呼叫完成。

由於這些呼叫是從您的維運工具而非工作程式主機執行，ANTHROPIC_WORK_ID 不會自動設定。在執行以下範例之前，請將其設定為目標工作項目的 ID。

後續步驟