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 nell'infrastruttura che controlli, così il codice dell'agente, il filesystem e il traffico di rete in uscita 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 dopo. Consulta il modello di sicurezza per il confine completo del flusso di dati.



In cosa differisce dagli ambienti cloud

Il self-hosting è una buona scelta quando l'agente deve operare su dati che non possono lasciare il confine della tua rete, raggiungere servizi interni che non sono 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 combinare 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 che pubblici. Usa entrambi quando vuoi che l'esecuzione e l'accesso agli strumenti rimangano all'interno del tuo confine.



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. Il tuo worker rivendica 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 pubblica i risultati.

Gli elementi di lavoro vengono rivendicati tramite polling della coda dell'ambiente: o da un worker sempre attivo che esegue il polling continuamente, o da un handler attivato da webhook che si risveglia su session.status_run_started e inizia il polling.

La CLI e l'SDK includono entrambi worker pre-costruiti. La CLI ant supporta solo il pattern sempre attivo; l'SDK supporta sia il pattern sempre attivo che 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 del 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 del 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.
• /mnt/session/outputs: l'harness del worker istruisce Claude a scrivere qui i deliverable finali. In modalità sandbox, monta una directory dell'host in questo percorso per recuperare gli output dopo la fine della sessione. In modalità in-process, gli strumenti file del worker scrivono invece nella directory di lavoro, quindi questo percorso non si applica.



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 in 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.
• Due credenziali: una chiave di ambiente (generata nella Console nei passaggi che seguono) autentica il worker alla sua coda; la tua chiave API Claude crea sessioni e legge le statistiche della coda dall'esterno dell'host del worker. La generazione delle chiavi è disponibile solo nella Console.



Esegui un worker

Scegli sempre attivo per la configurazione più semplice: un processo a lunga esecuzione esegue il polling della coda continuamente 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à rivendicata.

• EnvironmentWorker: il worker pronto all'uso. Gestisce polling, configurazione ed esecuzione end to end.
  • .run(): viene eseguito indefinitamente, prendendo in carico le sessioni man mano che arrivano.
  • .handle_item(): gestisce un singolo elemento di lavoro rivendicato ed esce. 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.
• work.poller(): esegue il polling della coda di lavoro per tuo conto e ti fornisce ogni sessione rivendicata. Usalo quando vuoi decidere cosa succede per ogni sessione, ad esempio avviare una sandbox invece di eseguire gli strumenti in-process.
  • drain: se interrompere il polling una volta che la coda è vuota invece di attendere nuovo lavoro.
  • block_ms: quanto tempo attendere l'arrivo del 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: rivendica nuovamente gli elementi di lavoro che sono stati rivendicati ma mai confermati entro questo numero di millisecondi.
  • auto_stop: se pubblicare un segnale di stop per ogni elemento di lavoro una volta che il corpo del tuo loop ha finito con esso. Il poller Go non ha opzione di disattivazione e pubblica sempre il segnale di stop, quindi blocca nel corpo del loop fino al completamento della sessione invece di scollegarti.
• 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à rivendicato 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 rivendicata:

import asyncio
import os

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


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Sostituisci con il tuo launcher di sandbox per sessione. Passa
    # ANTHROPIC_ENVIRONMENT_KEY alla sandbox avviata, mai
    # la tua chiave API.
    print(f"claimed session {work.data.id}")


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())

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. beta_agent_toolset_20260401(env) prende 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 di 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 impostati sull'host del worker. Consulta Leggi la profondità della coda per la risposta completa delle statistiche e gli esempi in altri linguaggi.



Avvia una sessione

Una volta che il tuo worker è in esecuzione, crea una sessione che punta all'ambiente. Imposta AGENT_ID sull'ID agente che hai annotato in Prima di iniziare. La sessione entra nella coda di lavoro dell'ambiente e attende lì finché un worker non la rivendica; se nessun worker è connesso, la sessione rimane in coda invece di 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. Il tuo script di spawn o l'handler --on-work legge quei metadati dall'elemento di lavoro rivendicato (il poller della CLI invia il JSON dell'elemento di lavoro allo stdin dello script, e gli handler dell'SDK possono leggerlo tramite gli endpoint Environments Work) e prepara 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.



Monitoraggio e operazioni

Queste chiamate vengono eseguite dai tuoi strumenti di monitoraggio o operazioni, autenticate con la tua chiave API Claude, per osservare e gestire la flotta di worker. Il loop 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 ambiente:

• depth è il numero di elementi in attesa di essere rivendicati. Scala la tua flotta di worker o genera avvisi sul backlog in base a questo valore.
• pending è il numero di elementi che un worker ha rivendicato e sta attualmente elaborando.
• oldest_queued_at è il timestamp dell'elemento più vecchio ancora in coda o in elaborazione, 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 in modo pulito. Il worker completa qualsiasi chiamata agli strumenti in corso, pubblica uno stato finale e rilascia la sessione. Passa force: true nel corpo della richiesta (con la CLI, passa --force) per interrompere immediatamente invece di attendere il completamento della chiamata allo strumento corrente.

Poiché queste chiamate vengono eseguite dai tuoi strumenti operativi anziché dall'host del worker, ANTHROPIC_WORK_ID non viene impostato automaticamente. Impostalo sull'ID dell'elemento di lavoro di destinazione prima di eseguire gli esempi seguenti. Per trovare l'ID di un elemento di lavoro, elenca gli elementi di lavoro dell'ambiente 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