--- title: Distribuire worker self-hosted url: https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers description: "Scegli come i worker delle sandbox self-hosted acquisiscono il lavoro e dove vengono eseguite le sessioni: sempre attivi o attivati da webhook, in un unico processo o con una sandbox per sessione." featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- La [guida rapida](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes#quickstart) esegue un worker della CLI `ant` che effettua il polling in modo continuo ed esegue ogni sessione in un unico processo. Questa pagina illustra gli altri modi per eseguire un worker e come scegliere tra di essi. ## Scegli un modello di distribuzione Quando distribuisci i worker, devi fare due scelte: come il worker acquisisce il lavoro e dove viene eseguita ciascuna sessione. **Come il worker acquisisce il lavoro:** * **Sempre attivo:** un processo di lunga durata effettua il polling della coda in modo continuo e richiede solo HTTPS in uscita. Questa è la configurazione più semplice. * **Attivato da webhook:** un handler si attiva su `session.status_run_started` e avvia il polling. Questo evita un poller inattivo, ma richiede un endpoint [webhook](https://platform.claude.com/docs/it/managed-agents/webhooks) raggiungibile da Anthropic. **Dove viene eseguita ciascuna sessione:** * **Nel processo:** il worker che acquisisce una sessione esegue anche le sue chiamate agli strumenti, in un'unica directory di lavoro condivisa. * **Una sandbox per sessione:** un poller avvia una nuova sandbox per ogni sessione acquisita. Scegli questa opzione per un isolamento più forte: un filesystem nuovo, limiti sulle risorse o controlli di rete per sessione. I worker della CLI e dell'SDK supportano combinazioni diverse: | Funzionalità | CLI `ant` | SDK (Python, TypeScript, Go) | | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------- | | Polling sempre attivo | Sì | Sì | | Attivato da webhook | No | Sì | | Una sandbox per sessione | Sì | Sì | | [Memory store](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory) | Sì, con impostazioni di sincronizzazione predefinite | Sì, con sincronizzazione configurabile | | [Strumenti personalizzati](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-custom-tools) | No | Sì | Consulta il [Riferimento per i worker self-hosted](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference) per ogni flag della CLI e opzione dell'SDK. Per un maggiore controllo, chiama direttamente gli [endpoint Work degli Environments](https://platform.claude.com/docs/it/api/beta/environments/work) e implementa il tuo worker. ## Esegui un worker sempre attivo Avvia un worker che effettua il polling della coda in modo continuo. Si autentica con la [chiave dell'ambiente](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes#run-your-first-session) della guida rapida: ```bash CLI ant beta:worker poll --workdir /workspace ``` ```python Python import asyncio import contextlib import os import signal from anthropic import AsyncAnthropic from anthropic.lib.environments import EnvironmentWorker 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: worker = EnvironmentWorker( client, environment_id=environment_id, environment_key=environment_key, workdir="/workspace", ) task = asyncio.create_task(worker.run()) # Annullare il task, anziché terminare il processo, consente al worker di fermare il suo # elemento di lavoro in corso e caricare i file di memoria modificati 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()) ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments"; const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!; const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!; const client = new Anthropic({ authToken: environmentKey }); const controller = new AbortController(); // L'interruzione su uno dei due segnali consente al worker di caricare i file di memoria modificati e rimuovere le // directory dello store prima che il processo termini. process.once("SIGINT", () => controller.abort()); process.once("SIGTERM", () => controller.abort()); await new EnvironmentWorker({ client, environmentId, environmentKey, workdir: "/workspace", signal: controller.signal }).run(); ``` L'SDK C# non dispone di `EnvironmentWorker`. Esegui invece il worker della CLI `ant`: `ant beta:worker poll --workdir /workspace`. ```go Go package main import ( "context" "log" "os" "os/signal" "syscall" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/lib/environments" "github.com/anthropics/anthropic-sdk-go/option" ) func main() { environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY") environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID") ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() client := anthropic.NewClient(option.WithAuthToken(environmentKey)) worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, Workdir: "/workspace", }) if err := worker.Run(ctx); err != nil { log.Fatalf("worker: %v", err) } } ``` L'SDK Java non dispone di `EnvironmentWorker`. Esegui invece il worker della CLI `ant`: `ant beta:worker poll --workdir /workspace`. L'SDK PHP non dispone di `EnvironmentWorker`. Esegui invece il worker della CLI `ant`: `ant beta:worker poll --workdir /workspace`. L'SDK Ruby non dispone di `EnvironmentWorker`. Esegui invece il worker della CLI `ant`: `ant beta:worker poll --workdir /workspace`. ## Attiva i worker tramite webhook Nella [Console](https://platform.claude.com/settings/workspaces/default/webhooks), definisci un endpoint webhook che ascolti gli eventi `session.status_run_started`. Consulta [Webhook](https://platform.claude.com/docs/it/managed-agents/webhooks) per i dettagli. Insieme all'ID e alla chiave dell'ambiente della [guida rapida](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes#run-your-first-session), esporta la chiave di firma del webhook sull'host del tuo handler. L'handler la usa per verificare i payload in arrivo. ```bash export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..." ``` Invoca il worker quando viene attivato `session.status_run_started`. L'handler svuota la coda e passa ogni elemento di lavoro acquisito a `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`), che scarica le skill, esegue le chiamate agli strumenti, invia i risultati e termina. Per verificare le firme dei webhook, installa l'extra webhooks: `pip install "anthropic[webhooks]"`. ```python Python import asyncio import os import anthropic import standardwebhooks # installed by the anthropic[webhooks] extra environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"] environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"] client = anthropic.AsyncAnthropic( auth_token=environment_key, ) # Annullato da shutdown() affinché un elemento di lavoro in corso possa caricare i file di memoria modificati e # rimuovere le proprie directory di store prima che il processo termini. inflight: set[asyncio.Task[None]] = set() # Attendi questo dall'hook di arresto dell'host, ad es. uno shutdown del lifespan ASGI (il codice dopo # `yield` in un lifespan FastAPI), che uvicorn esegue su SIGTERM. uvicorn lascia terminare le richieste aperte # prima che l'hook venga eseguito, quindi imposta --timeout-graceful-shutdown per limitare l'attesa. async def shutdown() -> None: for task in inflight: task.cancel() await asyncio.gather(*inflight, return_exceptions=True) async def handle(raw: bytes, headers: dict[str, str]) -> tuple[dict[str, str], int]: try: event = client.beta.webhooks.unwrap(raw.decode(), headers=headers) except standardwebhooks.WebhookVerificationError: return {"error": "signature verification failed"}, 401 if event.data.type != "session.status_run_started": return {"status": "ignored"}, 200 task = asyncio.create_task(run_queued_work()) inflight.add(task) task.add_done_callback(inflight.discard) try: # Protetto (shield): una consegna persa o scaduta non deve annullare l'elemento; shutdown() lo fa. await asyncio.shield(task) except asyncio.CancelledError: return {"status": "shutting down"}, 503 return {"status": "ok"}, 200 async def run_queued_work() -> None: async for work in client.beta.environments.work.poller( environment_id=environment_id, environment_key=environment_key, block_ms=None, reclaim_older_than_ms=2000, drain=True, auto_stop=False, ): await client.beta.environments.work.worker(workdir="/workspace").handle_item( work_id=work.id, environment_id=environment_id, session_id=work.data.id, environment_key=environment_key, # Il segreto per sessione è ciò che consente al worker di montare gli store di memoria della sessione. work_secret=work.secret, ) ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!; const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!; const client = new Anthropic({ authToken: environmentKey }); // Chiama shutdown.abort() dall'handler SIGTERM/SIGINT dell'host, insieme alla chiusura del server, // poi attendi le chiamate handle() in corso prima di uscire: l'abort consente a un elemento di lavoro in esecuzione // di caricare i file di memoria modificati e rimuovere prima le directory dei suoi store. export const shutdown = new AbortController(); export async function handle(req: Request): Promise { // Non confermare mai una consegna il cui lavoro non verrà eseguito qui; un 503 fa ritentare il mittente. if (shutdown.signal.aborted) { return Response.json({ status: "shutting down" }, { status: 503 }); } const body = await req.text(); let event; try { event = client.beta.webhooks.unwrap(body, { headers: Object.fromEntries(req.headers) }); } catch { return new Response("signature verification failed", { status: 401 }); } if (event.data.type !== "session.status_run_started") { return Response.json({ status: "ignored" }); } for await (const work of client.beta.environments.work.poller({ environmentId, environmentKey, blockMs: null, reclaimOlderThanMs: 2000, drain: true, autoStop: false, signal: shutdown.signal })) { await client.beta.environments.work.worker({ workdir: "/workspace" }).handleItem({ workId: work.id, environmentId, sessionId: work.data.id, environmentKey, // Il segreto per sessione è ciò che consente al worker di montare gli store di memoria della sessione. workSecret: work.secret ?? undefined, signal: shutdown.signal }); } // Il poller e handleItem ritornano silenziosamente all'abort, quindi un drain interrotto finisce qui. if (shutdown.signal.aborted) { return Response.json({ status: "shutting down" }, { status: 503 }); } return Response.json({ status: "ok" }); } ``` L'SDK C# non dispone di `EnvironmentWorker`. Per gestire gli elementi di lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work). ```go Go package main import ( "context" "encoding/json" "errors" "io" "log/slog" "net/http" "os" "os/signal" "syscall" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/lib/environments" "github.com/anthropics/anthropic-sdk-go/option" "github.com/anthropics/anthropic-sdk-go/packages/param" ) var ( environmentKey = os.Getenv("ANTHROPIC_ENVIRONMENT_KEY") environmentID = os.Getenv("ANTHROPIC_ENVIRONMENT_ID") client = anthropic.NewClient( option.WithAuthToken(environmentKey), option.WithWebhookKey(os.Getenv("ANTHROPIC_WEBHOOK_SIGNING_KEY")), ) worker = environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ Workdir: "/workspace", }) // Annullato su SIGINT o SIGTERM (impostato in main) così che un work item in corso possa // caricare i file di memoria modificati e rimuovere le directory degli store prima dell'uscita. shutdown context.Context ) func handle(w http.ResponseWriter, r *http.Request) { body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "bad request", http.StatusBadRequest) return } event, err := client.Beta.Webhooks.Unwrap(body, r.Header) if err != nil { http.Error(w, "signature verification failed", http.StatusUnauthorized) return } if event.Data.Type != "session.status_run_started" { json.NewEncoder(w).Encode(map[string]string{"status": "ignored"}) return } // L'SDK Go non fornisce una funzione di comodo RunOne: svuota gli elementi in sospeso // con WorkPoller ed esegui ciascuno con HandleItem. // Scollega da r.Context(): la sessione può sopravvivere al timeout di consegna del webhook. // Il contesto di arresto a livello di processo termina comunque l'elemento in modo pulito su SIGTERM. ctx := shutdown poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, BlockMs: param.Null[int64](), ReclaimOlderThanMs: param.NewOpt[int64](2000), Drain: true, AutoStop: param.NewOpt(false), }) defer poller.Close() for poller.Next() { item := poller.Current() if err := worker.HandleItem(ctx, environments.HandleItemOptions{ WorkID: item.ID, EnvironmentID: item.EnvironmentID, SessionID: item.Data.ID, EnvironmentKey: environmentKey, // Il segreto per sessione è ciò che consente al worker di montare gli store di memoria della sessione. WorkSecret: item.Secret, }); err != nil { slog.Error("handle work item", "work_id", item.ID, "err", err) http.Error(w, "internal error", http.StatusInternalServerError) return } } if err := poller.Err(); err != nil { slog.Error("poll work queue", "err", err) http.Error(w, "internal error", http.StatusInternalServerError) return } json.NewEncoder(w).Encode(map[string]string{"status": "ok"}) } func main() { ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() shutdown = ctx server := &http.Server{Addr: ":8080"} http.HandleFunc("POST /webhook", handle) go func() { if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) { slog.Error("http server", "err", err) os.Exit(1) } }() // Su un segnale, smetti di accettare consegne e ritorna solo dopo che gli handler in corso, // e quindi il teardown della memoria dei loro work item, sono terminati. <-ctx.Done() if err := server.Shutdown(context.Background()); err != nil { slog.Error("http shutdown", "err", err) } } ``` L'SDK Java non dispone di `EnvironmentWorker`. Per gestire gli elementi di lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work). L'SDK PHP non dispone di `EnvironmentWorker`. Per gestire gli elementi di lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work). L'SDK Ruby non dispone di `EnvironmentWorker`. Per gestire gli elementi di lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work). Poiché l'handler acquisisce il lavoro autonomamente, deve [inoltrare il segreto dell'elemento di lavoro](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret), come fa qui l'argomento `work_secret` (typescript: `workSecret`; go: `WorkSecret`). Questo handler esegue ogni elemento acquisito in un unico processo su un unico host. Se le tue sessioni collegano lo stesso memory store, consulta [Isolare le sessioni che condividono uno store](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#isolate-sessions-that-share-a-store). ## Esegui una sandbox per sessione 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. Installa `ant` e imposta `ant beta:worker run` come 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`; `curl` viene usato solo in fase di build. ```dockerfile FROM your-base-image ARG ANT_VERSION=1.44.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"] ``` Lo script inoltra i dettagli della sessione in una nuova sandbox. Richiede `jq` sull'host del poller. ```bash #!/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-image ``` Il poller imposta le variabili `ANTHROPIC_*` che lo script inoltra, tranne il segreto. Consulta [Variabili d'ambiente](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#environment-variables). `/host/outputs` è una directory dell'host a tua scelta. Montarla su `/workspace` ti consente di recuperare i risultati della sessione dopo che la sandbox è terminata. Il mount include anche l'albero `skills/` scaricato e gli eventuali file intermedi. ```bash ant beta:worker poll --on-work ./spawn.sh ``` ### Inoltra il segreto dell'elemento di lavoro Ogni elemento di lavoro acquisito può contenere un `secret` (csharp, go: `Secret`) per sessione, emesso da Anthropic. Il worker che esegue la sessione ne ha bisogno per montare i [memory store](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory). Un worker che acquisisce ed esegue le sessioni in un unico processo (`ant beta:worker poll` senza `--on-work`, oppure `EnvironmentWorker` con `run()` (go: `Run()`)) trasmette il segreto autonomamente. Quando il tuo codice si trova tra l'acquisizione e il worker, sei tu a inoltrarlo: | 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()` (go: `environments.NewWorkPoller()`) dell'SDK | Il campo `secret` (go: `Secret`) di ogni elemento di lavoro acquisito | `ANTHROPIC_WORK_SECRET` nell'ambiente della sandbox, oppure l'argomento `work_secret` (typescript: `workSecret`; go: `WorkSecret`) di `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | Passa il segreto solo alla sandbox che serve quella sessione e non registrarlo mai nei log. Consulta [Modello di sicurezza](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-security) per capire come si relaziona 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 `work.poller()` (go: `environments.NewWorkPoller()`). Effettua il polling della coda e ti fornisce ogni sessione acquisita, mentre tu avvii la sandbox: Acquisire il lavoro in un ciclo e avviare una sandbox per ogni sessione richiede più logica di un singolo comando shell. Dalla shell, esegui `ant beta:worker poll --on-work` con uno script di avvio, come in [Esegui una sandbox per sessione](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-session). Per acquisire il lavoro dalla shell e avviare una sandbox per ogni sessione, esegui `ant beta:worker poll --on-work` con uno script di avvio, come in [Esegui una sandbox per sessione](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-session). ```python Python 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 del work item: 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()) ``` ```typescript TypeScript import { spawn } from "node:child_process"; import { once } from "node:events"; import Anthropic from "@anthropic-ai/sdk"; import { WorkPoller } from "@anthropic-ai/sdk/helpers/beta/environments"; import type { BetaSelfHostedWork } from "@anthropic-ai/sdk/resources/beta/environments"; const 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 ]; const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!; const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!; const client = new Anthropic({ authToken: environmentKey }); async function launchContainer(work: BetaSelfHostedWork): Promise { console.log(`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 del work item: il worker // interno ha bisogno del segreto per montare i memory store della sessione. const env = { ...process.env, ANTHROPIC_WORK_ID: work.id, ANTHROPIC_SESSION_ID: work.data.id, ANTHROPIC_WORK_SECRET: work.secret ?? "" }; const forward = SANDBOX_ENV.flatMap((name) => ["-e", name]); const launcher = spawn("docker", ["run", "--rm", "--detach", ...forward, "your-image"], { env, stdio: "inherit" }); await once(launcher, "close"); } const poller = new WorkPoller({ client, environmentId, environmentKey, autoStop: false // the launched sandbox owns the stop call }); for await (const work of poller) { await launchContainer(work); } ``` L'SDK C# non dispone di un helper che effettua il polling del lavoro. Per acquisire il lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work). ```go Go package main import ( "context" "fmt" "log" "os" "os/exec" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/lib/environments" "github.com/anthropics/anthropic-sdk-go/option" "github.com/anthropics/anthropic-sdk-go/packages/param" ) var sandboxEnv = []string{ "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 } func launchContainer(ctx context.Context, work *anthropic.BetaSelfHostedWork) error { fmt.Printf("claimed session %s\n", 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 del work item: il worker // interno ha bisogno del segreto per montare i memory store della sessione. args := []string{"run", "--rm", "--detach"} for _, name := range sandboxEnv { args = append(args, "-e", name) } launcher := exec.CommandContext(ctx, "docker", append(args, "your-image")...) launcher.Env = append(os.Environ(), "ANTHROPIC_WORK_ID="+work.ID, "ANTHROPIC_SESSION_ID="+work.Data.ID, "ANTHROPIC_WORK_SECRET="+work.Secret, ) launcher.Stdout, launcher.Stderr = os.Stdout, os.Stderr return launcher.Run() } func main() { environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID") environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY") client := anthropic.NewClient(option.WithAuthToken(environmentKey)) ctx := context.Background() poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, AutoStop: param.NewOpt(false), // the launched sandbox owns the stop call }) defer poller.Close() for work, err := range poller.All() { if err != nil { log.Fatal(err) } if err := launchContainer(ctx, work); err != nil { log.Fatal(err) } } } ``` L'SDK Java non dispone di un helper che effettua il polling del lavoro. Per acquisire il lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work). L'SDK PHP non dispone di un helper che effettua il polling del lavoro. Per acquisire il lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work). L'SDK Ruby non dispone di un helper che effettua il polling del lavoro. Per acquisire il lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work). ### 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](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-custom-tools) o usare [impostazioni di sincronizzazione della memoria non predefinite](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#configure-sync). L'entrypoint costruisce `EnvironmentWorker` e chiama `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`), che legge le stesse variabili `ANTHROPIC_*` inoltrate dallo script di avvio. ```python Python 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 spawn # ha inoltrato, inclusa 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()) ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments"; const client = new Anthropic({ authToken: process.env.ANTHROPIC_ENVIRONMENT_KEY }); const controller = new AbortController(); // Interrompere quando il container viene arrestato consente al worker di caricare i file di memoria // modificati e rimuovere le directory dello store prima di uscire. process.once("SIGTERM", () => controller.abort()); process.once("SIGINT", () => controller.abort()); // Senza argomenti, handleItem() legge le variabili ANTHROPIC_* che lo script di spawn // ha inoltrato, inclusa ANTHROPIC_WORK_SECRET. await new EnvironmentWorker({ client, workdir: "/workspace", signal: controller.signal }).handleItem(); ``` L'SDK C# non dispone di `EnvironmentWorker`. ```go Go package main import ( "context" "log" "os" "os/signal" "syscall" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/lib/environments" "github.com/anthropics/anthropic-sdk-go/option" ) func main() { // Annullare il contesto quando il container viene arrestato consente al worker di caricare // i file di memoria modificati e rimuovere le directory dello store prima di uscire. ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() client := anthropic.NewClient(option.WithAuthToken(os.Getenv("ANTHROPIC_ENVIRONMENT_KEY"))) worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ Workdir: "/workspace", }) // Con opzioni a valore zero, HandleItem legge le variabili ANTHROPIC_* che lo script di spawn // ha inoltrato, inclusa ANTHROPIC_WORK_SECRET. if err := worker.HandleItem(ctx, environments.HandleItemOptions{}); err != nil { log.Fatalf("worker: %v", err) } } ``` L'SDK Java non dispone di `EnvironmentWorker`. L'SDK PHP non dispone di `EnvironmentWorker`. L'SDK Ruby non dispone di `EnvironmentWorker`. ## Prepara i file per una sessione Anthropic non monta file o repository GitHub nelle sandbox self-hosted. Per rendere disponibili i file specifici di una sessione: 1. Passa i riferimenti ai file, come un percorso S3 o lo SHA di un commit, nel campo `metadata` della sessione. 2. Nel tuo script di avvio o nell'handler `--on-work`, recupera la sessione (`GET /v1/sessions/{session_id}`) e leggi `metadata`. L'elemento di lavoro acquisito contiene l'ID della sessione ma non i metadati. 3. Prepara i file nella directory di lavoro prima che inizi l'esecuzione degli strumenti. ```bash cURL curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "agent": "'"$AGENT_ID"'", "environment_id": "'"$ANTHROPIC_ENVIRONMENT_ID"'", "metadata": {"input_file": "s3://my-bucket/data.csv"} }' ``` ```bash CLI ant beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ANTHROPIC_ENVIRONMENT_ID" \ --metadata '{"input_file": "s3://my-bucket/data.csv"}' ``` ```python Python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, metadata={"input_file": "s3://my-bucket/data.csv"}, ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: agent.id, environment_id: environment.id, metadata: { input_file: "s3://my-bucket/data.csv" } }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = agent.ID, EnvironmentID = environment.ID, Metadata = new Dictionary { ["input_file"] = "s3://my-bucket/data.csv" }, }); ``` ```go Go session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}, EnvironmentID: environment.ID, Metadata: map[string]string{ "input_file": "s3://my-bucket/data.csv", }, }) if err != nil { panic(err) } ``` ```java Java var session = client.beta().sessions().create(SessionCreateParams.builder() .agent(agent.id()) .environmentId(environment.id()) .metadata(SessionCreateParams.Metadata.builder() .putAdditionalProperty("input_file", JsonValue.from("s3://my-bucket/data.csv")) .build()) .build()); ``` ```php PHP $session = $client->beta->sessions->create( agent: $agent->id, environmentID: $environment->id, metadata: ['input_file' => 's3://my-bucket/data.csv'], ); ``` ```ruby Ruby 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 sessioni e worker in modo pulito e risolvi i problemi più comuni. Modello di responsabilità condivisa per gli ambienti sandbox self-hosted.