Claude Platform Docs
Managed AgentsSandbox self-hosted

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

ComandoDescrizione
ant beta:worker pollAcquisisce 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 runGestisce una singola sessione acquisita e termina. Usalo come entrypoint di una sandbox per sessione.
FlagDescrizione
--environment-idL’ambiente da interrogare per il lavoro. Viene letto anche da ANTHROPIC_ENVIRONMENT_ID.
--environment-keyAutentica il worker con questo ambiente. Viene letto anche da ANTHROPIC_ENVIRONMENT_KEY.
--workdirDirectory 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-workScript 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-idleQuanto 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-formatFormato dell’output dei log. Usa json per l’acquisizione di log strutturati. Il valore predefinito è text.

Variabili d’ambiente

VariabileDescrizioneImpostata da
ANTHROPIC_ENVIRONMENT_IDL’ambiente la cui coda viene servita dal worker.Te, sull’host del worker. Il poller la passa allo script --on-work.
ANTHROPIC_ENVIRONMENT_KEYAutentica il worker presso la sua coda.Te, sull’host del worker. Il poller la passa allo script --on-work.
ANTHROPIC_SESSION_IDLa sessione rappresentata da un elemento di lavoro acquisito.Il poller, per lo script --on-work.
ANTHROPIC_WORK_IDL’elemento di lavoro acquisito.Il poller, per lo script --on-work.
ANTHROPIC_WORK_SECRETIl 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_URLSovrascrive l’endpoint API predefinito. Facoltativa.Te, sull’host del worker.
ANTHROPIC_WEBHOOK_SIGNING_KEYVerifica i payload dei webhook in arrivo.Te, su un host che gestisce i webhook.

Requisiti dell’host

WorkerRequisito
Tutti i workerUn 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 TypeScriptunzip e tar nel PATH, e Node.js 22 o successivo.
SDK Python e GoNessun 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

PercorsoContenuto
/workspaceLa 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/outputs se 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:

HelperCosa faQuando usarlo
EnvironmentWorkerGestisce 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

MetodoDescrizione
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.
OpzioneDescrizione
toolsUna factory che riceve l’AgentToolContext della sessione e restituisce l’elenco degli strumenti. Il valore predefinito è il toolset standard dell’agente.
max_idleQuanto 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_intervalIl 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_deletionsSe 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

OpzioneDescrizione
drainSe interrompere il polling quando la coda è vuota invece di attendere nuovo lavoro.
block_msQuanto 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_msAcquisisce nuovamente gli elementi di lavoro che sono stati acquisiti ma mai confermati entro questo numero di millisecondi.
auto_stopSe 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:

  1. Il tuo ciclo chiama handle_item(), che invia l’arresto autonomamente.
  2. 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 run e handle_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.

OpzioneDescrizione
allowed_rootsDirectory, oltre alla directory di lavoro, raggiungibili dagli strumenti per i file (read, write, edit, glob, grep).
read_only_rootsDirectory 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?