--- title: Monitorar e solucionar problemas de workers auto-hospedados url: https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-operations description: Leia a profundidade da fila, pare sessões e workers sem perder trabalho e corrija falhas comuns de sandboxes auto-hospedados. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- As chamadas de monitoramento nesta página são executadas a partir das suas ferramentas de monitoramento ou operações, autenticadas com sua chave de API do Claude. Os helpers do worker cuidam do loop de reivindicação e keep-alive, então você não chama esses endpoints diretamente. Esses endpoints aceitam tanto a chave de API da sua organização quanto a chave do ambiente. Chame-os de fora do host do worker com a chave de API da sua organização. Definir `ANTHROPIC_API_KEY` no host do worker expõe uma credencial com escopo de organização às chamadas de ferramentas do agente. ## Ler a profundidade da fila `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`) retorna o estado da fila de um ambiente: | Campo | Significado | Use para | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | `depth` (csharp, go: `Depth`) | Itens aguardando para serem reivindicados. | Escalar sua frota de workers ou alertar sobre acúmulo. | | `pending` (csharp, go: `Pending`) | Itens reivindicados por um worker, mas ainda não confirmados. Os helpers do worker confirmam cada item antes de processá-lo, então esse valor fica próximo de zero em operação normal. | Detectar um worker que travou entre reivindicar e confirmar: alerte sobre um valor diferente de zero persistente. | | `oldest_queued_at` (java, php: `oldestQueuedAt`; csharp, go: `OldestQueuedAt`) | Timestamp do item mais antigo ainda na fila, seja aguardando para ser reivindicado ou reivindicado, mas ainda não confirmado. `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) quando não há tal item. | Ver há quanto tempo o item mais antigo está esperando. | | `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) | Workers que fizeram polling nos últimos 30 segundos. | Alertar sobre disponibilidade. | ```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 } ``` ## Parar uma sessão de forma controlada Use `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 ao worker que está lidando com uma sessão específica que a encerre. Por padrão, o item de trabalho passa para `stopping`. O worker percebe isso no próximo heartbeat do lease, cancela a chamada de ferramenta em andamento da sessão e confirma o encerramento. O item de trabalho então se torna `stopped`. Passe `force: true` (python: `force=True`; cli: `--force`) para marcar o item de trabalho como `stopped` imediatamente, em vez de aguardar a confirmação do worker. Como essas chamadas são executadas a partir das suas ferramentas de operações e não do host do worker, `ANTHROPIC_WORK_ID` não é definido automaticamente. Defina-o com o ID do item de trabalho de destino antes de executar os exemplos a seguir. Para encontrar o ID de um item de trabalho, liste os itens de trabalho do ambiente por meio dos [endpoints Environments Work](https://platform.claude.com/docs/pt-BR/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 ``` ## Parar workers de forma controlada Um worker que é cancelado enquanto uma sessão está em execução interrompe seu trabalho em andamento antes de sair. Se a sessão tiver [memory stores](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory) anexados, o worker pula a sincronização final, mas ainda faz upload dos arquivos alterados e remove os diretórios dos stores. Um processo encerrado à força não executa nenhuma rotina de finalização. Para parar um worker de forma limpa: 1. **Certifique-se de que SIGTERM e SIGINT cancelem o worker.** Como fazer isso depende do worker: | Worker | O que fazer | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CLI `ant` | Nada. A CLI lida com ambos os sinais por conta própria: ela cancela qualquer chamada de ferramenta em andamento, publica seu resultado de erro e libera o item de trabalho. | | Worker do SDK que é seu próprio processo | `EnvironmentWorker` não instala nenhum manipulador de sinais. Cancele o worker a partir de um manipulador de sinais, como fazem os exemplos de worker independente. | | Worker do SDK dentro de um servidor de webhook | Cancele o worker a partir do próprio hook de desligamento do servidor, como fazem os exemplos de webhook. O worker não deve assumir os sinais do servidor. | 2. **Pare o worker com SIGTERM e aguarde pelo menos 30 segundos antes de qualquer encerramento forçado.** O upload final pode levar esse tempo. Por padrão, o Docker envia SIGKILL 10 segundos após o sinal de parada. Aumente esse limite com `--stop-timeout` no `docker run` ou com o período de carência de encerramento do seu orquestrador. Se um worker for encerrado à força antes de sua rotina de finalização ser executada, quaisquer edições de memória que não tenham sido sincronizadas serão perdidas. Em um host de longa duração, remova também o diretório de store remanescente em `/mnt/memory/` antes da próxima sessão que anexar esse store. Um sandbox que atende a uma sessão e depois é descartado não precisa de limpeza. ## Solução de problemas ### O worker não se conecta Se `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) permanecer em 0, o worker não está alcançando a fila. Confirme que `ANTHROPIC_ENVIRONMENT_KEY` e `ANTHROPIC_ENVIRONMENT_ID` estão definidos no host do worker. ### Uma sessão permanece na fila Nenhum worker está reivindicando trabalho. Uma sessão na fila aguarda em vez de falhar. Verifique `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) e `depth` (csharp, go: `Depth`) em [Ler a profundidade da fila](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-operations#read-queue-depth). ### Memory stores não são montados O worker registra em log as falhas de montagem e de sincronização em segundo plano, em vez de reportá-las à sessão. Apenas recusas de somente leitura chegam ao agente, como erros de ferramenta (consulte [Stores somente leitura e conflitos](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#read-only-stores-and-conflicts)). Se o worker não conseguir montar um memory store ao reivindicar uma sessão, ele marca o item de trabalho como falho. A sessão não emite nenhum evento de erro e permanece ociosa. | Sintoma | Causa | Correção | | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | O log do worker contém `the work item carried no sessions token` (em Go, o erro `ErrSessionMemoryNoToken`) e o item de trabalho falha. | O `secret` (csharp, go: `Secret`) por sessão do item de trabalho não chegou ao worker. Ou seu código não o encaminhou, ou memory stores em sandboxes auto-hospedados não estão habilitados para sua organização. | [Encaminhar o segredo do item de trabalho](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). Se o worker faz polling e executa sessões em um único processo e ainda registra isso, entre em contato com o suporte. | | O log do worker contém `something already exists at the memory store's path`. | Um diretório remanescente de uma sessão anterior, geralmente uma cujo worker foi encerrado à força antes de sua rotina de finalização ser executada. | Remova o diretório remanescente indicado na linha de log. As edições nele que não foram sincronizadas são perdidas. | | O log do worker contém `cannot create the memory store's folder` e `the worker host must make this mount path writable`. | O usuário com o qual o worker é executado não consegue criar diretórios em `/mnt/memory`. | Crie `/mnt/memory` e aplique `chown` para esse usuário. Consulte [Preparar o host](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). | | A sessão fica `idle` com um motivo de parada `requires_action` e nenhum evento de erro logo após um worker reivindicá-la. | O worker marcou o item de trabalho como falho porque não conseguiu montar um memory store, por um dos motivos anteriores. | Corrija a causa no host e, em seguida, envie um evento [`user.interrupt`](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#interrupt-the-agent). O trabalho da sessão é colocado na fila novamente, e o próximo worker que o reivindicar tentará a montagem de novo. | ### Uma chamada de ferramenta personalizada nunca retorna Se a sessão ficar pausada com um motivo de parada `requires_action`, nenhum worker ou cliente serve essa ferramenta. Consulte [Servir uma ferramenta personalizada](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-custom-tools#serve-a-custom-tool). ### Uma chamada de ferramenta MCP encapsulada trava Sem um timeout no cliente MCP, uma chamada travada para um [servidor MCP encapsulado](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-custom-tools#wrap-an-mcp-server-as-custom-tools) só se torna um resultado de ferramenta com erro quando um mecanismo de contenção é acionado: | SDK | Mecanismo de contenção | Acionado após | | ---------- | --------------------------------------------------------------------------- | ---------------------------- | | Python | O próprio limite de chamada de ferramenta do worker | Cerca de dois minutos e meio | | TypeScript | O timeout de requisição padrão do SDK do MCP | Cerca de um minuto | | Go | O worker cancela uma chamada de ferramenta que ultrapassa seu limite padrão | 120 segundos |