---
title: Monitorare e risolvere i problemi dei worker self-hosted
url: https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-operations
description: Leggi la profondità della coda, arresta sessioni e worker senza perdere lavoro e risolvi i problemi comuni delle sandbox self-hosted.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
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.
Questi endpoint accettano sia la chiave API della tua organizzazione sia la chiave dell'ambiente. Chiamali dall'esterno dell'host del worker con la chiave API della tua organizzazione. Impostare `ANTHROPIC_API_KEY` sull'host del worker espone una credenziale con ambito di organizzazione alle chiamate agli strumenti dell'agente.
## Leggere la profondità della coda
`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`) restituisce lo stato della coda per un ambiente:
| Campo | Significato | Usalo per |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `depth` (csharp, go: `Depth`) | Elementi in attesa di essere acquisiti. | Scalare la tua flotta di worker o generare avvisi in caso di arretrato. |
| `pending` (csharp, go: `Pending`) | Elementi acquisiti da un worker ma non ancora confermati. Gli helper del worker confermano ogni elemento prima di elaborarlo, quindi questo valore resta vicino a zero durante il normale funzionamento. | Rilevare un worker bloccato tra l'acquisizione e la conferma: genera un avviso se il valore resta diverso da zero. |
| `oldest_queued_at` (java, php: `oldestQueuedAt`; csharp, go: `OldestQueuedAt`) | Timestamp dell'elemento più vecchio ancora in coda, in attesa di essere acquisito oppure acquisito ma non ancora confermato. `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) quando non esiste un elemento di questo tipo. | Vedere da quanto tempo attende l'elemento più vecchio. |
| `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) | Worker che hanno eseguito il polling negli ultimi 30 secondi. | Generare avvisi sulla liveness. |
```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
}
```
## Arrestare una sessione in modo controllato
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`) 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` (python: `force=True`; cli: `--force`) 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](https://platform.claude.com/docs/it/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
```
## 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](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory), 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` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) 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 lavoro. Una sessione in coda attende anziché fallire. Controlla `workers_polling` (java, php: `workersPolling`; csharp, go: `WorkersPolling`) e `depth` (csharp, go: `Depth`) in [Leggere la profondità della coda](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-operations#read-queue-depth).
### 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](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#read-only-stores-and-conflicts)).
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.
| Sintomo | Causa | Soluzione |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Il log del worker contiene `the work item carried no sessions token` (in Go, l'errore `ErrSessionMemoryNoToken`) e l'elemento di lavoro fallisce. | Il `secret` (csharp, go: `Secret`) per sessione dell'elemento di lavoro non ha raggiunto il worker. Il tuo codice non lo ha inoltrato, oppure i memory store sulle sandbox self-hosted non sono abilitati per la tua organizzazione. | [Inoltra il segreto dell'elemento di lavoro](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). Se il worker esegue il polling e le sessioni in un unico processo e registra comunque questo messaggio, contatta il supporto. |
| Il log del worker contiene `something already exists at the memory store's path`. | Una directory rimasta da una sessione precedente, di solito una il cui worker è stato terminato forzatamente prima che venisse eseguito il suo teardown. | Rimuovi la directory rimasta indicata dalla riga di log. Le modifiche al suo interno non ancora sincronizzate vanno perse. |
| Il log del worker contiene `cannot create the memory store's folder` e `the worker host must make this mount path writable`. | L'utente con cui viene eseguito il worker non può creare directory in `/mnt/memory`. | Crea `/mnt/memory` ed esegui `chown` assegnandola a quell'utente. Vedi [Preparare l'host](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). |
| La sessione resta `idle` con uno stop reason `requires_action` e nessun evento di errore poco dopo che un worker l'ha acquisita. | Il worker ha fatto fallire l'elemento di lavoro perché non è riuscito a montare un memory store, per uno dei motivi precedenti. | Correggi la causa sull'host, quindi invia un evento [`user.interrupt`](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#interrupt-the-agent). Il lavoro della sessione viene rimesso in coda e il worker successivo che lo acquisisce riprova il montaggio. |
### 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](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-custom-tools#serve-a-custom-tool).
### Una chiamata a uno strumento MCP incapsulato si blocca
Senza un timeout sul client MCP, una chiamata bloccata a un [server MCP incapsulato](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-custom-tools#wrap-an-mcp-server-as-custom-tools) diventa un risultato di errore dello strumento solo quando scatta un meccanismo di sicurezza:
| SDK | Meccanismo di sicurezza | Scatta dopo |
| ---------- | ---------------------------------------------------------------------------------- | ------------------------ |
| Python | Il limite delle chiamate agli strumenti del worker stesso | Circa due minuti e mezzo |
| TypeScript | Il timeout predefinito delle richieste dell'SDK MCP | Circa un minuto |
| Go | Il worker annulla una chiamata allo strumento che supera il suo limite predefinito | 120 secondi |