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 il worker scarica le skill e in cui gli strumenti leggono e scrivono file. Il valore predefinito è . (la directory corrente). La directory deve esistere prima dell’avvio del worker. |
--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 tempo il worker attende mentre una sessione è inattiva prima che ant beta:worker run termini o che ant beta:worker poll passi all’elemento di lavoro successivo. Il tempo di inattività con uno stop reason requires_action (motivo di arresto) non viene conteggiato. Il valore predefinito è 60s. Impostalo su 0 per disattivare il timeout. Con uno script --on-work, ant beta:worker poll ignora questo flag. Passalo invece al comando ant beta:worker run avviato dal tuo script. |
--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 dell’elemento di lavoro per la sua sessione. | 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 o macOS con /bin/bash esattamente in quel percorso. Lo strumento bash del worker lo esegue direttamente, senza consultare PATH. Su macOS, si tratta del Bash 3.2 di sistema. |
| 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.
Su macOS, il volume radice è di sola lettura, quindi mkdir non può creare /workspace. Imposta la directory di lavoro del worker su una in cui puoi scrivere, come una directory workspace nella tua home directory. Per usare gli archivi di memoria su macOS, prima prepara l’host macOS.
Filesystem della sandbox
| Percorso | Contenuto |
|---|---|
/workspace | La directory di lavoro usata negli esempi delle pagine sulle sandbox self-hosted. Non è quella predefinita del worker: il worker usa la directory corrente a meno che tu non imposti --workdir o workdir. Le sandbox cloud di Anthropic conservano skill e repository in /workspace. 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 copia locale di ogni memory store collegato, una directory per store. L’API restituisce il percorso completo di ogni directory nel campo mount_path della risorsa memory store della sessione (ad esempio, /mnt/memory/user-preferences/). |
Il worker crea le directory dei memory store quando acquisisce una sessione. Le rimuove quando ha finito con quella sessione o quando arresti il worker in modo controllato. Questo rimuove solo le copie locali, e le memorie restano nello store.
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 scarichi le skill autonomamente, imposta tu stesso i loro permessi di esecuzione.
Quando il worker ha finito con una sessione
Il worker ha finito con una sessione in uno qualsiasi di questi casi:
- La sessione termina.
- Arresti l’elemento di lavoro della sessione.
- La sessione resta inattiva per tutto il limite di inattività del worker. La sessione stessa resta aperta. Quando poi le invii un nuovo evento, come un messaggio dell’utente, lo stesso worker o un altro la acquisisce. Quel worker scarica di nuovo gli store.
Il limite di inattività è di 60 secondi per impostazione predefinita. Per modificarlo, usa --max-idle per il worker della CLI ant o max_idle per EnvironmentWorker. Il chart Helm cma-sandboxes avvia invece i suoi worker con un limite di 30 minuti. Per modificare quel limite, modifica l’impostazione sandbox.idleTimeout del chart.
Risultati finali
Le sandbox self-hosted non hanno una directory /mnt/session/outputs. Nelle sandbox cloud di Anthropic, il prompt di sistema della sessione indica all’agente di copiarvi i risultati finali. Negli ambienti self-hosted, il prompt di sistema omette quell’istruzione. I risultati finali restano ovunque l’agente li scriva, in genere sotto la directory di lavoro, e il worker non li carica.
Per raccogliere i risultati finali in un unico posto, indica il percorso completo di una directory nel prompt di sistema del tuo agente. Scegli una directory in cui gli strumenti per i file del worker possano scrivere:
- All’interno della directory di lavoro: ad esempio,
/workspace/outputsse la directory di lavoro è/workspace. - In qualsiasi altro posto, solo con un worker dell’SDK: aggiungi la directory a
allowed_roots. Consulta AgentToolContext e il toolset dell’agente.
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 degli strumenti dall’inizio alla fine. | Nella maggior parte dei casi. |
work.poller() | Interroga la coda di lavoro e ti fornisce ogni sessione acquisita. | Decidi tu come gestire ogni sessione, ad esempio avviando 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 eseguire gli strumenti. |
EnvironmentWorker
| Metodo | Descrizione |
|---|---|
run() | Viene eseguito indefinitamente, prendendo in carico le sessioni man mano che arrivano. |
handle_item() | Gestisce un elemento di lavoro già acquisito da un poller. Il poller può essere ant beta:worker poll --on-work o il tuo codice. Il metodo ritorna quando il worker ha finito con la sessione dell’elemento. Puoi passare work_id, session_id, environment_id e work_secret. Per ciascuno che ometti, il metodo legge la variabile ANTHROPIC_* corrispondente. |
| 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. |
max_idle | Quanto tempo il worker attende mentre una sessione è inattiva prima di avere finito con la sessione. Il tempo di inattività con uno stop reason requires_action (motivo di arresto) non viene conteggiato. Il valore predefinito è 60 secondi. Per attendere 5 minuti, impostalo su 300. Per disattivare il limite, impostalo su None. |
memory_sync_interval | Il tempo minimo tra due sincronizzazioni dei memory store collegati mentre la sessione è in esecuzione. Il worker controlla l’intervallo dopo ogni chiamata a uno strumento eseguito nella tua sandbox, non in base a un timer. Il valore predefinito è 15 secondi. 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:
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic, beta_async_tool
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_bash_tool
@beta_async_tool
async def get_order_status(order_id: str) -> str:
"""Look up an order in the internal fulfillment system by order ID."""
return f"Order {order_id}: shipped"
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
async with AsyncAnthropic(auth_token=environment_key) as client:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
# Elenca ogni strumento che l'agente può chiamare. Il worker non risponde ad altri strumenti.
tools=lambda env: [beta_bash_tool(env), get_order_status],
)
task = asyncio.create_task(worker.run())
loop = asyncio.get_running_loop()
for signum in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(signum, task.cancel)
with contextlib.suppress(asyncio.CancelledError):
await task
asyncio.run(main())Work poller
| Opzione | Descrizione |
|---|---|
drain | Se interrompere il polling quando la coda è vuota invece di attendere nuovo lavoro. |
block_ms | Quanto attende ogni richiesta di polling 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 polling di 999ms. |
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 il poller invia un segnale di arresto per ogni elemento di lavoro una volta che il corpo del tuo ciclo ha finito di elaborarlo. Il valore predefinito è True. Impostalo su False nei due casi che seguono questa tabella. |
Imposta auto_stop su False in due casi:
- Il tuo ciclo chiama
handle_item(), che invia l’arresto autonomamente. - Il tuo ciclo avvia una sandbox per l’elemento e passa oltre. Il worker in quella sandbox deve inviare l’arresto quando il lavoro della sessione termina, come fanno
ant beta:worker runehandle_item().
Per un esempio completo, consulta Avvia le sandbox dal poller dell’SDK.
Tool runner di sessione
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:
# skill 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 degli archivi di memoria della sessione a allowed_roots, e le directory degli archivi di memoria 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).
Questa pagina ti è stata utile?