Claude Platform Docs
Managed AgentsSandboxes auto-hébergées

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

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.

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.

Consulter la profondeur de la file d’attente

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

ChampSignificationUtilisez-le pour
depthÉléments en attente de réclamation.Dimensionner votre flotte de workers ou déclencher une alerte en cas d’arriéré.
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_atHorodatage 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é. None lorsqu’aucun élément de ce type n’existe.Voir depuis combien de temps l’élément le plus ancien attend.
workers_pollingWorkers ayant interrogé la file au cours des 30 dernières secondes.Déclencher une alerte sur la disponibilité.
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 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 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 travailAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. 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.

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 cette session avant de se terminer, comme lorsque vous arrêtez une session. Si des magasins de mémoire 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 :

    WorkerQue faire
    CLI antRien. 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 processusEnvironmentWorker 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 webhookAnnulez 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 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 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 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.
SymptômeCauseCorrectif
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 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. 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.
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. Sur macOS, suivez plutôt Préparer un hôte macOS.
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. 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é.

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 :

SDKMécanisme de secoursSe déclenche après
PythonLa limite d’appel d’outil propre au workerEnviron 2,5 minutes
TypeScriptLe délai d’expiration de requête par défaut du SDK MCPEnviron une minute
GoLe worker annule un appel d’outil qui dépasse sa limite par défaut120 secondes

Cette page vous a-t-elle été utile ?