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, 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 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 piano di controllo 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 funzionare 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 tunnellizzati che 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 worker dell'ambiente è un processo che esegui sulla tua infrastruttura. Riceve richieste di esecuzione di 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 interrogando la coda dell'ambiente: tramite un worker sempre attivo che esegue il polling continuamente, oppure 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 predefiniti. 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.
• 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.



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 di 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 la 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(): 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 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 anziché 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 di 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 punti 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 uno 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 avvio o handler --on-work recupera la sessione (GET /v1/sessions/{session_id}) per leggere il campo metadata, poi 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.



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 corrispondente user.custom_tool_result. 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 la pubblicazione dei risultati degli strumenti personalizzati, quindi la tua chiave API di 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 alcun worker o client lascia la sessione in pausa con un motivo di arresto requires_action finché qualcosa non pubblica il suo risultato; consulta Gestione delle chiamate a strumenti personalizzati per il flusso degli eventi.



Incapsulare 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 raggiungibile solo dalla tua rete, 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. 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).

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 di Managed Agents. I nomi degli strumenti personalizzati sono univoci per agente e usano lettere, cifre, trattini bassi e trattini (1–128 caratteri); una descrizione è obbligatoria (1–4.096 caratteri); 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 assegna 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 fagli 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 rendi inline gli schemi che generatori come pydantic fattorizzano in $defs. Rifiuta anche oneOf, anyOf e allOf di primo livello, e nomi di proprietà al di fuori di lettere, cifre, trattini bassi, punti e trattini (1–64 caratteri).
• I fallimenti degli strumenti emergono come risultati di errore degli strumenti. Quando il server MCP segnala un errore di strumento, il worker pubblica un risultato di errore dello strumento a cui il modello può reagire. Il contenuto MCP senza un equivalente di risultato di strumento, come blocchi audio e link a risorse, emerge anch'esso 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 interviene 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 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 effettuata dal modello, 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 di 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 imposta 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 prolungato 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 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
}



Arrestare una sessione in modo controllato

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