自行託管 worker 參考
自行託管沙箱 worker 的參考資料：ant CLI 旗標、環境變數、主機需求、檔案系統路徑，以及 SDK 輔助工具選項。
本頁說明為 self_hosted 環境提供服務的預建 worker。如需以任務為導向的指南，請從自行託管沙箱和部署自行託管的 worker 開始。
CLI 命令與旗標
| 命令 | 說明 |
|---|---|
ant beta:worker poll | 從環境的佇列中認領工作項目，並在程序內執行每個工作階段。使用 --on-work 時，則改為針對每個工作項目呼叫您的指令碼。 |
ant beta:worker run | 處理一個已認領的工作階段後結束。請將其用作每個工作階段沙箱的進入點。 |
| 旗標 | 說明 |
|---|---|
--environment-id | 要輪詢工作的環境。也會從 ANTHROPIC_ENVIRONMENT_ID 讀取。 |
--environment-key | 向此環境驗證 worker 的身分。也會從 ANTHROPIC_ENVIRONMENT_KEY 讀取。 |
--workdir | 下載技能以及工具讀寫檔案的目錄。預設為 .（目前目錄）。 |
--on-work | 針對每個已認領的工作項目呼叫的指令碼，取代在程序內執行工具。它會以環境變數接收工作階段詳細資訊，並從標準輸入以 JSON 接收工作項目。 |
--max-idle | 工作階段以 end_turn 停止原因進入閒置後，在關閉前等待的時間。預設為 60s。 |
--log-format | 日誌輸出格式。使用 json 以進行結構化日誌擷取。預設為 text。 |
環境變數
| 變數 | 說明 | 設定者 |
|---|---|---|
ANTHROPIC_ENVIRONMENT_ID | worker 所服務之佇列所屬的環境。 | 您，在 worker 主機上設定。輪詢器會將其傳遞給 --on-work 指令碼。 |
ANTHROPIC_ENVIRONMENT_KEY | 向佇列驗證 worker 的身分。 | 您，在 worker 主機上設定。輪詢器會將其傳遞給 --on-work 指令碼。 |
ANTHROPIC_SESSION_ID | 已認領工作項目所代表的工作階段。 | 輪詢器，供 --on-work 指令碼使用。 |
ANTHROPIC_WORK_ID | 已認領的工作項目。 | 輪詢器，供 --on-work 指令碼使用。 |
ANTHROPIC_WORK_SECRET | 工作項目的每工作階段密鑰。 | 您。輪詢器不會設定它。請參閱轉送工作項目的密鑰。 |
ANTHROPIC_BASE_URL | 覆寫預設的 API 端點。選用。 | 您，在 worker 主機上設定。 |
ANTHROPIC_WEBHOOK_SIGNING_KEY | 驗證傳入的 webhook 酬載。 | 您，在 webhook 處理常式主機上設定。 |
主機需求
| Worker | 需求 |
|---|---|
| 所有 worker | 一台 Linux 主機，且 /bin/bash 位於該確切路徑。worker 的 bash 工具會直接呼叫它，而不參考 PATH。 |
| TypeScript SDK | PATH 上需有 unzip 和 tar，以及 Node.js 22 或更新版本。 |
| Python 和 Go SDK | 不需要額外的二進位檔。這些 SDK 使用其標準函式庫進行封存檔解壓縮。 |
記憶體儲存區有其自身的額外需求。
沙箱檔案系統
| 路徑 | 內容 |
|---|---|
/workspace | 工具執行和技能下載的系統預設工作目錄。如果您使用不同的工作目錄，請更新代理的系統提示，讓 Claude 能找到技能檔案。 |
<workdir>/skills/<name>/ | 代理已下載的技能。 |
/mnt/memory/<store>/ | 每個附加的記憶體儲存區各有一個目錄，位於該儲存區的 mount_path（例如 /mnt/memory/user-preferences/）。worker 會在認領工作階段時建立這些目錄，並在工作階段結束時移除它們。 |
在自行託管環境中，工作階段的系統提示會省略 Anthropic 管理的沙箱所使用的 /mnt/session/outputs 指示。最終交付成果會位於代理在您沙箱檔案系統中寫入的任何位置，通常在工作目錄之下。
技能可以包含代理可直接執行的可執行檔。CLI 和 SDK worker 在解壓縮技能套件時，會保留其中記錄的可執行權限。如果您手動實作技能下載，則需自行負責設定可執行權限。
SDK 輔助工具
Python、TypeScript 和 Go SDK 提供三種不同控制層級的輔助工具：
| 輔助工具 | 功能 | 使用時機 |
|---|---|---|
EnvironmentWorker | 端對端處理輪詢、設定和執行。 | 大多數情況。 |
work.poller() | 輪詢工作佇列，並將每個已認領的工作階段交給您。 | 您要決定每個工作階段的處理方式，例如啟動沙箱而非在程序內執行工具。 |
client.beta.sessions.events.tool_runner() | 根據工作階段 ID 和工具清單，為單一工作階段執行工具呼叫。 | 您已認領工作，只需要執行層。 |
EnvironmentWorker
| 方法 | 說明 |
|---|---|
run() | 無限期執行，在工作階段到達時接手處理。 |
handle_item() | 處理單一已認領的工作項目後返回。請明確傳入工作、工作階段和環境識別碼以及 work_secret，或讓它讀取 ANTHROPIC_* 變數。 |
| 選項 | 說明 |
|---|---|
tools | 一個工廠函式，接收工作階段的 AgentToolContext 並傳回工具清單。預設為標準代理工具集。 |
memory_sync_interval | 工作階段執行期間，附加的記憶體儲存區與伺服器同步的頻率。請參閱同步間隔。 |
memory_sync_deletions | 代理在本機刪除的檔案是否也從儲存區中刪除。請參閱刪除。 |
EnvironmentWorker 會自動管理 AgentToolContext 和工具集。傳入 tools 工廠函式即可自訂工具清單：
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])工作輪詢器
| 選項 | 說明 |
|---|---|
drain | 佇列清空後是否停止輪詢，而非等待新工作。 |
block_ms | 每次輪詢在返回前等待工作到達的時間，以毫秒為單位。必須介於 1 到 999 之間；輔助工具會自動重新輪詢。傳入 None 以進行非阻塞檢查。預設為 999 毫秒的長輪詢。 |
reclaim_older_than_ms | 重新認領已被認領但在此毫秒數內從未確認的工作項目。 |
auto_stop | 在您的迴圈主體處理完每個工作項目後，是否為其發送停止訊號。當執行工作項目的程式會自行發送停止訊號時，請將其設為 False。handle_item() 會這麼做，由您啟動且負責停止呼叫的沙箱也是如此。 |
如需完整範例，請參閱從 SDK 輪詢器啟動沙箱。
工作階段工具執行器
client.beta.sessions.events.tool_runner() 以 tools 接收工具清單。若要建立該清單，請自行設定 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)AgentToolContext 與代理工具集
AgentToolContext 是工具呼叫的執行上下文。它定義工作目錄和路徑政策，並可下載工作階段的技能。
| 選項 | 說明 |
|---|---|
allowed_roots | 除工作目錄外，檔案工具（read、write、edit、glob、grep）可存取的目錄。 |
read_only_roots | write 和 edit 會拒絕其下路徑的目錄。 |
EnvironmentWorker 會自行將工作階段的記憶體儲存區目錄加入 allowed_roots，並將以 access: "read_only" 附加之儲存區的目錄加入 read_only_roots。
此限制僅是針對檔案工具的防護措施，而非沙箱。它不會限制 bash。
beta_agent_toolset_20260401(env) 接收一個 AgentToolContext，並傳回標準工具實作（bash、read、write、edit、glob、grep）。
Was this page helpful?