セルフホストワーカーの監視とトラブルシューティング
キューの深さを読み取り、ワークを失わずにセッションとワーカーを停止し、セルフホスト型サンドボックスでよくある障害を修正します。
このページのキュー統計と停止の呼び出しは、組織のAPIキーで認証された監視ツールまたは運用ツールから実行します。ワーカーヘルパーが取得とキープアライブのループを処理するため、それらのエンドポイントを直接呼び出す必要はありません。
キューの深さを読み取る
client.beta.environments.work.stats() は、環境のキューの状態を返します。
| フィールド | 意味 | 用途 |
|---|---|---|
depth | 取得を待っているアイテム。 | ワーカーフリートのスケーリングや、バックログに関するアラートに使用します。 |
pending | ワーカーによって取得されたものの、まだ確認応答されていないアイテム。ワーカーヘルパーは各アイテムを処理する前に確認応答するため、通常の運用ではこの値はほぼゼロのままです。 | 取得と確認応答の間で停止したワーカーを検出します。ゼロ以外の値が継続する場合にアラートを出します。 |
oldest_queued_at | キューに残っている最も古いアイテム(取得待ち、または取得済みで未確認応答のもの)のタイムスタンプ。該当するアイテムがない場合は None です。 | 最も古いアイテムがどれだけ待機しているかを確認します。 |
workers_polling | 過去30秒以内にポーリングしたワーカー。 | 死活監視のアラートに使用します。 |
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になります。Python SDKワーカーの場合は、代わりに実行中のツール呼び出しを先に完了させるため、最大2.5分かかることがあります。
force=True を渡すと、ワーカーの確認を待たずに、ワークアイテムを即座に stopped としてマークします。強制停止しても実行中のツール呼び出しが早く終了するわけではありません。ワーカーが停止を検知するのは、依然として次のハートビートのときだからです。
これらの呼び出しはワーカーホストではなく運用ツールから実行されるため、ANTHROPIC_WORK_ID は自動的には設定されません。以下の例を実行する前に、対象のワークアイテムのIDを設定してください。ワークアイテムのIDを確認するには、環境キーを Authorization: Bearer $ANTHROPIC_ENVIRONMENT_KEY として送信し、ワークアイテムの一覧API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。を呼び出します。このエンドポイントは組織の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)ワーカーを正常に停止する
セッションの実行中にキャンセルされたワーカーは、セッションを停止する場合と同様に、終了する前にそのセッションをシャットダウンします。セッションにメモリストアがアタッチされている場合、ワーカーはそれでも新規および変更されたファイルのアップロードとストアディレクトリの削除を行います。削除は送信しないため、エージェントが削除したメモリは、以前の同期ですでにストアから削除されていない限り、ストアに残ります。
異常終了したプロセスはティアダウンを実行しません。ワーカーをクリーンに停止するには、次の手順に従います。
-
SIGTERMとSIGINTでワーカーがキャンセルされるようにします。 方法はワーカーによって異なります。
ワーカー 対応方法 antCLI何もする必要はありません。CLIは両方のシグナルを自身で処理します。実行中のツール呼び出しをキャンセルし、エラー結果を送信して、ワークアイテムを stoppedとしてマークします。独立したプロセスとして動作するSDKワーカー EnvironmentWorkerはシグナルハンドラーをインストールしません。スタンドアロンワーカーの例と同様に、シグナルハンドラーからワーカーをキャンセルしてください。Webhookサーバー内のSDKワーカー Webhookの例と同様に、サーバー自身のシャットダウンフックからワーカーをキャンセルしてください。ワーカーがサーバーのシグナルを横取りしてはいけません。 -
SIGTERMでワーカーを停止し、強制終了までに処理を完了するための時間を与えます。 ワーカーには、実行中のツール呼び出しを終了し、変更されたファイルをメモリストアにアップロードするための時間が必要です。Dockerはデフォルトで、停止シグナルの10秒後にSIGKILLを送信します。この制限は、
docker runの--stop-timeout 210で引き上げるか、オーケストレーターの終了猶予期間を同じ秒数に設定してください。
ティアダウンが実行される前にワーカーが停止した場合、同期されていなかったメモリの編集内容は失われます。長期間稼働するホストでは、そのストアをアタッチする次のセッションの前に、/mnt/memory/ 配下に残ったストアディレクトリも削除してください。1つのセッションを処理した後に破棄されるサンドボックスでは、クリーンアップは不要です。
トラブルシューティング
ワーカーが接続しない
workers_polling が0のままの場合、ワーカーはキューに到達していません。ワーカーホストで ANTHROPIC_ENVIRONMENT_KEY と ANTHROPIC_ENVIRONMENT_ID が設定されていることを確認してください。
セッションがキューに入ったままになる
ワークを取得しているワーカーがありません。キューに入ったセッションは失敗せずに待機します。キューの深さを読み取るで workers_polling と depth を確認してください。
メモリストアのマウントまたは同期に失敗する
メモリストアの障害がどこに現れるかは、その種類によって異なります。
- マウントの失敗: ワーカーがセッションを取得した際にメモリストアをマウントできない場合、ワーカーは失敗をログに書き込み、ワークアイテムを失敗させます。セッションはエラーイベントを発行せず、アイドル状態のままになります。
- 同期の失敗: ワーカーは失敗をログに書き込み、セッションには報告しません。
- 読み取り専用ストアへの書き込みの拒否: エージェントはツールエラーを受け取ります。読み取り専用ストアと競合を参照してください。
| 症状 | 原因 | 修正方法 |
|---|---|---|
ワーカーログに the work item carried no sessions token(Goでは ErrSessionMemoryNoToken エラー)が含まれ、ワークアイテムが失敗する。 | ワークアイテムのセッションごとの secret がワーカーに届いていません。コードがそれを転送していないか、組織でセルフホスト型サンドボックスのメモリストアが有効になっていません。 | ワークアイテムのシークレットを転送します。ワーカーが1つのプロセスでポーリングとセッション実行を行っているにもかかわらずこのログが出る場合は、サポートにお問い合わせください。 |
ワーカーログに something already exists at the memory store's path が含まれる。 | 同じファイルシステム上の別のセッションがそのパスを使用しています。または、以前のセッションのワーカーがティアダウンの実行前に強制終了されたため、ディレクトリが残っています。 | そのパスを使用するセッションをまだ実行しているワーカーがあるか確認してください。ある場合は、ディレクトリを削除しないでください。ワーカーはセッションの処理を終えたときにそれを削除します。ない場合は、ログ行に示されているディレクトリを削除してください。その中の同期されていなかった編集内容は失われます。そのようなセッションを2つ同時に実行するには、ストアを共有するセッションを分離するを参照してください。 |
ワーカーログに cannot create the memory store's folder と the worker host must make this mount path writable が含まれる。 | ワーカーを実行しているユーザーが /mnt/memory 配下にディレクトリを作成できません。 | /mnt/memoryを作成し、そのユーザーにchownします。ホストを準備するを参照してください。macOSの場合は、代わりにmacOSホストを準備するに従ってください。 |
ワーカーがセッションを取得した直後に、セッションが requires_action の停止理由でエラーイベントなしに idle のままになる。 | 前述のいずれかの理由でメモリストアをマウントできなかったため、ワーカーがワークアイテムを失敗させました。 | ホスト上で原因を修正してから、user.interrupt イベントを送信します。セッションのワークが再びキューに入り、次にそれを取得したワーカーがマウントを再試行します。 |
カスタムツール呼び出しが返ってこない
セッションが requires_action の停止理由で一時停止したままの場合、そのツールを提供しているワーカーまたはクライアントがありません。カスタムツールを提供するを参照してください。
ラップされたMCPツール呼び出しがハングする
MCPクライアントにタイムアウトが設定されていない場合、ラップされたMCPサーバーへのハングした呼び出しは、バックストップが発動したときにのみエラーのツール結果になります。
| SDK | バックストップ | 発動までの時間 |
|---|---|---|
| Python | ワーカー自身のツール呼び出し制限 | 約2.5分 |
| TypeScript | MCP SDKのデフォルトのリクエストタイムアウト | 約1分 |
| Go | デフォルトの制限を超えたツール呼び出しをワーカーがキャンセル | 120秒 |
このページは役に立ちましたか?