--- title: セルフホストワーカーの監視とトラブルシューティング url: https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-operations description: キューの深さを読み取り、ワークを失わずにセッションとワーカーを停止し、セルフホスト型サンドボックスでよくある障害を修正します。 featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- このページの監視呼び出しは、Claude APIキーで認証された監視ツールまたは運用ツールから実行します。ワーカーヘルパーが取得とキープアライブのループを処理するため、それらのエンドポイントを直接呼び出す必要はありません。 これらのエンドポイントは、組織のAPIキーまたは環境キーのいずれかを受け付けます。ワーカーホストの外部から、組織のAPIキーを使用して呼び出してください。ワーカーホストで `ANTHROPIC_API_KEY` を設定すると、組織スコープの認証情報がエージェントのツール呼び出しに公開されてしまいます。 ## キューの深さを読み取る `GET /v1/environments/{environment_id}/work/stats` (python, typescript, ruby: `client.beta.environments.work.stats()`; go, csharp: `client.Beta.Environments.Work.Stats()`; java: `client.beta().environments().work().stats()`; php: `$client->beta->environments->work->stats()`; cli: `ant beta:environments:work stats`) は、環境のキューの状態を返します。 | フィールド | 意味 | 用途 | | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `depth` (csharp, go: `Depth`) | 取得を待っているアイテム。 | ワーカーフリートのスケーリングや、バックログに関するアラートに使用します。 | | `pending` (csharp, go: `Pending`) | ワーカーによって取得されたものの、まだ確認応答されていないアイテム。ワーカーヘルパーは各アイテムを処理する前に確認応答するため、通常の運用ではこの値はほぼゼロのままです。 | 取得と確認応答の間で停止したワーカーを検出します。ゼロ以外の値が継続する場合にアラートを出します。 | | `oldest_queued_at` (java, php: `oldestQueuedAt`; csharp, go: `OldestQueuedAt`) | キューに残っている最も古いアイテム（取得待ち、または取得済みで未確認応答のもの）のタイムスタンプ。該当するアイテムがない場合は `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) です。 | 最も古いアイテムがどれだけ待機しているかを確認します。 | | `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) | 過去30秒以内にポーリングしたワーカー。 | 死活監視のアラートに使用します。 | ```bash cURL curl -sS "https://api.anthropic.com/v1/environments/$ANTHROPIC_ENVIRONMENT_ID/work/stats" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "anthropic-version: 2023-06-01" ``` ```bash CLI ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID" ``` ```python Python 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}") ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const stats = await client.beta.environments.work.stats(process.env.ANTHROPIC_ENVIRONMENT_ID!); console.log(`depth=${stats.depth} pending=${stats.pending}`); ``` ```csharp C# using Anthropic; var client = new AnthropicClient(); var environmentId = Environment.GetEnvironmentVariable("ANTHROPIC_ENVIRONMENT_ID")!; var stats = await client.Beta.Environments.Work.Stats(environmentId); Console.WriteLine($"depth={stats.Depth} pending={stats.Pending}"); ``` ```go Go package main import ( "context" "fmt" "os" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID") stats, err := client.Beta.Environments.Work.Stats( context.Background(), environmentID, anthropic.BetaEnvironmentWorkStatsParams{}, ) if err != nil { panic(err) } fmt.Printf("depth=%d pending=%d\n", stats.Depth, stats.Pending) } ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.environments.work.BetaSelfHostedWorkQueueStats; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); BetaSelfHostedWorkQueueStats stats = client.beta() .environments() .work() .stats(System.getenv("ANTHROPIC_ENVIRONMENT_ID")); IO.println("depth=" + stats.depth() + " pending=" + stats.pending()); } ``` ```php PHP beta->environments->work->stats(getenv('ANTHROPIC_ENVIRONMENT_ID')); printf("depth=%d pending=%d\n", $stats->depth, $stats->pending); ``` ```ruby Ruby require "anthropic" client = Anthropic::Client.new stats = client.beta.environments.work.stats(ENV.fetch("ANTHROPIC_ENVIRONMENT_ID")) puts "depth=#{stats.depth} pending=#{stats.pending}" ``` ```text wrap { "type": "work_queue_stats", "depth": 0, "pending": 0, "oldest_queued_at": null, "workers_polling": 0 } ``` ## セッションを正常に停止する `POST /v1/environments/{environment_id}/work/{work_id}/stop` (python, typescript, ruby: `client.beta.environments.work.stop()`; go, csharp: `client.Beta.Environments.Work.Stop()`; java: `client.beta().environments().work().stop()`; php: `$client->beta->environments->work->stop()`; cli: `ant beta:environments:work stop`) を使用すると、特定のセッションを処理しているワーカーにそのセッションのシャットダウンを要求できます。 デフォルトでは、ワークアイテムは `stopping` に移行します。ワーカーは次のリースハートビートでこれを検知し、セッションの実行中のツール呼び出しをキャンセルして、シャットダウンを確認します。その後、ワークアイテムは `stopped` になります。 `force: true` (python: `force=True`; cli: `--force`) を渡すと、ワーカーの確認を待たずに、ワークアイテムを即座に `stopped` としてマークします。 これらの呼び出しはワーカーホストではなく運用ツールから実行されるため、`ANTHROPIC_WORK_ID` は自動的には設定されません。以下の例を実行する前に、対象のワークアイテムのIDを設定してください。ワークアイテムのIDを確認するには、[Environments Workエンドポイント](https://platform.claude.com/docs/ja/api/beta/environments/work)を使用して環境のワークアイテムを一覧表示します。 ```bash cURL curl -sS "https://api.anthropic.com/v1/environments/$ANTHROPIC_ENVIRONMENT_ID/work/$ANTHROPIC_WORK_ID/stop" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{}' ``` ```bash CLI ant beta:environments:work stop \ --environment-id "$ANTHROPIC_ENVIRONMENT_ID" \ --work-id "$ANTHROPIC_WORK_ID" ``` ```python Python 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) ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const work = await client.beta.environments.work.stop(process.env.ANTHROPIC_WORK_ID!, { environment_id: process.env.ANTHROPIC_ENVIRONMENT_ID! }); console.log(work.state); ``` ```csharp C# using Anthropic; var client = new AnthropicClient(); var work = await client.Beta.Environments.Work.Stop( Environment.GetEnvironmentVariable("ANTHROPIC_WORK_ID")!, new() { EnvironmentID = Environment.GetEnvironmentVariable("ANTHROPIC_ENVIRONMENT_ID")! } ); Console.WriteLine(work.State); ``` ```go Go package main import ( "context" "fmt" "os" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() work, err := client.Beta.Environments.Work.Stop( context.Background(), os.Getenv("ANTHROPIC_WORK_ID"), anthropic.BetaEnvironmentWorkStopParams{ EnvironmentID: os.Getenv("ANTHROPIC_ENVIRONMENT_ID"), }, ) if err != nil { panic(err) } fmt.Println(work.State) } ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.beta.environments.work.BetaSelfHostedWork; import com.anthropic.models.beta.environments.work.BetaSelfHostedWorkStopRequest; import com.anthropic.models.beta.environments.work.WorkStopParams; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); BetaSelfHostedWork work = client.beta().environments().work().stop( WorkStopParams.builder() .environmentId(System.getenv("ANTHROPIC_ENVIRONMENT_ID")) .workId(System.getenv("ANTHROPIC_WORK_ID")) .betaSelfHostedWorkStopRequest(BetaSelfHostedWorkStopRequest.builder().build()) .build() ); IO.println(work.state()); } ``` ```php PHP beta->environments->work->stop( getenv('ANTHROPIC_WORK_ID'), environmentID: getenv('ANTHROPIC_ENVIRONMENT_ID'), ); echo $work->state . "\n"; ``` ```ruby Ruby require "anthropic" client = Anthropic::Client.new work = client.beta.environments.work.stop( ENV.fetch("ANTHROPIC_WORK_ID"), environment_id: ENV.fetch("ANTHROPIC_ENVIRONMENT_ID") ) puts work.state ``` ## ワーカーを正常に停止する セッションの実行中にキャンセルされたワーカーは、終了する前に実行中のワークを停止します。セッションに[メモリストア](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-memory)がアタッチされている場合、ワーカーは最終同期をスキップしますが、変更されたファイルのアップロードとストアディレクトリの削除は引き続き行います。 強制終了（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` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) が0のままの場合、ワーカーはキューに到達していません。ワーカーホストで `ANTHROPIC_ENVIRONMENT_KEY` と `ANTHROPIC_ENVIRONMENT_ID` が設定されていることを確認してください。 ### セッションがキューに入ったままになる ワークを取得しているワーカーがありません。キューに入ったセッションは失敗せずに待機します。[キューの深さを読み取る](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-operations#read-queue-depth)で `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) と `depth` (csharp, go: `Depth`) を確認してください。 ### メモリストアのマウントに失敗する ワーカーは、マウントおよびバックグラウンド同期の失敗をセッションに報告するのではなく、ログに記録します。エージェントに届くのは読み取り専用による拒否のみで、ツールエラーとして届きます（[読み取り専用ストアと競合](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-memory#read-only-stores-and-conflicts)を参照）。 ワーカーがセッションを取得した際にメモリストアをマウントできない場合、ワーカーはワークアイテムを失敗させます。セッションはエラーイベントを発行せず、アイドル状態のままになります。 | 症状 | 原因 | 修正方法 | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ワーカーログに `the work item carried no sessions token`（Goでは `ErrSessionMemoryNoToken` エラー）が含まれ、ワークアイテムが失敗する。 | ワークアイテムのセッションごとの `secret` (csharp, go: `Secret`) がワーカーに届いていません。コードがそれを転送していないか、組織でセルフホスト型サンドボックスのメモリストアが有効になっていません。 | [ワークアイテムのシークレットを転送します](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret)。ワーカーが1つのプロセスでポーリングとセッション実行を行っているにもかかわらずこのログが出る場合は、サポートにお問い合わせください。 | | ワーカーログに `something already exists at the memory store's path` が含まれる。 | 以前のセッションから残ったディレクトリです。通常は、ティアダウンが実行される前にワーカーが強制終了されたセッションのものです。 | ログ行に示されている残存ディレクトリを削除してください。その中の同期されていなかった編集内容は失われます。 | | ワーカーログに `cannot create the memory store's folder` と `the worker host must make this mount path writable` が含まれる。 | ワーカーを実行しているユーザーが `/mnt/memory` 配下にディレクトリを作成できません。 | `/mnt/memory` を作成し、そのユーザーに `chown` してください。[ホストを準備する](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-memory#prepare-the-host)を参照してください。 | | ワーカーがセッションを取得した直後に、セッションが `requires_action` の停止理由でエラーイベントなしに `idle` のままになる。 | 前述のいずれかの理由でメモリストアをマウントできなかったため、ワーカーがワークアイテムを失敗させました。 | ホスト上で原因を修正してから、[`user.interrupt`](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming#interrupt-the-agent) イベントを送信します。セッションのワークが再びキューに入り、次にそれを取得したワーカーがマウントを再試行します。 | ### カスタムツール呼び出しが返ってこない セッションが `requires_action` の停止理由で一時停止したままの場合、そのツールを提供しているワーカーまたはクライアントがありません。[カスタムツールを提供する](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-custom-tools#serve-a-custom-tool)を参照してください。 ### ラップされたMCPツール呼び出しがハングする MCPクライアントにタイムアウトが設定されていない場合、[ラップされたMCPサーバー](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-custom-tools#wrap-an-mcp-server-as-custom-tools)へのハングした呼び出しは、バックストップが発動したときにのみエラーのツール結果になります。 | SDK | バックストップ | 発動までの時間 | | ---------- | --------------------------------- | ------- | | Python | ワーカー自身のツール呼び出し制限 | 約2分半 | | TypeScript | MCP SDKのデフォルトのリクエストタイムアウト | 約1分 | | Go | ワーカーが、デフォルトの制限を超えたツール呼び出しをキャンセルする | 120秒 |