--- title: Riferimento per i worker self-hosted url: https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference description: "Riferimento per i worker di sandbox self-hosted: flag della CLI ant, variabili d'ambiente, requisiti dell'host, percorsi del filesystem e opzioni degli helper dell'SDK." featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Questa pagina documenta i worker predefiniti che servono un ambiente `self_hosted`. Per guide orientate alle attività, inizia con [Sandbox self-hosted](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes) e [Distribuire worker self-hosted](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers). ## Comandi e flag della CLI | Comando | Descrizione | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ant beta:worker poll` | Acquisisce gli elementi di lavoro dalla coda dell'ambiente ed esegue ogni sessione nel processo. Con `--on-work`, chiama invece il tuo script per ogni elemento di lavoro. | | `ant beta:worker run` | Gestisce una singola sessione acquisita e termina. Usalo come entrypoint di una sandbox per sessione. | | Flag | Descrizione | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--environment-id` | L'ambiente da interrogare per il lavoro. Viene letto anche da `ANTHROPIC_ENVIRONMENT_ID`. | | `--environment-key` | Autentica il worker con questo ambiente. Viene letto anche da `ANTHROPIC_ENVIRONMENT_KEY`. | | `--workdir` | Directory in cui vengono scaricate le skill e in cui gli strumenti leggono e scrivono file. Il valore predefinito è `.` (la directory corrente). | | `--on-work` | Script da chiamare per ogni elemento di lavoro acquisito invece di eseguire gli strumenti nel processo. Riceve i dettagli della sessione come variabili d'ambiente e l'elemento di lavoro come JSON sullo standard input. | | `--max-idle` | Quanto attendere, dopo che la sessione diventa inattiva con uno [stop reason](https://platform.claude.com/docs/it/build-with-claude/handling-stop-reasons) (motivo di arresto) `end_turn`, prima di arrestarsi. Il valore predefinito è `60s`. | | `--log-format` | Formato dell'output dei log. Usa `json` per l'acquisizione di log strutturati. Il valore predefinito è `text`. | ## Variabili d'ambiente | Variabile | Descrizione | Impostata da | | ------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ANTHROPIC_ENVIRONMENT_ID` | L'ambiente la cui coda viene servita dal worker. | Te, sull'host del worker. Il poller la passa allo script `--on-work`. | | `ANTHROPIC_ENVIRONMENT_KEY` | Autentica il worker presso la sua coda. | Te, sull'host del worker. Il poller la passa allo script `--on-work`. | | `ANTHROPIC_SESSION_ID` | La sessione rappresentata da un elemento di lavoro acquisito. | Il poller, per lo script `--on-work`. | | `ANTHROPIC_WORK_ID` | L'elemento di lavoro acquisito. | Il poller, per lo script `--on-work`. | | `ANTHROPIC_WORK_SECRET` | Il segreto per sessione dell'elemento di lavoro. | Te. Il poller non la imposta. Consulta [Inoltra il segreto dell'elemento di lavoro](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). | | `ANTHROPIC_BASE_URL` | Sovrascrive l'endpoint API predefinito. Facoltativa. | Te, sull'host del worker. | | `ANTHROPIC_WEBHOOK_SIGNING_KEY` | Verifica i payload dei webhook in arrivo. | Te, su un host che gestisce i webhook. | ## Requisiti dell'host | Worker | Requisito | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Tutti i worker | Un host Linux con `/bin/bash` esattamente in quel percorso. Lo strumento bash del worker lo invoca direttamente, senza consultare `PATH`. | | SDK TypeScript | `unzip` e `tar` nel `PATH`, e Node.js 22 o successivo. | | SDK Python e Go | Nessun binario aggiuntivo. Questi SDK usano le proprie librerie standard per l'estrazione degli archivi. | I [memory store](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#requirements) aggiungono i propri requisiti. ## Filesystem della sandbox | Percorso | Contenuto | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/workspace` | La directory di lavoro predefinita del sistema per l'esecuzione degli strumenti e il download delle skill. Se usi una directory di lavoro diversa, aggiorna il prompt di sistema del tuo agente in modo che Claude possa individuare i file delle skill. | | `/skills//` | Le skill scaricate dell'agente. | | `/mnt/memory//` | Una directory per ogni memory store collegato, nel `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) dello store (ad esempio, `/mnt/memory/user-preferences/`). Il worker crea queste directory quando acquisisce la sessione e le rimuove quando la sessione termina. | Negli ambienti self-hosted il prompt di sistema della sessione omette l'istruzione `/mnt/session/outputs` usata nelle sandbox gestite da Anthropic. I risultati finali finiscono ovunque l'agente li scriva nel filesystem della tua sandbox, in genere sotto la directory di lavoro. Le skill possono includere eseguibili che l'agente può eseguire direttamente. I worker della CLI e dell'SDK preservano i permessi di esecuzione registrati nel bundle della skill quando lo estraggono. Se implementi manualmente il download delle skill, sei responsabile dell'impostazione dei permessi di esecuzione. ## Helper dell'SDK Gli SDK Python, TypeScript e Go forniscono tre helper con diversi livelli di controllo: | Helper | Cosa fa | Quando usarlo | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | [`EnvironmentWorker`](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#environment-worker) | Gestisce polling, configurazione ed esecuzione dall'inizio alla fine. | Nella maggior parte dei casi. | | [`work.poller()` (go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#work-poller) | Interroga la coda di lavoro e ti fornisce ogni sessione acquisita. | Decidi tu cosa accade per ogni sessione, ad esempio avviare una sandbox invece di eseguire gli strumenti nel processo. | | [`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#session-tool-runner) | Esegue le chiamate agli strumenti per una singola sessione, dati l'ID della sessione e un elenco di strumenti. | Hai già acquisito il lavoro e ti serve solo il livello di esecuzione. | ### EnvironmentWorker | Metodo | Descrizione | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `run()` (go: `Run()`) | Viene eseguito indefinitamente, prendendo in carico le sessioni man mano che arrivano. | | `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | Gestisce un singolo elemento di lavoro acquisito e ritorna. Passa esplicitamente gli identificatori di lavoro, sessione e ambiente e il `work_secret` (typescript: `workSecret`; go: `WorkSecret`), oppure lascia che legga le [variabili `ANTHROPIC_*`](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#environment-variables). | | Opzione | Descrizione | | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools` (go: `ToolsFunc`) | Una factory che riceve l'`AgentToolContext` della sessione e restituisce l'elenco degli strumenti. Il valore predefinito è il toolset standard dell'agente. | | `memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) | Con quale frequenza i memory store collegati si riconciliano con il server mentre la sessione è in esecuzione. Consulta [Intervallo di sincronizzazione](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#sync-interval). | | `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) | Se i file che l'agente elimina localmente vengono eliminati anche dallo store. Consulta [Eliminazioni](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#deletions). | `EnvironmentWorker` gestisce automaticamente l'`AgentToolContext` e il set di strumenti. Passa una factory `tools` (go: `ToolsFunc`) per personalizzare l'elenco degli strumenti: ```python Python EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool]) ``` ```typescript TypeScript new EnvironmentWorker({ client, environmentId, environmentKey, tools: (ctx) => [betaBashTool(ctx), myCustomTool] }); ``` L'SDK C# non dispone di `EnvironmentWorker`. Per rispondere alle chiamate agli strumenti personalizzati dal tuo codice, invia ogni risultato sul flusso di eventi della sessione, come in [Restituire il risultato di uno strumento personalizzato](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#return-a-custom-tool-result). ```go Go worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool { return []anthropic.BetaTool{agenttoolset.BetaBashTool(env), myCustomTool} }, }) ``` L'SDK Java non dispone di `EnvironmentWorker`. Per rispondere alle chiamate agli strumenti personalizzati dal tuo codice, invia ogni risultato sul flusso di eventi della sessione, come in [Restituire il risultato di uno strumento personalizzato](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#return-a-custom-tool-result). L'SDK PHP non dispone di `EnvironmentWorker`. Per rispondere alle chiamate agli strumenti personalizzati dal tuo codice, invia ogni risultato sul flusso di eventi della sessione, come in [Restituire il risultato di uno strumento personalizzato](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#return-a-custom-tool-result). L'SDK Ruby non dispone di `EnvironmentWorker`. Per rispondere alle chiamate agli strumenti personalizzati dal tuo codice, invia ogni risultato sul flusso di eventi della sessione, come in [Restituire il risultato di uno strumento personalizzato](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#return-a-custom-tool-result). ### Work poller | Opzione | Descrizione | | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `drain` (go: `Drain`) | Se interrompere il polling quando la coda è vuota invece di attendere nuovo lavoro. | | `block_ms` (typescript: `blockMs`; go: `BlockMs`) | Quanto attende ogni poll l'arrivo di lavoro prima di ritornare, in millisecondi. Deve essere compreso tra 1 e 999; l'helper ripete automaticamente il polling. Passa `null` (python: `None`; go: `param.Null[int64]()`) per un controllo non bloccante. Il valore predefinito è un long-poll di 999 ms. | | `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | Acquisisce nuovamente gli elementi di lavoro che sono stati acquisiti ma mai confermati entro questo numero di millisecondi. | | `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | Se inviare un segnale di arresto per ogni elemento di lavoro una volta che il corpo del tuo ciclo ha finito di elaborarlo. Impostalo su `false` (python: `False`; go: `param.NewOpt(false)`) quando ciò che esegue l'elemento di lavoro invia l'arresto autonomamente. `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) lo fa, così come una sandbox da te avviata che gestisce la chiamata di arresto. | Per un esempio completo, consulta [Avvia le sandbox dal poller dell'SDK](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers#launch-sandboxes-from-the-sdk-poller). ### Session tool runner `client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`) accetta un elenco di strumenti come `tools` (go: `Tools`). Per costruire tale elenco, configura tu stesso `AgentToolContext` e chiama `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`): ```python Python from anthropic.lib.tools.agent_toolset import ( AgentToolContext, beta_agent_toolset_20260401, ) async with AgentToolContext( workdir="/workspace", client=client, session_id=work.data.id ) as env: # skills scaricate in /workspace/skills// tools = beta_agent_toolset_20260401(env) ``` ```typescript TypeScript import { setupSkills, betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node"; const ctx = { workdir: "/workspace", client, sessionId: work.data.id }; await setupSkills(ctx); const tools = betaAgentToolset20260401(ctx); ``` L'SDK C# non dispone di `AgentToolContext`. ```go Go env := &agenttoolset.AgentToolContext{Workdir: "/workspace"} if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil { panic(err) } // skills scaricate in /workspace/skills// tools := agenttoolset.BetaAgentToolset20260401(env) ``` L'SDK Java non dispone di `AgentToolContext`. L'SDK PHP non dispone di `AgentToolContext`. L'SDK Ruby non dispone di `AgentToolContext`. ### AgentToolContext e il toolset dell'agente `AgentToolContext` è il contesto di esecuzione per le chiamate agli strumenti. Definisce la directory di lavoro e la policy dei percorsi, e può scaricare le skill della sessione. | Opzione | Descrizione | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`) | Directory, oltre alla directory di lavoro, raggiungibili dagli strumenti per i file (`read`, `write`, `edit`, `glob`, `grep`). | | `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`) | Directory sotto le quali `write` e `edit` rifiutano i percorsi. | `EnvironmentWorker` aggiunge autonomamente le directory dei memory store della sessione a `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`), e le directory degli store collegati con `access: "read_only"` a `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`). Il confinamento è una protezione solo per gli strumenti per i file, non una sandbox. Non vincola `bash`. `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`) accetta un `AgentToolContext` e restituisce le implementazioni standard degli strumenti (`bash`, `read`, `write`, `edit`, `glob`, `grep`).