Monitorare e risolvere i problemi dei worker self-hosted

Le chiamate di monitoraggio in questa pagina vengono eseguite dai tuoi strumenti di monitoraggio o di gestione operativa, autenticate con la tua chiave API di Claude. Gli helper del worker gestiscono il ciclo di acquisizione e keep-alive, quindi non devi chiamare direttamente quegli endpoint.

Leggere la profondità della coda

client.beta.environments.work.stats() restituisce lo stato della coda per un 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
}

Arrestare una sessione in modo controllato

Usa client.beta.environments.work.stop() per chiedere al worker che gestisce una sessione specifica di chiuderla.

Per impostazione predefinita l'elemento di lavoro passa a stopping. Il worker se ne accorge al successivo heartbeat del lease, annulla la chiamata allo strumento in corso della sessione e conferma l'arresto. L'elemento di lavoro diventa quindi stopped.

Passa force=True per contrassegnare immediatamente l'elemento di lavoro come stopped invece di attendere la conferma del worker.

Poiché queste chiamate vengono eseguite dai tuoi strumenti operativi anziché dall'host del worker, ANTHROPIC_WORK_ID non viene impostato automaticamente. Impostalo sull'ID dell'elemento di lavoro di destinazione prima di eseguire gli esempi seguenti. Per trovare l'ID di un elemento di lavoro, elenca gli elementi di lavoro dell'ambiente tramite gli endpoint 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)

Arrestare i worker in modo controllato

Un worker che viene annullato mentre una sessione è in esecuzione arresta il lavoro in corso prima di terminare. Se alla sessione sono collegati dei memory store, il worker salta la sincronizzazione finale ma carica comunque i file modificati e rimuove le directory degli store.

Un processo terminato forzatamente non esegue alcun teardown. Per arrestare un worker in modo pulito:

1. Assicurati che SIGTERM e SIGINT annullino il worker. Il modo dipende dal worker:

   Worker	Cosa fare
   CLI ant	Niente. La CLI gestisce autonomamente entrambi i segnali: annulla qualsiasi chiamata allo strumento in corso, invia il risultato di errore e rilascia l'elemento di lavoro.
   Worker SDK che è un processo a sé stante	EnvironmentWorker non installa gestori di segnali. Annulla il worker da un gestore di segnali, come fanno gli esempi di worker standalone.
   Worker SDK all'interno di un server webhook	Annulla il worker dall'hook di arresto del server stesso, come fanno gli esempi webhook. Il worker non deve prendere il controllo dei segnali del server.

2. Arresta il worker con SIGTERM e attendi almeno 30 secondi prima di qualsiasi terminazione forzata. Il caricamento finale può richiedere tutto quel tempo. Per impostazione predefinita Docker invia SIGKILL 10 secondi dopo il segnale di arresto. Aumenta questo limite con --stop-timeout su docker run, oppure con il periodo di tolleranza per la terminazione del tuo orchestratore.

Se un worker viene terminato forzatamente prima che venga eseguito il suo teardown, tutte le modifiche alla memoria non ancora sincronizzate vanno perse. Su un host di lunga durata, rimuovi anche la directory dello store rimasta in /mnt/memory/ prima della sessione successiva che collega quello store. Una sandbox che serve una sola sessione e viene poi eliminata non richiede alcuna pulizia.

Risoluzione dei problemi

Il worker non si connette

Se workers_polling resta a 0, il worker non raggiunge la coda. Verifica che ANTHROPIC_ENVIRONMENT_KEY e ANTHROPIC_ENVIRONMENT_ID siano impostati sull'host del worker.

Una sessione resta in coda

Nessun worker sta acquisendo il lavoro. Una sessione in coda resta in attesa anziché fallire. Controlla workers_polling e depth in Leggere la profondità della coda.

Il montaggio dei memory store non riesce

Il worker registra nei log gli errori di montaggio e di sincronizzazione in background anziché segnalarli alla sessione. Solo i rifiuti dovuti alla sola lettura raggiungono l'agente, come errori degli strumenti (vedi Store di sola lettura e conflitti).

Se il worker non riesce a montare un memory store quando acquisisce una sessione, fa fallire l'elemento di lavoro. La sessione non emette alcun evento di errore e resta inattiva.

Una chiamata a uno strumento personalizzato non restituisce mai un risultato

Se la sessione resta in pausa con uno stop reason requires_action, nessun worker o client serve quello strumento. Vedi Servire uno strumento personalizzato.

Una chiamata a uno strumento MCP incapsulato si blocca

Senza un timeout sul client MCP, una chiamata bloccata a un server MCP incapsulato diventa un risultato di errore dello strumento solo quando scatta un meccanismo di sicurezza: