---
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
---
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.
Estos endpoints 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.
## 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. |
```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: 2023-06-01"
```
```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"
)
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
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}"
```
```text wrap
{
"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`.
Pasa `force: true` (python: `force=True`; cli: `--force`) 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](https://platform.claude.com/docs/es/api/beta/environments/work).
```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: 2023-06-01" \
-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"
)
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
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
```
## 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory) 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` (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
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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#read-only-stores-and-conflicts)).
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.
| Síntoma | Causa | Solución |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| El log 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-workers#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 log del worker contiene `something already exists at the memory store's path`. | Un directorio sobrante de una sesión anterior, normalmente una cuyo worker se terminó a la fuerza antes de que se ejecutara su limpieza. | Elimina el directorio sobrante que indica la línea del log. Las ediciones en él que no se hayan sincronizado se pierden. |
| El log 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 asígnalo a ese usuario con `chown`. Consulta [Preparar el host](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#prepare-the-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 | Unos dos minutos y medio |
| 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 |