Claude Platform Docs
Managed AgentsSandboxes autoalojados

Supervisar y solucionar problemas de workers autoalojados

Lee la profundidad de la cola, detén sesiones y workers sin perder trabajo, y corrige fallos comunes de sandboxes autoalojados.

Las llamadas de estadísticas de la cola y de detención de esta página se ejecutan desde tus herramientas de supervisión u operaciones, autenticadas con la clave de API de tu organización. 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:

CampoSignificadoÚsalo para
depthElementos en espera de ser reclamados.Escalar tu flota de workers o generar alertas por acumulación.
pendingElementos reclamados por un worker pero aún no confirmados. Los helpers del worker confirman cada elemento antes de procesarlo, por lo que este valor se mantiene cerca de cero en funcionamiento normal.Detectar un worker que se detuvo entre la reclamación y la confirmación: genera una alerta ante un valor distinto de cero sostenido.
oldest_queued_atMarca de tiempo del elemento más antiguo que sigue en la cola, ya sea en espera de ser reclamado o reclamado pero aún no confirmado. None cuando no existe tal elemento.Ver cuánto tiempo ha esperado el elemento más antiguo.
workers_pollingWorkers que han sondeado en los últimos 30 segundos.Generar alertas sobre la disponibilidad.
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. Un worker del SDK de Python, en cambio, deja que la llamada a herramienta en curso termine primero, lo que puede tardar hasta 2.5 minutos.

Pasa force=True para marcar el elemento de trabajo como stopped de inmediato en lugar de esperar la confirmación del worker. Una detención forzada no hace que una llamada a herramienta en curso termine antes, porque el worker de todos modos detecta la detención en su siguiente heartbeat.

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, llama a Listar elementos de trabajoVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. con la clave del entorno, enviada como Authorization: Bearer $ANTHROPIC_ENVIRONMENT_KEY. Ese endpoint rechaza la clave de API de tu organización.

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 cierra esa sesión antes de salir, igual que cuando detienes una sesión. Si la sesión tiene almacenes de memoria adjuntos, el worker aun así sube los archivos nuevos y modificados y elimina los directorios de los almacenes. No envía eliminaciones, por lo que una memoria que el agente eliminó permanece en el almacén a menos que una sincronización anterior ya la haya eliminado del almacén.

Un proceso que termina abruptamente 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:

    WorkerQué hacer
    CLI antNada. La CLI gestiona ambas señales por sí misma: cancela cualquier llamada a herramienta en curso, publica su resultado de error y marca el elemento de trabajo como stopped.
    Worker del SDK que es su propio procesoEnvironmentWorker 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 webhooksCancela 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 dale tiempo para terminar antes de cualquier terminación forzada. El worker necesita tiempo para finalizar una llamada a herramienta en curso y para subir los archivos modificados a un almacén de memoria. 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 210 en docker run, o configura el período de gracia de terminación de tu orquestador con el mismo número de segundos.

Si un worker se detiene antes de que se ejecute su limpieza, pierdes 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 configurados 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 o no se sincronizan

Dónde aparece un fallo de un almacén de memoria depende de su tipo:

  • Un fallo de montaje: Si el worker no puede montar un almacén de memoria cuando reclama una sesión, escribe el fallo en su registro y marca el elemento de trabajo como fallido. La sesión no emite ningún evento de error y permanece inactiva.
  • Un fallo de sincronización: El worker escribe el fallo en su registro y no lo informa a la sesión.
  • Una escritura rechazada en un almacén de solo lectura: El agente recibe un error de herramienta. Consulta Almacenes de solo lectura y conflictos.
SíntomaCausaSolución
El registro del worker contiene the work item carried no sessions token (en Go, el error ErrSessionMemoryNoToken) y el elemento de trabajo falla.El secret por sesión del elemento de trabajo no llegó al worker. O bien tu código no lo reenvió, o los almacenes de memoria en sandboxes autoalojados no están habilitados para tu organización.Reenvía el secreto del elemento de trabajo. Si el worker sondea y ejecuta sesiones en un solo proceso y aun así registra esto, contacta con soporte.
El registro del worker contiene something already exists at the memory store's path.Otra sesión en el mismo sistema de archivos está usando esa ruta. O bien el worker de una sesión anterior se terminó a la fuerza antes de que se ejecutara su limpieza, por lo que el directorio quedó sin eliminar.Comprueba si un worker aún ejecuta una sesión que usa esa ruta. Si es así, no elimines el directorio: el worker lo elimina cuando termina con la sesión. Si no es así, elimina el directorio que indica la línea del registro. Las ediciones en él que no se hayan sincronizado se pierden. Para ejecutar dos de esas sesiones a la vez, consulta Aislar sesiones que comparten un almacén.
El registro del worker contiene cannot create the memory store's folder y the worker host must make this mount path writable.El usuario con el que se ejecuta el worker no puede crear directorios en /mnt/memory.Crea /mnt/memory y aplica chown para asignarlo a ese usuario. Consulta Preparar el host. En macOS, sigue en su lugar Preparar un host macOS.
La sesión queda en idle con un motivo de detención requires_action y sin evento de error poco después de que un worker la reclamara.El worker marcó el elemento de trabajo como fallido porque no pudo montar un almacén de memoria, por uno de los motivos anteriores.Corrige la causa en el host y luego envía un evento user.interrupt. El trabajo de la sesión vuelve a ponerse en cola, y el siguiente worker que lo reclame reintenta el montaje.

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:

SDKMecanismo de respaldoSe activa después de
PythonEl límite de tiempo propio del worker para cada llamada a herramientaAproximadamente 2.5 minutos
TypeScriptEl tiempo de espera de solicitud predeterminado del SDK de MCPAproximadamente un minuto
GoEl worker cancela una llamada a herramienta que supera su límite predeterminado120 segundos

¿Te resultó útil esta página?