Surveiller et dépanner les workers auto-hébergés

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.

Consulter la profondeur de la file d'attente

client.beta.environments.work.stats() renvoie l'état de la file d'attente d'un environnement :

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
}

Arrêter une session proprement

Utilisez client.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 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.

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)

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 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 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 et depth dans Consulter la profondeur de la file d'attente.

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

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.

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

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é ne devient un résultat d'outil en erreur que lorsqu'un mécanisme de secours se déclenche :