---
title: Supervisar y solucionar problemas de workers autoalojados
url: https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-operations
description: Lee la profundidad de la cola, detén sesiones y workers sin perder trabajo, y corrige fallos comunes de sandboxes autoalojados.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: No es elegible para ZDR, excepto Managed Agents autoalojado. Las sesiones son recursos con estado; las transcripciones persisten hasta que las eliminas.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
    Claude Models on Google Cloud (Anthropic managed):
      availability: beta
      note: Escribes tu propio worker, que llama a los endpoints de trabajo del entorno.
---

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.

<Warning>
  Los endpoints de estadísticas de la cola y de detención aceptan tanto la clave de API de tu organización como la clave del entorno. Llámalos desde fuera del host del worker con la clave de API de tu organización. Configurar `ANTHROPIC_API_KEY` en el host del worker expone una credencial con alcance de organización a las llamadas a herramientas del agente.
</Warning>

## Leer la profundidad de la cola

`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`) devuelve el estado de la cola de un entorno:

| Campo | Significado | Úsalo para |
| ----- | ----- | ----- |
| `depth` (csharp, go: `Depth`) | Elementos en espera de ser reclamados. | Escalar tu flota de workers o generar alertas por acumulación. |
| `pending` (csharp, go: `Pending`) | Elementos 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_at` (java, php: `oldestQueuedAt`; csharp, go: `OldestQueuedAt`) | Marca 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. `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) cuando no existe tal elemento. | Ver cuánto tiempo ha esperado el elemento más antiguo. |
| `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) | Workers que han sondeado en los últimos 30 segundos. | Generar alertas sobre la disponibilidad. |

<CodeGroup>
  ```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: 2026-10-21"
  ```

  ```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/v2"
  )

  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
  <?php

  use Anthropic\Client;

  $client = new Client();

  $stats = $client->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}"
  ```
</CodeGroup>

```json
{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}
```

## Detener una sesión de forma ordenada

Usa `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`) 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` (python: `force=True`; csharp: `Force = true`; go: `BetaSelfHostedWorkStopRequest: anthropic.BetaSelfHostedWorkStopRequestParam{Force: anthropic.Bool(true)}`; java: `.force(true)`; cli: `--force`) 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 trabajo](https://platform.claude.com/docs/es/api/beta/environments/work/list) con la clave del entorno, enviada como `Authorization: Bearer $ANTHROPIC_ENVIRONMENT_KEY`. Ese endpoint rechaza la clave de API de tu organización.

<CodeGroup>
  ```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: 2026-10-21" \
    -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/v2"
  )

  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
  <?php

  use Anthropic\Client;

  $client = new Client();

  $work = $client->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
  ```
</CodeGroup>

## 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-operations#stop-a-session-gracefully). Si la sesión tiene [almacenes de memoria](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory) 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:

   | 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 marca el elemento de trabajo como `stopped`. |
   | 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 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 60` (python: `--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` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) 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` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) y `depth` (csharp, go: `Depth`) en [Leer la profundidad de la cola](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-operations#read-queue-depth).

### 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#read-only-stores-and-conflicts).

| Síntoma | Causa | Solució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` (csharp, go: `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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session#forward-the-work-items-secret). 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#isolate-sessions-that-share-a-store). |
| 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). En macOS, sigue en su lugar [Preparar un host macOS](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host). |
| 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`](https://platform.claude.com/docs/es/managed-agents/events-and-streaming#interrupt-the-agent). 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-custom-tools#serve-a-custom-tool).

### 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-custom-tools#wrap-an-mcp-server-as-custom-tools) se convierte en un resultado de herramienta con error solo cuando se activa un mecanismo de respaldo:

| SDK | Mecanismo de respaldo | Se activa después de |
| ----- | ----- | ----- |
| Python | El límite de tiempo propio del worker para cada llamada a herramienta | Aproximadamente 2.5 minutos |
| TypeScript | El tiempo de espera de solicitud predeterminado del SDK de MCP | Aproximadamente un minuto |
| Go | El worker cancela una llamada a herramienta que supera su límite predeterminado | 120 segundos |
