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 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 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 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ò utilizzare 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.

Environment worker

Un environment worker è un processo che esegui sulla tua infrastruttura. Riceve richieste di esecuzione di strumenti da Anthropic e le esegue localmente. L'ambiente self_hosted funziona come una coda di lavoro: quando una sessione viene assegnata ad esso, Anthropic accoda la sessione come elemento di lavoro. 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 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. Su Claude Platform on AWS, l'endpoint di elenco GET /v1/environments/{id}/work e il suo equivalente SDK non sono attualmente disponibili; gli altri endpoint di lavoro (poll, ack, heartbeat, stop, post results, per-item get e stats) funzionano normalmente.

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 host in questo percorso per recuperare gli output dopo la fine della sessione. In modalità in-process, gli strumenti file del worker scrivono invece sotto la 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 in quel percorso esatto. L'SDK TypeScript richiede inoltre unzip, tar e Node.js 22 o successivo; l'SDK Python usa la libreria standard per l'estrazione degli archivi e non ha requisiti binari aggiuntivi. Queste dipendenze vengono risolte in percorsi fissi e non rispettano gli override di PATH.
• La CLI ant o un SDK Anthropic (Python, TypeScript o Go) sull'host del worker.
• Due credenziali: una environment key (generata nei passaggi seguenti) 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.

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 hai bisogno di 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, prelevando le sessioni man mano che arrivano. Termina in modo pulito su SIGTERM.
  • .handle_item(): preleva una sessione in attesa, la gestisce e termina.
• work.poller(): interroga la coda di lavoro per tuo conto e ti fornisce ogni sessione reclamata. Usalo quando vuoi decidere cosa succede per ogni sessione, ad esempio avviando 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 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; omettendo il parametro viene usato il long-poll predefinito di 999 ms.
  • reclaim_older_than_ms: reclama nuovamente gli elementi di lavoro assegnati a un worker che ha smesso di rispondere.
  • auto_stop: se inviare un segnale di stop sull'elemento di lavoro dopo che l'iteratore termina. Il poller Go non ha opt-out e invia sempre il segnale di stop, quindi blocca nel corpo del loop finché la sessione non è completata invece di 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à 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


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 opzionalmente scarica le skill della sessione quando usato come context manager. 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 downloaded to /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

Verifica che il worker sia connesso

Da una shell separata, usando la tua chiave API Claude (non la environment key), 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 altri esempi in altri linguaggi.

Avvia una sessione

Una volta che il tuo worker è in esecuzione, crea una sessione che punta all'ambiente. La sessione entra nella coda di lavoro dell'ambiente e attende lì finché un worker non la reclama; 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 un SHA di commit) nel campo metadata della sessione. Il tuo script di spawn o handler --on-work legge quei metadati dall'elemento di lavoro reclamato (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 Self-hosted worker nel riferimento per l'elenco completo dei flag della CLI, e Helper SDK per le opzioni degli helper 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 reclamo 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 reclamati. 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 reclamato e sta attualmente elaborando.
• oldest_queued_at è il timestamp dell'elemento più vecchio nella coda, o null se la coda è vuota.
• 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
}

Arresta una sessione in modo pulito

Usa work.stop per chiedere al worker che gestisce una sessione specifica di arrestarla in modo pulito. Il worker completa qualsiasi chiamata a strumento in corso, invia uno stato finale e rilascia la sessione. Passa force: true nel corpo della richiesta per interrompere immediatamente invece di attendere il completamento della chiamata a strumento corrente.

Poiché queste chiamate vengono eseguite dai tuoi strumenti operativi invece che dall'host del worker, ANTHROPIC_WORK_ID non è impostato automaticamente. Impostalo sull'ID dell'elemento di lavoro di destinazione prima di eseguire gli esempi seguenti.

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