---
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
  zdr:
    eligibility: not-eligible
    note: セルフホスト型Managed Agentsを除き、ZDRの適格対象ではありません。セッションはステートフルなリソースであり、トランスクリプトは削除するまで保持されます。
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
    Claude Models on Google Cloud (Anthropic managed):
      availability: beta
      note: Environments Workエンドポイントを呼び出すワーカーを自分で作成します。
---

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

<Warning>
  キュー統計と停止のエンドポイントは、組織のAPIキーまたは環境キーのいずれかを受け付けます。ワーカーホストの外部から、組織のAPIキーを使用して呼び出してください。ワーカーホストで `ANTHROPIC_API_KEY` を設定すると、組織スコープの認証情報がエージェントのツール呼び出しに公開されてしまいます。
</Warning>

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

`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秒以内にポーリングしたワーカー。 | 死活監視のアラートに使用します。 |

<CodeGroup>
  ```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: 2026-10-21"
  ```

  ```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/v2"
  )

  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
  <?php

  use Anthropic\Client;

  $client = new Client();

  $stats = $client->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}"
  ```
</CodeGroup>

```json
{
  "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`になります。Python SDKワーカーの場合は、代わりに実行中のツール呼び出しを先に完了させるため、最大2.5分かかることがあります。

`force: true` (python: `force=True`; csharp: `Force = true`; go: `BetaSelfHostedWorkStopRequest: anthropic.BetaSelfHostedWorkStopRequestParam{Force: anthropic.Bool(true)}`; java: `.force(true)`; cli: `--force`) を渡すと、ワーカーの確認を待たずに、ワークアイテムを即座に `stopped` としてマークします。強制停止しても実行中のツール呼び出しが早く終了するわけではありません。ワーカーが停止を検知するのは、依然として次のハートビートのときだからです。

これらの呼び出しはワーカーホストではなく運用ツールから実行されるため、`ANTHROPIC_WORK_ID` は自動的には設定されません。以下の例を実行する前に、対象のワークアイテムのIDを設定してください。ワークアイテムのIDを確認するには、環境キーを `Authorization: Bearer $ANTHROPIC_ENVIRONMENT_KEY` として送信し、[ワークアイテムの一覧](https://platform.claude.com/docs/ja/api/beta/environments/work/list)を呼び出します。このエンドポイントは組織のAPIキーを拒否します。

<CodeGroup>
  ```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: 2026-10-21" \
    -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/v2"
  )

  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
  <?php

  use Anthropic\Client;

  $client = new Client();

  $work = $client->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
  ```
</CodeGroup>

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

セッションの実行中にキャンセルされたワーカーは、[セッションを停止する](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-operations#stop-a-session-gracefully)場合と同様に、終了する前にそのセッションをシャットダウンします。セッションに[メモリストア](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-memory)がアタッチされている場合、ワーカーはそれでも新規および変更されたファイルのアップロードとストアディレクトリの削除を行います。削除は送信しないため、エージェントが削除したメモリは、以前の同期ですでにストアから削除されていない限り、ストアに残ります。

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

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

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

2. **SIGTERMでワーカーを停止し、強制終了までに処理を完了するための時間を与えます。** ワーカーには、実行中のツール呼び出しを終了し、変更されたファイルをメモリストアにアップロードするための時間が必要です。Dockerはデフォルトで、停止シグナルの10秒後にSIGKILLを送信します。この制限は、`docker run` の `--stop-timeout 60` (python: `--stop-timeout 210`) で引き上げるか、オーケストレーターの終了猶予期間を同じ秒数に設定してください。

ティアダウンが実行される前にワーカーが停止した場合、同期されていなかったメモリの編集内容は失われます。長期間稼働するホストでは、そのストアをアタッチする次のセッションの前に、`/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-per-session#forward-the-work-items-secret)。ワーカーが1つのプロセスでポーリングとセッション実行を行っているにもかかわらずこのログが出る場合は、サポートにお問い合わせください。 |
| ワーカーログに `something already exists at the memory store's path` が含まれる。 | 同じファイルシステム上の別のセッションがそのパスを使用しています。または、以前のセッションのワーカーがティアダウンの実行前に強制終了されたため、ディレクトリが残っています。 | そのパスを使用するセッションをまだ実行しているワーカーがあるか確認してください。ある場合は、ディレクトリを削除しないでください。ワーカーはセッションの処理を終えたときにそれを削除します。ない場合は、ログ行に示されているディレクトリを削除してください。その中の同期されていなかった編集内容は失われます。そのようなセッションを2つ同時に実行するには、[ストアを共有するセッションを分離する](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-memory#isolate-sessions-that-share-a-store)を参照してください。 |
| ワーカーログに `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)を参照してください。macOSの場合は、代わりに[macOSホストを準備する](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-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.5分 |
| TypeScript | MCP SDKのデフォルトのリクエストタイムアウト | 約1分 |
| Go | デフォルトの制限を超えたツール呼び出しをワーカーがキャンセル | 120秒 |
