Sandbox self-hosted

Per impostazione predefinita, Managed Agents esegue strumenti e codice all'interno di sandbox cloud gestite da Anthropic. Le sandbox self-hosted mantengono l'orchestrazione dal lato di Anthropic ma spostano l'esecuzione degli strumenti in un'infrastruttura che controlli tu, così il codice dell'agente, il filesystem e il traffico di rete in uscita ("network egress") non lasciano mai il tuo ambiente.

L'esecuzione degli strumenti rimane sul tuo host: il filesystem che l'agente legge e scrive, i processi che avvia e la rete che può raggiungere sono tutti sotto il tuo controllo. Gli input e gli output degli strumenti continuano a fluire verso il control plane di Anthropic (dove viene eseguito Claude) in modo che il modello possa vedere i risultati e determinare cosa fare successivamente. Le skill dell'agente e i contenuti di eventuali memory store collegati alla sessione sono archiviati da Anthropic e copiati nella tua sandbox per la sessione; le modifiche che l'agente apporta ai file di memoria vengono sincronizzate nuovamente con lo store. Consulta il modello di sicurezza per il confine completo del flusso di dati.

In cosa differisce dagli ambienti cloud

Il self-hosting è adatto quando l'agente deve operare su dati che non possono lasciare il confine della tua rete, raggiungere servizi interni non instradabili pubblicamente o essere eseguito sotto i controlli di conformità e audit della tua organizzazione.

Per l'idoneità a Zero Data Retention e HIPAA BAA, consulta API e conservazione dei dati.

Quando combinarle con i tunnel MCP

Il self-hosting controlla dove viene eseguito il codice dell'agente. I tunnel MCP controllano come Anthropic raggiunge i server MCP nella tua rete. Sono indipendenti: una sessione in esecuzione nelle sandbox cloud di Anthropic può comunque raggiungere server MCP privati attraverso un tunnel, e una sessione self-hosted può usare server MCP sia tramite tunnel sia pubblici. Usa entrambi quando vuoi che l'esecuzione e l'accesso agli strumenti rimangano all'interno del tuo confine. Per fornire all'agente strumenti da un server MCP all'interno della tua rete senza eseguire un tunnel, puoi anche incapsulare il server come strumenti personalizzati serviti dal tuo worker.

Worker dell'ambiente

Un "environment worker" (worker dell'ambiente) è un processo che esegui sulla tua infrastruttura. Riceve richieste di esecuzione degli strumenti da Anthropic e le esegue localmente. L'ambiente self_hosted funge da coda di lavoro: quando una sessione gli viene assegnata, Anthropic accoda la sessione come elemento di lavoro ("work item"). Il tuo worker reclama gli elementi di lavoro da quella coda, avvia un contesto di esecuzione per ciascuno, scarica le skill dell'agente (risorse riutilizzabili basate su filesystem che forniscono all'agente competenze specifiche di dominio), esegue le chiamate agli strumenti e invia i risultati.

Gli elementi di lavoro vengono reclamati interrogando (polling) la coda dell'ambiente: tramite un worker sempre attivo che interroga continuamente, oppure un handler attivato da webhook che si attiva su session.status_run_started e inizia il polling.

Sia la CLI sia l'SDK includono worker precostruiti. La CLI ant supporta solo il pattern sempre attivo; l'SDK supporta sia quello sempre attivo sia quello attivato da webhook. Entrambi sono configurabili: consulta Worker self-hosted nel riferimento per i flag della CLI, e Helper dell'SDK in questa pagina per le opzioni dell'SDK. Per un maggiore controllo, chiama direttamente gli endpoint Environments Work e implementa il tuo worker.

Filesystem della sandbox

• /workspace: la directory di lavoro predefinita di sistema per l'esecuzione degli strumenti e il download delle skill. Il flag --workdir della CLI ha come valore predefinito la directory corrente; passa --workdir /workspace per corrispondere al valore predefinito di sistema. Le skill vengono scaricate in <workdir>/skills/<name>/. 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.
• Output: negli ambienti self-hosted il prompt di sistema della sessione omette l'istruzione /mnt/session/outputs usata nelle sandbox gestite da Anthropic, quindi i deliverable finali finiscono ovunque l'agente li scriva nel filesystem della tua sandbox, tipicamente sotto la directory di lavoro.
• /mnt/memory/: i memory store collegati alla sessione vengono materializzati qui dal worker dell'SDK, una directory per store al mount_path dello store (ad esempio, /mnt/memory/user-preferences/). Il worker crea queste directory quando reclama la sessione e le rimuove quando la sessione termina; consulta Usa i memory store.

Prima di iniziare

Ti servono:

• Un agente esistente. Se non ne hai uno, completa prima il Quickstart e annota il suo ID agente.
• Un host Linux con /bin/bash esattamente a quel percorso. Lo strumento bash del worker lo invoca direttamente, senza consultare PATH. L'SDK TypeScript richiede inoltre unzip e tar nel PATH e Node.js 22 o successivo; gli SDK Python e Go usano le loro librerie standard per l'estrazione degli archivi e non hanno requisiti binari aggiuntivi.
• La CLI ant o un SDK Anthropic (Python, TypeScript o Go) sull'host del worker.
• Credenziali: una chiave dell'ambiente (generata nella Console nei passaggi che seguono) autentica il worker presso la sua coda; la tua chiave API Claude crea le sessioni e legge le statistiche della coda dall'esterno dell'host del worker. La generazione delle chiavi è possibile solo dalla Console. Gli elementi di lavoro reclamati contengono anche un secret per sessione che il worker usa per montare i memory store; non lo generi tu, ma nel pattern sandbox-per-sessione lo inoltri tu stesso nella sandbox (consulta Esegui una sandbox per sessione).
• Per i memory store, un host preparato. Se le sessioni su questo ambiente collegheranno memory store, prepara /mnt/memory sull'host del worker prima di avviare il worker; consulta Prepara l'host.

1. 1

   Crea un ambiente self-hosted

   Nella Console: Workspace > Environments > New > Self-hosted

   Oppure tramite l'API:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client = anthropic.Anthropic()
   
   environment = client.beta.environments.create(
       name="self-hosted", config={"type": "self_hosted"}
   )
   print(environment.id)

2. 2

   Genera una chiave dell'ambiente

   Nella Console, apri l'ambiente e fai clic su Generate environment key. La generazione delle chiavi è possibile solo dalla Console, indipendentemente dal fatto che tu abbia creato l'ambiente tramite la Console o l'API. Quindi esporta l'ID e la chiave dell'ambiente sull'host del worker:

   export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
   export ANTHROPIC_ENVIRONMENT_ID="env_..."

   

Esegui un worker

Scegli sempre attivo per la configurazione più semplice: un processo a lunga esecuzione interroga continuamente la coda e necessita solo di HTTPS in uscita. Scegli attivato da webhook per evitare di eseguire un poller inattivo; richiede un endpoint webhook che Anthropic possa raggiungere (consulta Webhook per la configurazione dell'endpoint e la verifica della firma).

Helper dell'SDK

L'SDK fornisce tre helper a diversi livelli di controllo. EnvironmentWorker copre la maggior parte dei casi d'uso; passa agli helper di livello inferiore quando devi avviare il tuo processo per sessione o eseguire strumenti su una sessione già reclamata.

• EnvironmentWorker: il worker pronto all'uso. Gestisce polling, configurazione ed esecuzione dall'inizio alla fine.
  • .run(): viene eseguito indefinitamente, prendendo in carico le sessioni man mano che arrivano.
  • .handle_item(): gestisce un singolo elemento di lavoro reclamato e termina. Passa esplicitamente gli identificatori di lavoro, sessione e ambiente, oppure lascia che legga le variabili ANTHROPIC_* che ant beta:worker poll --on-work imposta per il processo che avvia. Per consentire alla sessione di montare i suoi memory store, passa anche il secret dell'elemento di lavoro come work_secret (workSecret in TypeScript, WorkSecret in Go) oppure imposta ANTHROPIC_WORK_SECRET; ant beta:worker poll --on-work non imposta quella variabile, quindi leggi il secret dal JSON dell'elemento di lavoro che scrive sullo standard input del tuo script, come mostrato in Esegui una sandbox per sessione.
  • memory_sync_interval (memorySyncIntervalMs in TypeScript, MemorySyncInterval in Go) e memory_sync_deletions (memorySyncDeletions, MemorySyncDeletions): con quale frequenza i memory store collegati si riconciliano con il server mentre la sessione è in esecuzione, e se i file che l'agente elimina localmente vengono eliminati anche dallo store. Consulta Configura la sincronizzazione per unità, valori predefiniti e come disabilitare il supporto della memoria.
• work.poller(): interroga la coda di lavoro per tuo conto e ti fornisce ogni sessione reclamata. Usalo quando vuoi decidere cosa accade per ogni sessione, ad esempio avviare una sandbox anziché eseguire gli strumenti in-process.
  • drain: se interrompere il polling una volta che la coda è vuota anziché attendere nuovo lavoro.
  • block_ms: quanto attendere l'arrivo di lavoro prima di restituire, in millisecondi. Deve essere compreso tra 1 e 999 (attesa per singolo poll; l'helper ripete il polling automaticamente). Passa null (None in Python, param.Null[int64]() in Go) per un controllo non bloccante; omettere il parametro usa il long-poll predefinito di 999 ms.
  • reclaim_older_than_ms: reclama nuovamente gli elementi di lavoro che sono stati reclamati ma mai confermati entro questo numero di millisecondi.
  • auto_stop (autoStop in TypeScript, AutoStop in Go): se inviare un segnale di stop per ogni elemento di lavoro una volta che il corpo del tuo ciclo ha finito con esso. Disattivalo ogni volta che ciò che esegue l'elemento di lavoro invia lo stop da sé: handle_item() lo fa, quindi impostalo su false quando passi gli elementi reclamati a handle_item() come fanno gli handler webhook in questa pagina, e lo fa anche una sandbox che avvii e che sia responsabile della chiamata di stop.
• 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. Usalo quando hai già reclamato il lavoro e ti serve solo il livello di esecuzione.

Usa direttamente il work poller quando vuoi avviare il tuo processo per sessione, ad esempio avviando una sandbox per ogni sessione reclamata:

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork

SANDBOX_ENV = (
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
)


async def launch_container(work: BetaSelfHostedWork) -> None:
    print(f"claimed session {work.data.id}")
    # Sostituisci `docker run` con il tuo launcher di sandbox. Inoltra la chiave
    # dell'ambiente (mai la tua chiave API) e il segreto per sessione del work item: il worker
    # all'interno necessita del segreto per montare gli archivi di memoria della sessione.
    env = os.environ | {
        "ANTHROPIC_WORK_ID": work.id,
        "ANTHROPIC_SESSION_ID": work.data.id,
        "ANTHROPIC_WORK_SECRET": work.secret or "",
    }
    forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
    launcher = await asyncio.create_subprocess_exec(
        "docker", "run", "--rm", "--detach", *forward, "your-sdk-worker-image", env=env
    )
    await launcher.wait()


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:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

Qualunque cosa avvii la sandbox deve inoltrare al suo interno il secret dell'elemento di lavoro reclamato (ad esempio come ANTHROPIC_WORK_SECRET) insieme agli identificatori di sessione, lavoro e ambiente, in modo che il worker all'interno possa montare i memory store della sessione; consulta Esegui una sandbox per sessione.

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. Gli strumenti per i file (read, write, edit, glob, grep) sono confinati alla directory di lavoro più eventuali directory elencate in allowed_roots (allowedRoots in TypeScript, AllowedRoots in Go), e write ed edit rifiutano inoltre i percorsi sotto read_only_roots (readOnlyRoots, ReadOnlyRoots). EnvironmentWorker aggiunge da sé le directory dei memory store della sessione a questi elenchi. 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).

Con EnvironmentWorker: entrambi sono gestiti automaticamente. Passa una factory tools per personalizzare l'elenco degli strumenti:

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

Con work.poller() e tool_runner(): passa un elenco di strumenti come tools a client.beta.sessions.events.tool_runner(). Per costruire quell'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)

Verifica che il worker sia connesso

Da una shell separata, con ANTHROPIC_API_KEY impostata sulla tua chiave API Claude (non la chiave dell'ambiente), conferma che workers_polling sia almeno 1:

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

Se workers_polling rimane a 0, il worker non sta raggiungendo la coda: conferma che ANTHROPIC_ENVIRONMENT_KEY e ANTHROPIC_ENVIRONMENT_ID siano impostate sull'host del worker. Consulta Leggi la profondità della coda per la risposta completa delle statistiche ed esempi in altri linguaggi.

Avvia una sessione

Una volta che il tuo worker è in esecuzione, crea una sessione che abbia come destinazione l'ambiente. Imposta AGENT_ID sull'ID agente che hai annotato in Prima di iniziare. La sessione entra nella coda di lavoro dell'ambiente e vi attende finché un worker non la reclama; se nessun worker è connesso, la sessione rimane in coda anziché fallire.

Anthropic non monta file o repository GitHub nelle sandbox self-hosted. Per rendere disponibili file specifici della sessione, passa riferimenti ai file (come un percorso S3 o uno SHA di commit) nel campo metadata della sessione. L'elemento di lavoro reclamato non contiene i metadata della sessione, ma contiene l'ID della sessione: il tuo script di avvio o handler --on-work recupera la sessione (GET /v1/sessions/{session_id}) per leggere il campo metadata, quindi predispone i file nella directory di lavoro prima che inizi l'esecuzione degli strumenti.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

Consulta Worker self-hosted nel riferimento per l'elenco completo dei flag della CLI, e Helper dell'SDK per le opzioni degli helper dell'SDK.

Usa i memory store

Le sessioni su un ambiente self-hosted collegano i memory store esattamente come fanno le sessioni sugli ambienti cloud: elencali in resources quando crei la sessione, come mostrato in Collega un memory store a una sessione. Una sessione accetta fino a 8 memory store. Su un ambiente self-hosted è il worker dell'SDK, anziché l'infrastruttura di Anthropic, a materializzare ogni store per l'agente, quindi lì i memory store richiedono EnvironmentWorker (o il suo metodo handle_item()) dall'SDK Python, TypeScript o Go.

Il worker della CLI ant (ant beta:worker poll e ant beta:worker run) non monta i memory store. Per combinare il poller della CLI con i memory store, esegui il worker dell'SDK all'interno di una sandbox per sessione come descritto in Esegui una sandbox per sessione.

I memory store non possono essere collegati a sessioni su ambienti self-hosted su Claude Platform on AWS.

Come il worker gestisce la memoria

Quando il worker reclama un elemento di lavoro la cui sessione ha memory store collegati:

1. Scarica ogni store collegato nel suo mount_path sull'host del worker, autenticandosi con il secret per sessione dell'elemento di lavoro. Il mount_path è la stessa directory sotto /mnt/memory/ usata dalle sessioni cloud (ad esempio, /mnt/memory/user-preferences/ per uno store chiamato "User Preferences"), e il prompt di sistema della sessione la descrive all'agente.
2. Aggiunge quelle directory alle root consentite degli strumenti per i file, e le directory degli store collegati con access: "read_only" alle loro root di sola lettura, in modo che l'agente lavori sulle memorie con gli stessi strumenti read, write, edit, glob e grep che usa nella directory di lavoro.
3. Riconcilia le modifiche locali e remote dopo le chiamate agli strumenti, al massimo una volta per intervallo di sincronizzazione (15 secondi per impostazione predefinita): le memorie modificate nello store vengono scritte su disco, e i file modificati dall'agente vengono caricati nello store.
4. Esegue una sincronizzazione finale quando la sessione termina, completa eventuali caricamenti ancora in sospeso per un massimo di 30 secondi, e quindi rimuove le directory che ha creato. Un worker che viene annullato mentre una sessione è in esecuzione salta la sincronizzazione finale ma carica comunque i file modificati e rimuove le directory prima di terminare.

Il memory store dal lato di Anthropic rimane la fonte di verità. Le versioni della memoria, la redazione e la visualizzazione o modifica delle memorie nella Console funzionano come per le sessioni cloud, e le letture e scritture di memoria dell'agente appaiono nel flusso di eventi come normali eventi di strumenti. Poiché ogni worker sincronizza a intervalli, una modifica scritta in una sessione diventa visibile a un'altra sessione in esecuzione solo dopo che entrambe hanno sincronizzato, tipicamente ben meno di un minuto all'intervallo predefinito; le sessioni su sandbox cloud vedono le modifiche reciproche quasi immediatamente.

Ogni directory di store contiene un file marcatore chiamato .anthropic-memory-store che lega la directory al suo store. Lascialo al suo posto: il worker non sincronizza una directory il cui marcatore è mancante o alterato.

Prepara l'host

I memory store sulle sandbox self-hosted necessitano di un filesystem POSIX sull'host del worker (l'host Linux di Prima di iniziare); gli host Windows non sono supportati, perché il worker richiede O_NOFOLLOW quando apre i file di memoria. È consigliato un filesystem case-sensitive, in modo che i percorsi di memoria che differiscono solo per maiuscole e minuscole non collidano.

Prima di avviare il worker, crea la directory padre e rendila scrivibile dall'utente con cui viene eseguito il worker:

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

Non creare tu stesso le directory per store. Il worker crea la directory mount_path di ogni store (ad esempio, /mnt/memory/user-preferences) quando una sessione inizia, rifiuta di avviare il lavoro della sessione se esiste già qualcosa a quel percorso, e rimuove la directory quando la sessione termina. Ne derivano due regole operative:

• Esegui una sessione per filesystem quando le sessioni collegano lo stesso store. Due sessioni non possono montare lo stesso store su un unico host contemporaneamente, perché entrambe necessitano dello stesso percorso. Dare a ogni sessione la propria sandbox, come descritto in Esegui una sandbox per sessione, soddisfa questa regola.
• Arresta i worker in modo controllato. Quando arresti un worker mentre una sessione è in esecuzione, EnvironmentWorker carica i file di memoria modificati della sessione e rimuove le sue directory di store solo se viene annullato anziché terminato forzatamente: un processo terminato forzatamente non esegue alcun teardown, e il worker non installa da sé gestori di segnali. Collega SIGTERM e SIGINT all'annullamento nel processo che lo esegue: interrompi il signal che passi al worker in TypeScript, annulla il context in Go, e in Python annulla il task che esegue run() o handle_item(). Fallo da un gestore di segnali quando il tuo worker è il processo, come fanno i worker standalone in questa pagina, oppure dall'hook di arresto del tuo server quando il worker viene eseguito all'interno di un handler webhook, che non deve prendere il controllo dei segnali del server. Quindi arresta i worker con SIGTERM e concedi loro almeno 30 secondi per terminare prima di qualsiasi terminazione forzata, perché il caricamento finale può richiedere tutto quel tempo. Se un worker viene terminato forzatamente prima che il suo teardown venga eseguito, rimuovi la directory di store residua sotto /mnt/memory/ prima della sessione successiva che collega quello store; eventuali modifiche in essa che non erano state sincronizzate vanno perse.

Esegui una sandbox per sessione

Il pattern sandbox-per-sessione in Esegui un worker fornisce a ogni sessione un filesystem nuovo, che è ciò che Prepara l'host richiede quando le sessioni collegano lo stesso store. Mantieni ant beta:worker poll --on-work (o il work poller dell'SDK) come poller sull'host.

L'entrypoint ant beta:worker run mostrato lì non monta i memory store, quindi costruisci l'immagine per sessione attorno al worker dell'SDK: il suo entrypoint costruisce EnvironmentWorker e chiama handle_item() (handleItem in TypeScript, HandleItem in Go), che legge gli identificatori di sessione, work ed environment dalle variabili ANTHROPIC_* e il secret per sessione del work item da ANTHROPIC_WORK_SECRET. Puoi anche passare il secret esplicitamente come work_secret (workSecret in TypeScript, WorkSecret in Go).

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


async def main() -> None:
    async with AsyncAnthropic(auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]) as client:
        worker = EnvironmentWorker(client, workdir="/workspace")
        # Senza argomenti, handle_item() legge le variabili ANTHROPIC_* che lo script di spawn
        # ha inoltrato, inclusa ANTHROPIC_WORK_SECRET.
        task = asyncio.create_task(worker.handle_item())
        # Annullare il task quando il container viene arrestato consente al worker di caricare
        # i file di memoria modificati e rimuovere le directory dello store prima di uscire.
        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())

ant beta:worker poll --on-work non imposta ANTHROPIC_WORK_SECRET per lo script che avvia, quindi lo script di spawn legge il secret dal JSON del work item sul suo standard input e lo passa nella sandbox:

#!/bin/bash
# spawn.sh: chiamato una volta per ogni elemento di lavoro acquisito
# L'elemento di lavoro acquisito arriva come JSON su stdin. Il suo secret è la
# credenziale per sessione richiesta dagli endpoint del memory store.
ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
export ANTHROPIC_WORK_SECRET
mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
exec docker run --rm \
  -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
  -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
  -e ANTHROPIC_WORK_SECRET \
  -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
  your-sdk-worker-image

Se invece reclami il work con il work poller dell'SDK, passa il secret di ogni item reclamato nella sandbox che avvii allo stesso modo. Passalo solo nella sandbox che serve quella sessione e non registrarlo mai nei log.

L'immagine della sandbox necessita anche di un /mnt/memory scrivibile (vedi Prepara l'host). Poiché ogni sandbox serve una sola sessione e viene scartata in seguito, non ci sono directory residue da pulire e le directory di memoria non devono essere montate in bind sull'host: il worker carica il loro contenuto nello store prima che la sandbox termini. Se arresti un container prima che la sua sessione finisca, invia un segnale che l'entrypoint trasforma in cancellazione (vedi Prepara l'host) invece di ucciderlo, in modo che il caricamento venga comunque eseguito. Dai inoltre al container il tempo di completare il caricamento: Docker fa seguire al segnale di stop un SIGKILL dopo 10 secondi per impostazione predefinita, quindi aumenta quel limite ad almeno i 30 secondi richiesti da Prepara l'host, con --stop-timeout su docker run o con il periodo di grazia di terminazione del tuo orchestratore.

Configura la sincronizzazione

Due opzioni di EnvironmentWorker controllano il comportamento della memoria:

• memory_sync_interval (Python, in secondi; memorySyncIntervalMs in TypeScript, in millisecondi; MemorySyncInterval in Go, una durata): la frequenza con cui gli store collegati si riconciliano con il server mentre la sessione è in esecuzione. Il valore predefinito è 15 secondi; il minimo è 5 secondi. Un intervallo più breve riduce la finestra in cui un'altra sessione vede memorie obsolete, al costo di più richieste al memory store. None in Python, null in TypeScript o una durata negativa in Go disabilita completamente il supporto alla memoria: il worker non scarica né sincronizza gli store, e una sessione con memory store collegati viene eseguita senza di essi anche se il suo "system prompt" (prompt di sistema) li descrive ancora, quindi disabilita il supporto alla memoria solo sui worker le cui sessioni non collegano memory store. Mentre il supporto alla memoria è abilitato, un work item che arriva senza un secret per sessione per una sessione con store collegati fallisce invece di essere eseguito senza memoria (vedi Risolvi i problemi dei mount di memoria).
• memory_sync_deletions (memorySyncDeletions in TypeScript, MemorySyncDeletions in Go): se un file che l'agente elimina localmente viene eliminato anche dallo store. Il valore è uno tra "enabled" (il predefinito), "log_only" o "disabled" in Python e TypeScript, e una delle costanti environments.MemorySyncDeletionsEnabled (il valore zero), environments.MemorySyncDeletionsLogOnly o environments.MemorySyncDeletionsDisabled in Go. Quando abilitato, il worker elimina la memoria dallo store una volta che una sincronizzazione successiva conferma che il file è ancora assente; in modalità log-only esegue gli stessi controlli ma registra solo ciò che avrebbe eliminato, il che ti permette di osservare cosa eliminerebbero i tuoi worker prima di fidarti della modalità abilitata; quando disabilitato, non elimina mai dallo store. I caricamenti e gli scaricamenti non sono influenzati da questa impostazione.

Imposta queste opzioni dove costruisci il worker, sia tramite il costruttore EnvironmentWorker sia, in Python e TypeScript, tramite la factory client.beta.environments.work.worker() che usa il gestore del webhook.

Ad esempio, per sincronizzare ogni 10 secondi e registrare solo le eliminazioni che il worker avrebbe effettuato:

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

Store di sola lettura e conflitti

Per uno store collegato con access: "read_only", gli strumenti write ed edit si rifiutano di modificare i file all'interno della sua directory, e il worker non carica mai nulla da essa. Le modifiche effettuate tramite bash, o tramite uno strumento personalizzato o un server MCP che servi dalla sandbox, non vengono bloccate localmente: non vengono mai sincronizzate con lo store, e la successiva modifica remota a quella memoria le sovrascrive. Se hai bisogno che la copia locale stessa rimanga invariata durante la sessione, disabilita lo strumento bash per quell'agente e non fornirgli alcuno strumento personalizzato che scriva sul filesystem della sandbox; non montare il percorso dello store in sola lettura, perché il worker stesso deve creare la directory e scrivervi le memorie scaricate.

I conflitti si risolvono a favore dello store. Quando l'agente modifica un file di memoria che è cambiato anche nello store dall'ultima volta che la sessione lo ha sincronizzato, il worker mantiene la versione dello store alla sincronizzazione successiva, sovrascrive il file locale con essa e registra un avviso; gli strumenti write ed edit stessi hanno successo e nessun errore raggiunge l'agente. Se la modifica dell'agente è ancora applicabile, può rileggere il file dopo la sincronizzazione ed effettuare nuovamente la modifica.

Risolvi i problemi dei mount di memoria

Il worker registra nei log gli errori di mount e di sincronizzazione in background invece di segnalarli alla sessione; solo i rifiuti di sola lettura raggiungono l'agente, come errori degli strumenti (vedi Store di sola lettura e conflitti). Se un memory store non può essere montato quando il worker reclama una sessione, il worker fa fallire il work item: la sessione non emette alcun evento di errore e rimane inattiva.

Servi strumenti personalizzati dalla tua sandbox

Gli strumenti personalizzati sono strumenti eseguiti dal tuo codice: l'agente emette un evento agent.custom_tool_use e attende un user.custom_tool_result corrispondente. Il worker può essere quel codice e, poiché viene eseguito all'interno della tua sandbox, lo strumento raggiunge i servizi interni, le credenziali e l'uscita di rete che hai configurato per la sandbox, e nient'altro. La chiave dell'environment autorizza la pubblicazione dei risultati degli strumenti personalizzati, quindi la tua chiave API di Claude rimane fuori dall'host del worker.

1. 1

   Dichiara lo strumento sull'agente

   Aggiungi una voce custom ai tools dell'agente il cui name corrisponda allo strumento che il tuo worker registra. Vedi Strumenti personalizzati per la forma completa della dichiarazione.

   {
     "type": "custom",
     "name": "get_order_status",
     "description": "Look up an order in the internal fulfillment system by order ID.",
     "input_schema": {
       "type": "object",
       "properties": {
         "order_id": { "type": "string", "description": "The order ID" }
       },
       "required": ["order_id"]
     }
   }

   
2. 2

   Registra l'implementazione con il worker

   Passa lo strumento tramite la factory tools del worker (vedi Helper dell'SDK), insieme al toolset integrato:

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   import os
   from anthropic import AsyncAnthropic, beta_async_tool
   from anthropic.lib.environments import EnvironmentWorker
   from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
   
   
   @beta_async_tool
   async def get_order_status(order_id: str) -> str:
       """Look up an order in the internal fulfillment system by order ID."""
       # Viene eseguito sull'host del worker: chiama qualsiasi cosa raggiungibile dalla sandbox.
       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:
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
               tools=lambda env: [*beta_agent_toolset_20260401(env), get_order_status],
           ).run()
   
   
   asyncio.run(main())

Il worker risponde solo agli strumenti registrati con esso. Uno strumento personalizzato dichiarato sull'agente ma non registrato con alcun worker o client lascia la sessione in pausa con uno stop reason requires_action finché qualcosa non pubblica il suo risultato; vedi Gestione delle chiamate agli strumenti personalizzati per il flusso degli eventi.

Incapsula un server MCP come strumenti personalizzati

Il connettore MCP si connette ai server MCP dal lato di Anthropic, quindi un server deve esporre un endpoint HTTP che Anthropic possa raggiungere, direttamente o tramite un tunnel MCP. Per usare un server che solo la tua rete può raggiungere, rendi invece il worker il client MCP e dichiara gli strumenti del server come strumenti personalizzati. Il server MCP non necessita di connettività in ingresso dall'esterno della tua rete; Anthropic riceve le definizioni degli strumenti che dichiari sull'agente, l'input di ogni chiamata e il risultato che il tuo worker pubblica in risposta. A runtime il modello chiama uno strumento incapsulato come qualsiasi altro strumento personalizzato:

1. L'agente emette un evento agent.custom_tool_use.
2. Il worker, all'interno della tua sandbox, inoltra la chiamata tramite la sua sessione MCP aperta al server sulla tua rete.
3. Il worker pubblica la risposta del server come user.custom_tool_result.

Gli helper MCP lato client degli SDK convertono gli strumenti del server negli strumenti eseguibili che il worker accetta; installa un SDK MCP insieme all'SDK Anthropic (pip install "anthropic[mcp]" "mcp>=1.24", npm install @modelcontextprotocol/sdk, go get github.com/modelcontextprotocol/go-sdk). Gli esempi si connettono senza autenticazione; per inviare credenziali, configura il client HTTP o le opzioni di richiesta che passi al trasporto MCP (http_client in Python, requestInit in TypeScript, HTTPClient in Go).

1. 1

   Dichiara gli strumenti del server sull'agente

   Elenca gli strumenti del server MCP e dichiara ciascuno come strumento custom; i campi MCP name, description e inputSchema corrispondono uno a uno ai campi dello strumento personalizzato. Se il server impagina il suo elenco di strumenti, dichiara ogni pagina; il worker deve elencare le stesse pagine.

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   from typing import Any, cast
   from anthropic import AsyncAnthropic
   from anthropic.types.beta import BetaManagedAgentsCustomToolParams
   from mcp import ClientSession, types
   # Richiede mcp >= 1.24, che ha rinominato streamablehttp_client in streamable_http_client.
   from mcp.client.streamable_http import streamable_http_client
   
   MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
   
   
   def to_custom_tool(tool: types.Tool) -> BetaManagedAgentsCustomToolParams:
       # I campi MCP corrispondono uno a uno a una dichiarazione di strumento personalizzato. Il cast
       # passa il dizionario dello schema al parametro tipizzato dell'SDK senza modifiche.
       return {
           "type": "custom",
           "name": tool.name,
           "description": tool.description or tool.name,
           "input_schema": cast(Any, tool.inputSchema),
       }
   
   
   async def main() -> None:
       # Esegui questo codice dove crei gli agenti, non sull'host worker: si
       # autentica con la tua chiave API di Claude (ANTHROPIC_API_KEY).
       async with (
           streamable_http_client(MCP_SERVER_URL) as (read, write, _),
           ClientSession(read, write) as mcp_session,
           AsyncAnthropic() as client,
       ):
           await mcp_session.initialize()
           listed = await mcp_session.list_tools()
           agent = await client.beta.agents.create(
               name="Internal tools agent",
               model="claude-opus-5",
               tools=[
                   {"type": "agent_toolset_20260401"},
                   *[to_custom_tool(tool) for tool in listed.tools],
               ],
           )
           print(agent.id)
   
   
   asyncio.run(main())

2. 2

   Servi gli strumenti dal worker

   Connettiti allo stesso server MCP all'avvio, converti i suoi strumenti con gli helper MCP e registrali insieme al toolset integrato. Mantieni una sessione MCP aperta per tutta la vita del worker.

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   import os
   from datetime import timedelta
   from anthropic import AsyncAnthropic
   from anthropic.lib.environments import EnvironmentWorker
   from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
   from anthropic.lib.tools.mcp import async_mcp_tool
   from mcp import ClientSession
   # Richiede mcp >= 1.24, che ha rinominato streamablehttp_client in streamable_http_client.
   from mcp.client.streamable_http import streamable_http_client
   
   MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
   
   
   async def main() -> None:
       environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
       environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
       # Si connette al server MCP una sola volta all'avvio e mantiene la sessione aperta per
       # tutta la vita del worker. Il timeout trasforma una chiamata a uno strumento bloccata
       # in un risultato di errore anziché in una chiamata in stallo.
       async with (
           streamable_http_client(MCP_SERVER_URL) as (read, write, _),
           ClientSession(read, write, read_timeout_seconds=timedelta(seconds=60)) as mcp_session,
           AsyncAnthropic(auth_token=environment_key) as client,
       ):
           await mcp_session.initialize()
           listed = await mcp_session.list_tools()
           mcp_tools = [async_mcp_tool(tool, mcp_session) for tool in listed.tools]
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
               tools=lambda env: [*beta_agent_toolset_20260401(env), *mcp_tools],
           ).run()
   
   
   asyncio.run(main())

Tieni presente quanto segue quando incapsuli un server MCP:

• Gli strumenti vengono dichiarati, non scoperti a runtime. Il worker elenca gli strumenti del server MCP una volta all'avvio e non può aggiungere strumenti a una sessione in esecuzione. Quando gli strumenti del server cambiano, dichiarali di nuovo, sull'agente o su una sessione inattiva tramite Aggiornamento della configurazione dell'agente, e riavvia il worker.
• Nomi e descrizioni devono essere compatibili con la Managed Agents API. I nomi degli strumenti personalizzati sono univoci per agente e usano lettere, cifre, underscore e trattini (1–128 caratteri); è richiesta una descrizione non vuota; e l'array tools di un agente accetta al massimo 128 voci (ogni strumento incapsulato è una voce, e il toolset integrato è un'altra). L'API rifiuta una dichiarazione che riutilizza un nome di strumento, che dà a uno strumento personalizzato il nome di uno strumento integrato dell'agente come bash o read, o che usa il prefisso riservato mcp__. Gli helper MCP mantengono i nomi e le descrizioni del server, quindi rinomina o accorcia dove necessario. Quando due server espongono lo stesso nome di strumento, definisci tu stesso il wrapper con un nome prefissato e fai in modo che chiami il nome originale dello strumento del server.
• La maggior parte degli schemi passa invariata. L'API accetta le parole chiave JSON Schema che i server MCP emettono comunemente, come additionalProperties e title. Rifiuta le parole chiave di riferimento come $ref in qualsiasi punto dell'input_schema di uno strumento personalizzato, quindi incorpora inline gli schemi che generatori come pydantic fattorizzano in $defs. Rifiuta anche oneOf, anyOf e allOf al livello superiore, e nomi di proprietà al di fuori di lettere, cifre, underscore, punti e trattini (1–64 caratteri).
• Gli errori degli strumenti emergono come risultati di strumento con errore. Quando il server MCP segnala un errore di strumento, il worker pubblica un risultato di strumento con errore a cui il modello può reagire. Anche i contenuti MCP senza un equivalente nei risultati degli strumenti, come i blocchi audio e i link a risorse, emergono come errore. Imposta un timeout sul client MCP per un fallimento più rapido e chiaro, come fa l'esempio del worker Python con read_timeout_seconds. Senza di esso, una chiamata bloccata diventa un risultato di errore solo quando scatta il timeout di richiesta predefinito dell'SDK MCP TypeScript (circa un minuto) o quando scatta il meccanismo di sicurezza del worker stesso: circa due minuti e mezzo in Python, e due minuti in Go, dove il worker annulla una chiamata di strumento che supera il suo valore predefinito di 120 secondi e pubblica un risultato di errore.
• Incapsula server che gestisci o di cui ti fidi. Il nome, la descrizione e i risultati di uno strumento incapsulato entrano nel contesto del modello come quelli di qualsiasi altro strumento: input non attendibile che può influenzare ciò che l'agente fa con i suoi altri strumenti, incluso bash sull'host del worker. Dichiara solo gli strumenti che intendi far usare all'agente.
• Le policy di autorizzazione non si applicano agli strumenti personalizzati. Le policy di autorizzazione governano i toolset integrati e MCP; il worker esegue ogni chiamata a strumento incapsulato che il modello effettua, quindi inserisci qualsiasi passaggio di approvazione nel codice del tuo strumento.

Monitoraggio e operazioni

Queste chiamate vengono eseguite dai tuoi strumenti di monitoraggio o operativi, autenticate con la tua chiave API di Claude, per osservare e gestire la flotta di worker. Il ciclo di claim e keep-alive è gestito all'interno degli helper del worker, quindi non chiami direttamente quegli endpoint.

Leggi la profondità della coda

work.stats restituisce lo stato della coda per un environment:

• depth è il numero di item in attesa di essere reclamati. Scala la tua flotta di worker o genera avvisi sull'arretrato in base a questo valore.
• pending è il numero di item reclamati da un worker ma non ancora confermati. Gli helper del worker confermano ogni item prima di elaborarlo, quindi questo valore rimane vicino a zero nel funzionamento normale; un valore diverso da zero prolungato significa che un worker si è bloccato tra il claim e la conferma.
• oldest_queued_at è il timestamp dell'item più vecchio ancora in coda, in attesa di essere reclamato o reclamato ma non ancora confermato, oppure null quando non ce n'è nessuno.
• workers_polling è il numero di worker che hanno eseguito il polling negli ultimi 30 secondi. Usalo per gli avvisi di liveness.

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}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

Arresta una sessione in modo controllato

Usa work.stop per chiedere al worker che gestisce una sessione specifica di arrestarla. Per impostazione predefinita il work item passa a stopping: il worker se ne accorge al successivo heartbeat del lease, annulla la chiamata di strumento in corso della sessione e conferma l'arresto, momento in cui il work item diventa stopped. Passa force: true nel corpo della richiesta (con la CLI, passa --force) per contrassegnare immediatamente il work item come stopped invece di attendere la conferma del worker.

Poiché queste chiamate vengono eseguite dai tuoi strumenti operativi e non dall'host del worker, ANTHROPIC_WORK_ID non viene impostato automaticamente. Impostalo sull'ID del work item di destinazione prima di eseguire gli esempi seguenti. Per trovare l'ID di un work item, elenca i work item dell'environment tramite gli endpoint Environments Work.

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)

Prossimi passi