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 sul lato di Anthropic ma spostano l'esecuzione degli strumenti nell'infrastruttura che controlli, in modo che il codice dell'agente, il filesystem e il traffico di rete in uscita non lascino mai il tuo ambiente.

L'esecuzione degli strumenti rimane sul tuo host: il filesystem che l'agente legge e scrive, i processi che genera 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.



Differenze rispetto agli ambienti cloud

Il self-hosting è una buona scelta quando l'agente deve operare su dati che non possono lasciare il perimetro 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ò utilizzare server MCP sia tunnelizzati che pubblici. Usa entrambi quando vuoi che l'esecuzione e l'accesso agli strumenti rimangano all'interno del tuo perimetro. 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.



Environment worker

Un environment worker è 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, genera 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 rivendicati interrogando la coda dell'ambiente: tramite un worker sempre attivo che interroga continuamente, oppure un handler attivato da webhook che si risveglia su session.status_run_started e inizia a interrogare.

Sia la CLI che l'SDK forniscono worker precostruiti. La CLI ant supporta solo il pattern sempre attivo; l'SDK supporta sia quello sempre attivo che quello attivato da webhook. Entrambi sono configurabili: consulta Self-hosted worker nel riferimento per i flag della CLI, e Helper 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.
• Output: negli ambienti self-hosted il prompt di sistema della sessione omette l'istruzione /mnt/session/outputs utilizzata nelle sandbox gestite da Anthropic, quindi i deliverable finali vengono salvati ovunque l'agente li scriva nel filesystem della tua sandbox, tipicamente sotto la directory di lavoro.



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 in quel percorso esatto. 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 utilizzano 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 verso la 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 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 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 dall'inizio alla fine.
  • .run(): viene eseguito indefinitamente, prelevando le sessioni man mano che arrivano.
  • .handle_item(): gestisce un singolo elemento di lavoro rivendicato 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 genera.
• work.poller(): interroga la 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 anziché eseguire gli strumenti in-process.
  • drain: se interrompere il polling una volta che la coda è vuota anziché attendere nuovo lavoro.
  • block_ms: quanto tempo attendere l'arrivo di lavoro prima di restituire, in millisecondi. Deve essere compreso tra 1 e 999 (attesa per singolo poll; l'helper ripete automaticamente il polling). Passa null (None in Python, param.Null[int64]() in Go) per un controllo non bloccante; omettere il parametro utilizza 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 inviare un segnale di stop per ogni elemento di lavoro una volta che il corpo del tuo loop ha finito di elaborarlo. Il poller Go non ha opt-out e invia sempre il segnale di stop, quindi blocca nel corpo del loop fino al completamento della sessione anziché distaccarti.
• client.beta.sessions.events.tool_runner(): esegue le chiamate agli strumenti per una singola sessione, dato 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 creando 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 nella 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) 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 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 impostate sull'host del worker. Consulta Leggi la profondità della coda per la risposta completa delle statistiche e altri 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 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 un SHA di commit) nel campo metadata della sessione. L'elemento di lavoro rivendicato non trasporta i metadata della sessione, ma trasporta l'ID della sessione: il tuo script di spawn o handler --on-work recupera la sessione (GET /v1/sessions/{session_id}) per leggere il campo metadata, quindi 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 Self-hosted worker nel riferimento per l'elenco completo dei flag della CLI, e Helper SDK per le opzioni degli helper SDK.



Servi strumenti personalizzati dalla tua sandbox

Gli strumenti personalizzati sono strumenti che il tuo codice esegue: 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 il traffico di rete in uscita che hai configurato per la sandbox, e nient'altro. La chiave di ambiente autorizza l'invio dei risultati degli strumenti personalizzati, quindi la tua chiave API Claude rimane fuori dall'host del worker.

Il worker risponde solo agli strumenti registrati con esso. Uno strumento personalizzato dichiarato sull'agente ma non registrato con nessun worker o client lascia la sessione in pausa con uno stop reason requires_action finché qualcosa non invia il suo risultato; consulta 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 attraverso un tunnel MCP. Per utilizzare 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 entrata 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 invia. 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 attraverso la sua sessione MCP aperta al server sulla tua rete.
3. Il worker invia 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).

Tieni presente quanto segue quando incapsuli un server MCP:

• Gli strumenti sono 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 rispettare l'API Managed Agents. I nomi degli strumenti personalizzati sono univoci per agente e utilizzano 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, nomina uno strumento personalizzato come uno strumento agente integrato quale bash o read, o utilizza 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 fallo chiamare 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 ovunque nell'input_schema di uno strumento personalizzato, quindi incorpora inline gli schemi che generatori come pydantic fattorizzano in $defs. Rifiuta anche oneOf, anyOf e allOf a livello superiore, e nomi di proprietà al di fuori di lettere, cifre, underscore, punti e trattini (1–64 caratteri).
• I fallimenti degli strumenti emergono come risultati di errore. Quando il server MCP segnala un errore dello strumento, il worker invia un risultato di errore a cui il modello può reagire. Anche il contenuto MCP senza equivalente di risultato strumento, come blocchi audio e link a risorse, emerge 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 lo fa il backstop del worker stesso: circa due minuti e mezzo in Python, e due minuti in Go, dove il worker annulla una chiamata a strumento che supera il suo valore predefinito di 120 secondi e invia 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 gli altri suoi strumenti, incluso bash sull'host del worker. Dichiara solo gli strumenti che intendi far utilizzare 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 tuo codice dello strumento.



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 rivendicazione 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 rivendicati da un worker ma non ancora confermati. Gli helper del worker confermano ogni elemento prima di elaborarlo, quindi questo valore rimane vicino a zero in condizioni normali; un valore diverso da zero sostenuto significa che un worker si è bloccato tra la rivendicazione e la conferma.
• oldest_queued_at è il timestamp dell'elemento più vecchio ancora in coda, in attesa di essere rivendicato o rivendicato ma non ancora confermato, oppure null quando non ce n'è nessuno.
• workers_polling è il numero di worker che hanno interrogato 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
}



Arrestare 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 allo stato stopping: il worker se ne accorge al successivo heartbeat del lease, annulla la chiamata allo strumento in corso della sessione e conferma l'arresto, a quel punto 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 anziché 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'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)



Passaggi successivi