---
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
---
Les appels de surveillance présentés sur cette page s'exécutent depuis vos outils de surveillance ou d'exploitation, authentifiés avec votre clé API Claude. 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.
Ces points de terminaison 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.
## 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é. |
```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
}
```
## 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 s'en aperçoit 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`.
Passez `force: true` (python: `force=True`; cli: `--force`) pour marquer immédiatement l'élément de travail comme `stopped` au lieu d'attendre la confirmation du worker.
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, listez les éléments de travail de l'environnement via les [points de terminaison Environments Work](https://platform.claude.com/docs/fr/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
```
## Arrêter les workers proprement
Un worker annulé pendant l'exécution d'une session arrête son travail en cours avant de se terminer. 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 ignore la synchronisation finale mais téléverse tout de même les fichiers modifiés et supprime les répertoires des magasins.
Un processus tué 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 libère l'élément de travail. |
| 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 prévoyez au moins 30 secondes avant tout arrêt forcé.** Le téléversement final peut prendre ce temps. Par défaut, Docker envoie SIGKILL 10 secondes après le signal d'arrêt. Augmentez cette limite avec `--stop-timeout` sur `docker run`, ou avec le délai de grâce de terminaison de votre orchestrateur.
Si un worker est tué avant l'exécution de sa procédure de nettoyage, toutes les modifications de mémoire non synchronisées sont perdues. 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
Le worker journalise les échecs de montage et de synchronisation en arrière-plan plutôt que de les signaler à la session. Seuls les refus liés à la lecture seule parviennent à l'agent, sous forme d'erreurs d'outil (voir [Magasins en lecture seule et conflits](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#read-only-stores-and-conflicts)).
Si le worker ne peut pas monter un magasin de mémoire lorsqu'il réclame une session, il fait échouer l'élément de travail. La session n'émet aucun événement d'erreur et reste inactive.
| 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-workers#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`. | Un répertoire résiduel d'une session précédente, généralement une session dont le worker a été tué avant l'exécution de sa procédure de nettoyage. | Supprimez le répertoire résiduel indiqué par la ligne de journal. Les modifications qu'il contient et qui n'avaient pas été synchronisées sont perdues. |
| 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). |
| 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 deux minutes et demie |
| 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 |