Supervisar y solucionar problemas de workers autoalojados

Las llamadas de supervisión de esta página se ejecutan desde tus herramientas de supervisión u operaciones, autenticadas con tu clave de API de Claude. Los helpers del worker gestionan el bucle de reclamación y mantenimiento de actividad, por lo que no llamas a esos endpoints directamente.

Leer la profundidad de la cola

client.beta.environments.work.stats() devuelve el estado de la cola de un entorno:

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
}

Detener una sesión de forma ordenada

Usa client.beta.environments.work.stop() para pedir al worker que gestiona una sesión específica que la cierre.

De forma predeterminada, el elemento de trabajo pasa a stopping. El worker lo detecta en su siguiente heartbeat de arrendamiento, cancela la llamada a herramienta en curso de la sesión y confirma el cierre. Luego, el elemento de trabajo pasa a stopped.

Pasa force=True para marcar el elemento de trabajo como stopped de inmediato en lugar de esperar la confirmación del worker.

Como estas llamadas se ejecutan desde tus herramientas de operaciones y no desde el host del worker, ANTHROPIC_WORK_ID no se configura automáticamente. Configúrala con el ID del elemento de trabajo de destino antes de ejecutar los siguientes ejemplos. Para encontrar el ID de un elemento de trabajo, lista los elementos de trabajo del entorno mediante los endpoints de 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)

Detener workers de forma ordenada

Un worker que se cancela mientras se ejecuta una sesión detiene su trabajo en curso antes de salir. Si la sesión tiene almacenes de memoria adjuntos, el worker omite la sincronización final, pero aun así sube los archivos modificados y elimina los directorios de los almacenes.

Un proceso terminado a la fuerza no ejecuta ninguna limpieza. Para detener un worker de forma limpia:

1. Asegúrate de que SIGTERM y SIGINT cancelen el worker. La forma depende del worker:

   Worker	Qué hacer
   CLI ant	Nada. La CLI gestiona ambas señales por sí misma: cancela cualquier llamada a herramienta en curso, publica su resultado de error y libera el elemento de trabajo.
   Worker del SDK que es su propio proceso	EnvironmentWorker no instala manejadores de señales. Cancela el worker desde un manejador de señales, como hacen los ejemplos de worker independiente.
   Worker del SDK dentro de un servidor de webhooks	Cancela el worker desde el hook de apagado del propio servidor, como hacen los ejemplos de webhooks. El worker no debe tomar el control de las señales del servidor.

2. Detén el worker con SIGTERM y espera al menos 30 segundos antes de cualquier terminación forzada. La subida final puede tardar ese tiempo. Docker envía SIGKILL 10 segundos después de la señal de detención de forma predeterminada. Aumenta ese límite con --stop-timeout en docker run, o con el período de gracia de terminación de tu orquestador.

Si un worker se termina a la fuerza antes de que se ejecute su limpieza, se pierden las ediciones de memoria que no se hayan sincronizado. En un host de larga duración, elimina también el directorio de almacén sobrante en /mnt/memory/ antes de la siguiente sesión que adjunte ese almacén. Un sandbox que atiende una sola sesión y luego se descarta no necesita limpieza.

Solución de problemas

El worker no se conecta

Si workers_polling se mantiene en 0, el worker no está llegando a la cola. Confirma que ANTHROPIC_ENVIRONMENT_KEY y ANTHROPIC_ENVIRONMENT_ID estén configuradas en el host del worker.

Una sesión permanece en cola

Ningún worker está reclamando trabajo. Una sesión en cola espera en lugar de fallar. Revisa workers_polling y depth en Leer la profundidad de la cola.

Los almacenes de memoria no se montan

El worker registra en sus logs los fallos de montaje y de sincronización en segundo plano en lugar de informarlos a la sesión. Solo los rechazos por solo lectura llegan al agente, como errores de herramienta (consulta Almacenes de solo lectura y conflictos).

Si el worker no puede montar un almacén de memoria cuando reclama una sesión, marca el elemento de trabajo como fallido. La sesión no emite ningún evento de error y permanece inactiva.

Una llamada a herramienta personalizada nunca regresa

Si la sesión permanece en pausa con un motivo de detención requires_action, ningún worker ni cliente atiende esa herramienta. Consulta Servir una herramienta personalizada.

Una llamada a herramienta MCP envuelta se bloquea

Sin un tiempo de espera en el cliente MCP, una llamada bloqueada a un servidor MCP envuelto se convierte en un resultado de herramienta con error solo cuando se activa un mecanismo de respaldo: