---
title: Surveiller et dépanner les workers auto-hébergés
url: https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-operations
description: Consultez la profondeur de la file d'attente, arrêtez les sessions et les workers sans perdre de travail, et corrigez les défaillances courantes des sandboxes auto-hébergées.
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: Non éligible à la ZDR, sauf pour Managed Agents auto-hébergé. Les sessions sont des ressources avec état ; les transcriptions persistent jusqu’à ce que vous les supprimiez.
  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: Vous écrivez votre propre worker, qui appelle les points de terminaison Environments Work.
---

Les appels de statistiques de file d’attente et d’arrêt présentés sur cette page s’exécutent depuis vos outils de surveillance ou d’exploitation, authentifiés avec la clé API de votre organisation. Les helpers de worker gèrent la boucle de réclamation et de maintien en vie, vous n’appelez donc pas ces points de terminaison directement.

<Warning>
  Les points de terminaison de statistiques de file d’attente et d’arrêt acceptent soit la clé API de votre organisation, soit la clé d’environnement. Appelez-les depuis l’extérieur de l’hôte du worker avec la clé API de votre organisation. Définir `ANTHROPIC_API_KEY` sur l’hôte du worker expose un identifiant à portée d’organisation aux appels d’outils de l’agent.
</Warning>

## Consulter la profondeur de la file d’attente

`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`) renvoie l’état de la file d’attente d’un environnement :

| Champ | Signification | Utilisez-le pour |
| ----- | ----- | ----- |
| `depth` (csharp, go: `Depth`) | Éléments en attente de réclamation. | Dimensionner votre flotte de workers ou déclencher une alerte en cas d’arriéré. |
| `pending` (csharp, go: `Pending`) | Éléments réclamés par un worker mais pas encore acquittés. Les helpers de worker acquittent chaque élément avant de le traiter, cette valeur reste donc proche de zéro en fonctionnement normal. | Détecter un worker bloqué entre la réclamation et l’acquittement : déclenchez une alerte sur une valeur non nulle persistante. |
| `oldest_queued_at` (java, php: `oldestQueuedAt`; csharp, go: `OldestQueuedAt`) | Horodatage de l’élément le plus ancien encore dans la file d’attente, qu’il soit en attente de réclamation ou réclamé mais pas encore acquitté. `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) lorsqu’aucun élément de ce type n’existe. | Voir depuis combien de temps l’élément le plus ancien attend. |
| `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) | Workers ayant interrogé la file au cours des 30 dernières secondes. | Déclencher une alerte sur la disponibilité. |

<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
}
```

## Arrêter une session proprement

Utilisez `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`) pour demander au worker qui gère une session spécifique de l’arrêter.

Par défaut, l’élément de travail passe à l’état `stopping`. Le worker le détecte lors de son prochain heartbeat de bail, annule l’appel d’outil en cours de la session et confirme l’arrêt. L’élément de travail passe alors à l’état `stopped`. Un worker du SDK Python laisse plutôt l’appel d’outil en cours se terminer d’abord, ce qui peut prendre jusqu’à 2,5 minutes.

Passez `force: true` (python: `force=True`; csharp: `Force = true`; go: `BetaSelfHostedWorkStopRequest: anthropic.BetaSelfHostedWorkStopRequestParam{Force: anthropic.Bool(true)}`; java: `.force(true)`; cli: `--force`) pour marquer immédiatement l’élément de travail comme `stopped` au lieu d’attendre la confirmation du worker. Un arrêt forcé ne met pas fin plus tôt à un appel d’outil en cours, car le worker ne détecte toujours l’arrêt qu’à son prochain heartbeat.

Comme ces appels s’exécutent depuis vos outils d’exploitation plutôt que depuis l’hôte du worker, `ANTHROPIC_WORK_ID` n’est pas défini automatiquement. Définissez-le sur l’ID de l’élément de travail cible avant d’exécuter les exemples suivants. Pour trouver l’ID d’un élément de travail, appelez [Lister les éléments de travail](https://platform.claude.com/docs/fr/api/beta/environments/work/list) avec la clé d’environnement, envoyée sous la forme `Authorization: Bearer $ANTHROPIC_ENVIRONMENT_KEY`. Ce point de terminaison rejette la clé API de votre organisation.

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

## Arrêter les workers proprement

Un worker annulé pendant l’exécution d’une session arrête cette session avant de se terminer, comme lorsque vous [arrêtez une session](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-operations#stop-a-session-gracefully). Si des [magasins de mémoire](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory) sont attachés à la session, le worker téléverse tout de même les fichiers nouveaux et modifiés et supprime les répertoires des magasins. Il n’envoie aucune suppression : une mémoire que l’agent a supprimée reste donc dans le magasin, sauf si une synchronisation antérieure l’a déjà supprimée du magasin.

Un processus qui se termine brutalement n’exécute aucune procédure de nettoyage. Pour arrêter un worker proprement :

1. **Assurez-vous que SIGTERM et SIGINT annulent le worker.** La méthode dépend du worker :

   | Worker | Que faire |
   | ----- | ----- |
   | CLI `ant` | Rien. La CLI gère elle-même les deux signaux : elle annule tout appel d’outil en cours, publie son résultat d’erreur et marque l’élément de travail comme `stopped`. |
   | Worker SDK constituant son propre processus | `EnvironmentWorker` n’installe aucun gestionnaire de signaux. Annulez le worker depuis un gestionnaire de signaux, comme le font les exemples de worker autonome. |
   | Worker SDK au sein d’un serveur webhook | Annulez le worker depuis le hook d’arrêt propre au serveur, comme le font les exemples webhook. Le worker ne doit pas prendre le contrôle des signaux du serveur. |

2. **Arrêtez le worker avec SIGTERM et laissez-lui le temps de terminer avant tout arrêt brutal.** Le worker a besoin de temps pour mettre fin à un appel d’outil en cours et pour téléverser les fichiers modifiés vers un magasin de mémoire. Par défaut, Docker envoie SIGKILL 10 secondes après le signal d’arrêt. Augmentez cette limite avec `--stop-timeout 60` (python: `--stop-timeout 210`) sur `docker run`, ou définissez le délai de grâce de terminaison de votre orchestrateur sur le même nombre de secondes.

Si un worker s’arrête avant l’exécution de sa procédure de nettoyage, vous perdez toutes les modifications de mémoire non synchronisées. Sur un hôte de longue durée, supprimez également le répertoire de magasin résiduel sous `/mnt/memory/` avant la prochaine session qui attache ce magasin. Une sandbox qui sert une seule session puis est supprimée ne nécessite aucun nettoyage.

## Dépannage

### Le worker ne se connecte pas

Si `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) reste à 0, le worker n’atteint pas la file d’attente. Vérifiez que `ANTHROPIC_ENVIRONMENT_KEY` et `ANTHROPIC_ENVIRONMENT_ID` sont définis sur l’hôte du worker.

### Une session reste en file d’attente

Aucun worker ne réclame de travail. Une session en file d’attente attend plutôt que d’échouer. Vérifiez `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) et `depth` (csharp, go: `Depth`) dans [Consulter la profondeur de la file d’attente](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-operations#read-queue-depth).

### Les magasins de mémoire ne parviennent pas à se monter ou à se synchroniser

L’endroit où un échec de magasin de mémoire apparaît dépend de sa nature :

* **Un échec de montage :** si le worker ne peut pas monter un magasin de mémoire lorsqu’il réclame une session, il consigne l’échec dans son journal et fait échouer l’élément de travail. La session n’émet aucun événement d’erreur et reste inactive.
* **Un échec de synchronisation :** le worker consigne l’échec dans son journal et ne le signale pas à la session.
* **Une écriture refusée dans un magasin en lecture seule :** l’agent reçoit une erreur d’outil. Consultez [Magasins en lecture seule et conflits](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#read-only-stores-and-conflicts).

| Symptôme | Cause | Correctif |
| ----- | ----- | ----- |
| Le journal du worker contient `the work item carried no sessions token` (en Go, l’erreur `ErrSessionMemoryNoToken`) et l’élément de travail échoue. | Le `secret` (csharp, go: `Secret`) par session de l’élément de travail n’a pas atteint le worker. Soit votre code ne l’a pas transmis, soit les magasins de mémoire sur les sandboxes auto-hébergées ne sont pas activés pour votre organisation. | [Transmettez le secret de l’élément de travail](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-per-session#forward-the-work-items-secret). Si le worker interroge la file et exécute les sessions dans un seul processus et journalise tout de même ce message, contactez le support. |
| Le journal du worker contient `something already exists at the memory store's path`. | Une autre session sur le même système de fichiers utilise ce chemin. Ou bien le worker d’une session précédente a été tué avant l’exécution de sa procédure de nettoyage, si bien que le répertoire est resté en place. | Vérifiez si un worker exécute encore une session qui utilise ce chemin. Si c’est le cas, ne supprimez pas le répertoire : le worker le supprime lorsqu’il en a terminé avec la session. Sinon, supprimez le répertoire indiqué par la ligne de journal. Les modifications qu’il contient et qui n’avaient pas été synchronisées sont perdues. Pour exécuter deux sessions de ce type simultanément, consultez [Isoler les sessions qui partagent un magasin](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#isolate-sessions-that-share-a-store). |
| Le journal du worker contient `cannot create the memory store's folder` et `the worker host must make this mount path writable`. | L’utilisateur sous lequel le worker s’exécute ne peut pas créer de répertoires sous `/mnt/memory`. | Créez `/mnt/memory` et attribuez-le à cet utilisateur avec `chown`. Consultez [Préparer l’hôte](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). Sur macOS, suivez plutôt [Préparer un hôte macOS](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host). |
| La session reste `idle` avec une raison d’arrêt `requires_action` et aucun événement d’erreur peu après qu’un worker l’a réclamée. | Le worker a fait échouer l’élément de travail parce qu’il n’a pas pu monter un magasin de mémoire, pour l’une des raisons précédentes. | Corrigez la cause sur l’hôte, puis envoyez un événement [`user.interrupt`](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming#interrupt-the-agent). Le travail de la session est remis en file d’attente, et le prochain worker qui le réclame retente le montage. |

### Un appel d’outil personnalisé ne renvoie jamais de résultat

Si la session reste en pause avec une raison d’arrêt `requires_action`, aucun worker ni client ne sert cet outil. Consultez [Servir un outil personnalisé](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-custom-tools#serve-a-custom-tool).

### Un appel d’outil MCP encapsulé reste bloqué

Sans délai d’expiration sur le client MCP, un appel bloqué vers un [serveur MCP encapsulé](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-custom-tools#wrap-an-mcp-server-as-custom-tools) ne devient un résultat d’outil en erreur que lorsqu’un mécanisme de secours se déclenche :

| SDK | Mécanisme de secours | Se déclenche après |
| ----- | ----- | ----- |
| Python | La limite d’appel d’outil propre au worker | Environ 2,5 minutes |
| TypeScript | Le délai d’expiration de requête par défaut du SDK MCP | Environ une minute |
| Go | Le worker annule un appel d’outil qui dépasse sa limite par défaut | 120 secondes |
