Riferimento per i worker self-hosted
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.
Questa pagina documenta i worker predefiniti che servono un ambiente self_hosted. Per guide orientate alle attività, inizia con Sandbox self-hosted e Distribuire worker self-hosted.
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 (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. |
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 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. |
<workdir>/skills/<name>/ | Le skill scaricate dell'agente. |
/mnt/memory/<store>/ | Una directory per ogni memory store collegato, nel mount_path dello store (ad esempio, /mnt/memory/user-preferences/). Il worker crea queste directory quando acquisisce la sessione e le rimuove al termine della sessione. |
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 | Gestisce polling, configurazione ed esecuzione dall'inizio alla fine. | Nella maggior parte dei casi. |
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() | 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() | Viene eseguito indefinitamente, prendendo in carico le sessioni man mano che arrivano. |
handle_item() | Gestisce un singolo elemento di lavoro acquisito e ritorna. Passa esplicitamente gli identificatori di lavoro, sessione e ambiente e il work_secret, oppure lascia che legga le variabili ANTHROPIC_*. |
| Opzione | Descrizione |
|---|---|
tools | 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 | Con quale frequenza i memory store collegati si riconciliano con il server mentre la sessione è in esecuzione. Consulta Intervallo di sincronizzazione. |
memory_sync_deletions | Se i file che l'agente elimina localmente vengono eliminati anche dallo store. Consulta Eliminazioni. |
EnvironmentWorker gestisce automaticamente l'AgentToolContext e il set di strumenti. Passa una factory tools per personalizzare l'elenco degli strumenti:
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])Work poller
| Opzione | Descrizione |
|---|---|
drain | Se interrompere il polling quando la coda è vuota invece di attendere nuovo lavoro. |
block_ms | 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 None per un controllo non bloccante. Il valore predefinito è un long-poll di 999 ms. |
reclaim_older_than_ms | Acquisisce nuovamente gli elementi di lavoro che sono stati acquisiti ma mai confermati entro questo numero di millisecondi. |
auto_stop | 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 quando ciò che esegue l'elemento di lavoro invia l'arresto autonomamente. handle_item() 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.
Session tool runner
client.beta.sessions.events.tool_runner() accetta un elenco di strumenti come tools. Per costruire tale elenco, configura tu stesso AgentToolContext e chiama beta_agent_toolset_20260401(env):
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/<name>/
tools = beta_agent_toolset_20260401(env)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 | Directory, oltre alla directory di lavoro, raggiungibili dagli strumenti per i file (read, write, edit, glob, grep). |
read_only_roots | Directory sotto le quali write e edit rifiutano i percorsi. |
EnvironmentWorker aggiunge autonomamente le directory dei memory store della sessione a allowed_roots, e le directory degli store collegati con access: "read_only" a read_only_roots.
Il confinamento è una protezione solo per gli strumenti per i file, non una sandbox. Non vincola bash.
beta_agent_toolset_20260401(env) accetta un AgentToolContext e restituisce le implementazioni standard degli strumenti (bash, read, write, edit, glob, grep).
Was this page helpful?