監控自行託管的 worker 並進行疑難排解
讀取佇列深度、在不遺失工作的情況下停止工作階段與 worker,並修正常見的自行託管沙箱故障。
本頁面上的佇列統計與停止呼叫是從您的監控或維運工具執行,並使用您的組織 API 金鑰進行驗證。worker 輔助工具會處理認領與保持連線的迴圈,因此您不需要直接呼叫這些端點。
讀取佇列深度
client.beta.environments.work.stats() 會傳回環境的佇列狀態:
| 欄位 | 意義 | 用途 |
|---|---|---|
depth | 等待被認領的項目。 | 擴展您的 worker 叢集,或針對積壓發出警示。 |
pending | 已被 worker 認領但尚未確認的項目。worker 輔助工具會在處理每個項目之前先確認它,因此在正常運作下此值會維持在接近零。 | 偵測在認領與確認之間停滯的 worker:針對持續非零的值發出警示。 |
oldest_queued_at | 仍在佇列中最舊項目的時間戳記,該項目可能正在等待被認領,或已被認領但尚未確認。沒有此類項目時為 None。 | 查看最舊的項目已等待多久。 |
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
}正常停止工作階段
使用 client.beta.environments.work.stop() 要求處理特定工作階段的 worker 將其關閉。
預設情況下,工作項目會轉為 stopping。worker 會在下一次租約心跳時偵測到此狀態,取消該工作階段進行中的工具呼叫,並確認關閉。接著工作項目會變為 stopped。Python SDK worker 則會先讓進行中的工具呼叫完成,這最多可能需要 2.5 分鐘。
傳入 force=True 可立即將工作項目標記為 stopped,而不等待 worker 的確認。強制停止並不會更快結束進行中的工具呼叫,因為 worker 仍是在下一次心跳時才察覺到停止。
由於這些呼叫是從您的維運工具而非 worker 主機執行,因此不會自動設定 ANTHROPIC_WORK_ID。在執行以下範例之前,請將其設定為目標工作項目的 ID。若要找出工作項目的 ID,請使用環境金鑰呼叫列出工作項目可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。,並以 Authorization: Bearer $ANTHROPIC_ENVIRONMENT_KEY 的形式傳送。該端點會拒絕您的組織 API 金鑰。
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)正常停止 worker
在工作階段執行期間被取消的 worker,會在結束前關閉該工作階段,就如同您停止工作階段時一樣。如果工作階段附加了記憶體儲存區,worker 仍會上傳新增與已變更的檔案,並移除儲存區目錄。它不會傳送任何刪除操作,因此代理所刪除的記憶會保留在儲存區中,除非先前的同步已將其從儲存區中刪除。
突然結束的程序不會執行任何清理作業。若要乾淨地停止 worker:
-
確保 SIGTERM 和 SIGINT 會取消 worker。 做法取決於 worker:
Worker 該怎麼做 antCLI無需任何動作。CLI 會自行處理這兩個訊號:它會取消任何進行中的工具呼叫、發布其錯誤結果,並將工作項目標記為 stopped。作為獨立程序的 SDK worker EnvironmentWorker不會安裝任何訊號處理常式。請從訊號處理常式中取消 worker,如同獨立 worker 範例所示。位於 webhook 伺服器內的 SDK worker 請從伺服器本身的關閉掛鉤中取消 worker,如同 webhook 範例所示。worker 不得接管伺服器的訊號。 -
使用 SIGTERM 停止 worker,並在任何強制終止之前給予它完成的時間。 worker 需要時間來結束進行中的工具呼叫,並將已變更的檔案上傳至記憶體儲存區。Docker 預設會在停止訊號發出 10 秒後傳送 SIGKILL。請在
docker run上使用--stop-timeout 210來提高此限制,或將您的協調器的終止寬限期設定為相同的秒數。
如果 worker 在執行清理作業之前就停止,您將遺失任何尚未同步的記憶編輯。在長期運作的主機上,還需在下一個附加該儲存區的工作階段之前,刪除 /mnt/memory/ 下殘留的儲存區目錄。僅服務一個工作階段後即被捨棄的沙箱則不需要清理。
疑難排解
worker 無法連線
如果 workers_polling 一直維持在 0,表示 worker 無法連到佇列。請確認 worker 主機上已設定 ANTHROPIC_ENVIRONMENT_KEY 和 ANTHROPIC_ENVIRONMENT_ID。
工作階段一直處於佇列中
沒有 worker 在認領工作。佇列中的工作階段會持續等待,而不會失敗。請在讀取佇列深度中檢查 workers_polling 和 depth。
記憶體儲存區無法掛載或同步
記憶體儲存區故障會在何處顯現,取決於其類型:
- 掛載失敗: 如果 worker 在認領工作階段時無法掛載記憶體儲存區,它會將失敗寫入其日誌,並使該工作項目失敗。工作階段不會發出錯誤事件,並維持閒置狀態。
- 同步失敗: worker 會將失敗寫入其日誌,而不會回報給工作階段。
- 對唯讀儲存區的寫入遭拒: 代理會收到工具錯誤。請參閱唯讀儲存區與衝突。
| 症狀 | 原因 | 修正方式 |
|---|---|---|
worker 日誌包含 the work item carried no sessions token(在 Go 中為 ErrSessionMemoryNoToken 錯誤),且工作項目失敗。 | 工作項目的每個工作階段 secret 未送達 worker。可能是您的程式碼沒有轉送它,或是您的組織尚未啟用自行託管沙箱上的記憶體儲存區。 | 轉送工作項目的密鑰。如果 worker 在同一個程序中輪詢並執行工作階段,卻仍記錄此訊息,請聯絡支援團隊。 |
worker 日誌包含 something already exists at the memory store's path。 | 同一檔案系統上的另一個工作階段正在使用該路徑。或者,先前工作階段的 worker 在執行清理作業之前就被終止,因此目錄殘留了下來。 | 檢查是否仍有 worker 正在執行使用該路徑的工作階段。如果有,請不要移除該目錄:worker 會在處理完工作階段時將其移除。如果沒有,請移除日誌行中指出的目錄。其中尚未同步的編輯將會遺失。若要同時執行兩個這類工作階段,請參閱隔離共用儲存區的工作階段。 |
worker 日誌包含 cannot create the memory store's folder 和 the worker host must make this mount path writable。 | 執行 worker 的使用者無法在 /mnt/memory 下建立目錄。 | 建立 /mnt/memory 並使用 chown 將其擁有者設為該使用者。請參閱準備主機。在 macOS 上,請改為依照準備 macOS 主機操作。 |
在 worker 認領工作階段後不久,工作階段處於 idle 狀態,停止原因為 requires_action,且沒有錯誤事件。 | worker 因上述其中一個原因無法掛載記憶體儲存區,而使工作項目失敗。 | 在主機上修正原因,然後傳送 user.interrupt 事件。工作階段的工作會重新排入佇列,下一個認領它的 worker 會重試掛載。 |
自訂工具呼叫一直沒有回傳
如果工作階段處於暫停狀態且停止原因為 requires_action,表示沒有任何 worker 或用戶端提供該工具。請參閱提供自訂工具。
包裝的 MCP 工具呼叫停滯
如果 MCP 用戶端沒有設定逾時,對包裝的 MCP 伺服器的停滯呼叫只有在後備機制觸發時才會變成錯誤工具結果:
| SDK | 後備機制 | 觸發時間 |
|---|---|---|
| Python | worker 本身的工具呼叫限制 | 約 2.5 分鐘 |
| TypeScript | MCP SDK 的預設請求逾時 | 約一分鐘 |
| Go | worker 會取消執行時間超過其預設限制的工具呼叫 | 120 秒 |
這個頁面有幫助嗎?