Eseguire una sandbox per sessione
Assegna a ogni sessione la propria sandbox self-hosted con il chart Helm su Kubernetes, uno script di avvio o il poller dell’SDK.
Nel modello sandbox per sessione, ogni sessione viene eseguita in una sandbox nuova, che può avere il proprio filesystem, i propri limiti di risorse e i propri controlli di rete. Per confrontarlo con gli altri modelli, consulta Scegli un modello di distribuzione.
Puoi configurarlo in tre modi:
- Chart Helm su Kubernetes: il dispatcher di Anthropic acquisisce il lavoro e avvia un pod per ogni sessione sul tuo cluster.
- Script di avvio: la CLI
antacquisisce il lavoro e chiama il tuo script, che avvia una sandbox su qualsiasi piattaforma. - Poller dell’SDK: il tuo codice acquisisce il lavoro e avvia la sandbox.
Le sezioni successive a Esegui le sandbox su Kubernetes si applicano allo script di avvio e al poller dell’SDK.
Esegui le sandbox su Kubernetes
Anthropic pubblica un chart Helm, cma-sandboxes, e le relative immagini. Il chart esegue una sandbox per sessione sul tuo cluster Kubernetes. Il suo dispatcher interroga la coda di lavoro dell’ambiente e assegna a ogni sessione un pod dedicato:
- Isolamento: ogni pod viene eseguito sotto gVisor dietro le network policy del chart. Ha il proprio filesystem e i propri limiti di risorse. Solo il dispatcher detiene la chiave dell’ambiente.
- Affinità di sessione: ogni messaggio di una sessione va alla sandbox di quella sessione. Dopo che la sessione è rimasta inattiva per 30 minuti (il valore predefinito dell’impostazione
sandbox.idleTimeoutdel chart), il suo pod si arresta. Il suo volume/workspacerimane fino al termine della sessione. Il messaggio successivo avvia un pod sullo stesso volume. - Warm pool: tranne che su Google Kubernetes Engine (GKE), il chart mantiene due pod pronti per le nuove sessioni (il valore predefinito dell’impostazione
sandbox.warmPoolSizedel chart).
I pod delle sandbox eseguono il worker della CLI ant. Supportano i memory store con le impostazioni di sincronizzazione predefinite e non supportano gli strumenti personalizzati.
Installa il chart
Il chart funziona su GKE, Amazon EKS e altri cluster. Prima di installarlo, configura quanto segue:
- Nel cluster: il controller Agent Sandbox (su GKE, il componente aggiuntivo Agent Sandbox), nodi che eseguono gVisor e un plugin di rete che applica le NetworkPolicy.
- Nel tuo namespace: le etichette del Pod Security Standard Restricted, un Secret con l’ID dell’ambiente e la chiave dell’ambiente e il certificato TLS del dispatcher.
La guida all’installazione su GitHub contiene i passaggi di configurazione per ogni tipo di cluster. Tratta anche gli aggiornamenti e la rotazione delle chiavi.
Salva le tue impostazioni come cma-values.yaml. L’installazione non riesce senza le tre impostazioni presenti in questo file:
platform: gke # or eks, or generic for any other cluster
egress:
# The chart already blocks the private ranges. List your other addresses
# that sandboxes must not reach.
clusterCIDRs:
- 203.0.113.10/32 # your cluster's Kubernetes API endpoint
cmaServer:
public: true # the Claude API has a public addressLa guida all’installazione elenca le impostazioni che dipendono dal tuo cluster, come gke.dns su GKE Autopilot. Indica anche quando egress.clusterIsPrivate: true sostituisce egress.clusterCIDRs.
Quindi, installa il chart:
helm install cma \
oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
--version 0.1.0 \
--namespace cma \
-f cma-values.yaml \
--waitDopo l’installazione, esegui il controllo preliminare descritto nella guida all’installazione.
Aggiungi strumenti all’immagine della sandbox
L’immagine della sandbox pubblicata è Alpine Linux con bash, curl, jq e la CLI ant. Il chart la esegue con un filesystem radice di sola lettura e come utente non root, quindi un agente non può installare pacchetti durante una sessione.
Per fornire ai tuoi agenti più strumenti, come Python o Git, crea entrambe le immagini dal repository al tag della release. La sezione Install della guida all’installazione contiene i comandi. Carica le immagini nel tuo registry come cma-dispatcher e cma-sandbox, usando la versione del chart come tag. Quindi, imposta image.registry su quel registry. Se fissi i digest delle immagini, usa i digest delle tue immagini.
Limita l’egress di rete
Per impostazione predefinita, le network policy del chart consentono a una sandbox di raggiungere l’internet IPv4 pubblico. Bloccano gli intervalli di indirizzi privati, il server dei metadati del cloud e gli indirizzi in egress.clusterCIDRs. Un agente soggetto a prompt injection può inviare ciò che legge a qualsiasi indirizzo raggiungibile dalla sua sandbox. La sezione Network egress della guida all’installazione contiene i dettagli.
- GKE con Dataplane V2: imposta
egress.mode: fqdnGkeper limitare le connessioni alla porta 443 sugli host inegress.fqdnGke.hosts. Mantieniapi.anthropic.comin quell’elenco e aggiungi ogni host di cui hanno bisogno i comandi dei tuoi agenti. A differenza dell’impostazione predefinita, questa modalità non ha un elenco di intervalli bloccati. Consente qualsiasi indirizzo a cui si risolve il nome di un host elencato, quindi elenca solo gli host il cui DNS ritieni affidabile. Una sandbox può comunque inviare dati all’esterno all’interno delle query DNS. - Altri cluster e GKE senza Dataplane V2: l’impostazione predefinita è l’unica modalità.
- Ogni cluster: le network policy non coprono le porte su cui sono in ascolto i nodi stessi del cluster. Consulta Node isolation you own nella guida all’installazione.
Avvia le sandbox con uno script di avvio
Un poller sull’host acquisisce il lavoro e chiama il tuo script una volta per ogni elemento di lavoro. Lo script avvia una sandbox per quella singola sessione.
Crea l’immagine della sandbox
Installa
ante impostaant beta:worker runcome entrypoint. Quando una sandbox si avvia, legge i dettagli della sessione dalle variabili d’ambiente, gestisce quella sessione e termina. L’immagine di base deve fornire/bin/bash; la build usacurlsolo per scaricareant.DockerfileFROM your-base-image ARG ANT_VERSION=2.11.0 ARG TARGETARCH RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \ curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \ | tar -xz -C /usr/local/bin ant WORKDIR /workspace VOLUME /workspace ENTRYPOINT ["ant", "beta:worker", "run"]Scrivi lo script di avvio
Lo script inoltra i dettagli della sessione a una sandbox nuova. Richiede
jqsull’host del poller.spawn.sh#!/bin/bash # spawn.sh: chiamato una volta per ogni elemento di lavoro acquisito # L'elemento di lavoro acquisito arriva come JSON su stdin. 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-imageIl poller imposta
ANTHROPIC_WORK_ID,ANTHROPIC_ENVIRONMENT_ID,ANTHROPIC_SESSION_IDeANTHROPIC_ENVIRONMENT_KEY.ANTHROPIC_BASE_URLraggiunge lo script solo se lo imposti sull’host del poller. Lo script leggeANTHROPIC_WORK_SECRETdal JSON dell’elemento di lavoro sullo standard input. Consulta Variabili d’ambiente./host/outputsè una directory dell’host a tua scelta. Montandola in/workspacepuoi recuperare i risultati della sessione dopo che la sandbox è terminata. Il mount raccoglie anche l’alberoskills/scaricato e gli eventuali file intermedi.Avvia il poller
ant beta:worker poll --on-work ./spawn.sh
Inoltra il segreto dell’elemento di lavoro
Ogni elemento di lavoro acquisito può contenere un secret che Anthropic emette per quella sessione. Il worker che esegue la sessione ne ha bisogno per montare i memory store.
Un worker che acquisisce ed esegue le sessioni in un unico processo passa il segreto da solo. EnvironmentWorker con run() è uno di questi worker, e ant beta:worker poll senza --on-work è un altro. Quando il tuo codice si trova tra l’acquisizione e il worker, sei tu a inoltrare il segreto:
| Acquisisci il lavoro con | Il segreto arriva come | Passalo al worker come |
|---|---|---|
ant beta:worker poll --on-work | Il campo secret del JSON dell’elemento di lavoro sullo standard input del tuo script | ANTHROPIC_WORK_SECRET nell’ambiente della sandbox |
work.poller() dell’SDK Python, TypeScript o Go | Il campo secret di ogni elemento di lavoro acquisito | ANTHROPIC_WORK_SECRET nell’ambiente della sandbox oppure l’argomento work_secret di handle_item() |
Passa il segreto solo alla sandbox che serve quella sessione e non registrarlo mai nei log. Consulta Modello di sicurezza per scoprire come si rapporta alla chiave dell’ambiente.
Avvia le sandbox dal poller dell’SDK
Per acquisire il lavoro dal tuo codice invece che con ant beta:worker poll --on-work, usa il poller dell’SDK Python, TypeScript o Go: work.poller(). Interroga la coda e ti fornisce ogni sessione acquisita, mentre tu avvii la sandbox:
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 dell'elemento di lavoro: il worker
# all'interno ha bisogno del segreto per montare i memory store 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-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())Esegui il worker dell’SDK all’interno della sandbox
Sostituisci l’entrypoint ant beta:worker run con un entrypoint dell’SDK quando la sandbox deve servire strumenti personalizzati o usare impostazioni di sincronizzazione della memoria non predefinite. L’entrypoint costruisce EnvironmentWorker e chiama handle_item(), che legge le stesse variabili ANTHROPIC_* inoltrate dallo script di avvio.
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 avvio
# ha inoltrato, incluso 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())Prepara i file per una sessione
Anthropic non monta file o repository GitHub nelle sandbox self-hosted. Per rendere disponibili i file specifici della sessione:
- Passa i riferimenti ai file, come un percorso S3 o lo SHA di un commit, nel campo
metadatadella sessione. - Nel tuo script di avvio o nel gestore
--on-work, recupera la sessione (GET /v1/sessions/{session_id}) e leggimetadata. L’elemento di lavoro acquisito contiene l’ID della sessione ma non i metadati. - Prepara i file nella directory di lavoro prima che venga eseguito qualsiasi strumento.
L’esempio cURL legge un “access token” (token di accesso) da ANTHROPIC_AUTH_TOKEN. Per ottenerne uno, configura Workload Identity Federation con lo scope predefinito workspace:developer, come descritto in Configura la federazione. Quindi, scambia il token di identità del tuo workload con un token di accesso, come mostrato in Autenticati dal tuo workload. Imposta ANTHROPIC_AUTH_TOKEN solo nella shell in cui esegui l’esempio cURL, perché ha la precedenza sulle tue impostazioni di federazione. Autenticazione elenca le altre credenziali accettate dall’API, come la chiave API della guida rapida.
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
metadata={"input_file": "s3://my-bucket/data.csv"},
)Passaggi successivi
Leggi la profondità della coda, arresta correttamente sessioni e worker e risolvi gli errori più comuni.
Questa pagina ti è stata utile?