セルフホストワーカーの監視とトラブルシューティング

このページの監視呼び出しは、Claude APIキーで認証された監視ツールまたは運用ツールから実行します。ワーカーヘルパーが取得とキープアライブのループを処理するため、それらのエンドポイントを直接呼び出す必要はありません。

キューの深さを読み取る

client.beta.environments.work.stats() は、環境のキューの状態を返します。

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() を使用すると、特定のセッションを処理しているワーカーにそのセッションのシャットダウンを要求できます。

デフォルトでは、ワークアイテムは stopping に移行します。ワーカーは次のリースハートビートでこれを検知し、セッションの実行中のツール呼び出しをキャンセルして、シャットダウンを確認します。その後、ワークアイテムは stopped になります。

force=True を渡すと、ワーカーの確認を待たずに、ワークアイテムを即座に stopped としてマークします。

これらの呼び出しはワーカーホストではなく運用ツールから実行されるため、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)

ワーカーを正常に停止する

セッションの実行中にキャンセルされたワーカーは、終了する前に実行中のワークを停止します。セッションにメモリストアがアタッチされている場合、ワーカーは最終同期をスキップしますが、変更されたファイルのアップロードとストアディレクトリの削除は引き続き行います。

強制終了（kill）されたプロセスはティアダウンを実行しません。ワーカーをクリーンに停止するには、次の手順に従います。

1. SIGTERMとSIGINTでワーカーがキャンセルされるようにします。 方法はワーカーによって異なります。

   ワーカー	対応方法
   ant CLI	何もする必要はありません。CLIは両方のシグナルを自身で処理します。実行中のツール呼び出しをキャンセルし、エラー結果を送信して、ワークアイテムを解放します。
   独立したプロセスとして動作するSDKワーカー	EnvironmentWorker はシグナルハンドラーをインストールしません。スタンドアロンワーカーの例と同様に、シグナルハンドラーからワーカーをキャンセルしてください。
   Webhookサーバー内のSDKワーカー	Webhookの例と同様に、サーバー自身のシャットダウンフックからワーカーをキャンセルしてください。ワーカーがサーバーのシグナルを横取りしてはいけません。

2. SIGTERMでワーカーを停止し、強制終了までに少なくとも30秒の猶予を設けます。 最終アップロードにはそれだけの時間がかかる場合があります。Dockerはデフォルトで、停止シグナルの10秒後にSIGKILLを送信します。この制限は、docker run の --stop-timeout、またはオーケストレーターの終了猶予期間で引き上げてください。

ティアダウンが実行される前にワーカーが強制終了された場合、同期されていなかったメモリの編集内容は失われます。長期間稼働するホストでは、そのストアをアタッチする次のセッションの前に、/mnt/memory/ 配下に残ったストアディレクトリも削除してください。1つのセッションを処理した後に破棄されるサンドボックスでは、クリーンアップは不要です。

トラブルシューティング

ワーカーが接続しない

workers_polling が0のままの場合、ワーカーはキューに到達していません。ワーカーホストで ANTHROPIC_ENVIRONMENT_KEY と ANTHROPIC_ENVIRONMENT_ID が設定されていることを確認してください。

セッションがキューに入ったままになる

ワークを取得しているワーカーがありません。キューに入ったセッションは失敗せずに待機します。キューの深さを読み取るで workers_polling と depth を確認してください。

メモリストアのマウントに失敗する

ワーカーは、マウントおよびバックグラウンド同期の失敗をセッションに報告するのではなく、ログに記録します。エージェントに届くのは読み取り専用による拒否のみで、ツールエラーとして届きます（読み取り専用ストアと競合を参照）。

ワーカーがセッションを取得した際にメモリストアをマウントできない場合、ワーカーはワークアイテムを失敗させます。セッションはエラーイベントを発行せず、アイドル状態のままになります。

カスタムツール呼び出しが返ってこない

セッションが requires_action の停止理由で一時停止したままの場合、そのツールを提供しているワーカーまたはクライアントがありません。カスタムツールを提供するを参照してください。

ラップされたMCPツール呼び出しがハングする

MCPクライアントにタイムアウトが設定されていない場合、ラップされたMCPサーバーへのハングした呼び出しは、バックストップが発動したときにのみエラーのツール結果になります。