Monitorar e solucionar problemas de workers auto-hospedados

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.

Ler a profundidade da fila

client.beta.environments.work.stats() retorna o estado da fila de um ambiente:

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
}

Parar uma sessão de forma controlada

Use client.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 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.

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)

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 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 permanecer em 0, o worker não está alcançando a fila. Confirme se 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 e depth em Ler a profundidade da fila.

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).

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.

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.

Uma chamada de ferramenta MCP encapsulada trava

Sem um timeout no cliente MCP, uma chamada travada para um servidor MCP encapsulado só se torna um resultado de ferramenta com erro quando um mecanismo de contenção é acionado: