Claude Platform Docs
Managed Agents自行託管沙箱

監控自行託管的 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:

  1. 確保 SIGTERM 和 SIGINT 會取消 worker。 做法取決於 worker:

    Worker該怎麼做
    ant CLI無需任何動作。CLI 會自行處理這兩個訊號:它會取消任何進行中的工具呼叫、發布其錯誤結果,並將工作項目標記為 stopped。
    作為獨立程序的 SDK workerEnvironmentWorker 不會安裝任何訊號處理常式。請從訊號處理常式中取消 worker,如同獨立 worker 範例所示。
    位於 webhook 伺服器內的 SDK worker請從伺服器本身的關閉掛鉤中取消 worker,如同 webhook 範例所示。worker 不得接管伺服器的訊號。
  2. 使用 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後備機制觸發時間
Pythonworker 本身的工具呼叫限制約 2.5 分鐘
TypeScriptMCP SDK 的預設請求逾時約一分鐘
Goworker 會取消執行時間超過其預設限制的工具呼叫120 秒

這個頁面有幫助嗎?