---
title: Eseguire una sandbox per sessione
url: https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-per-session
description: Assegna a ogni sessione la propria sandbox self-hosted con il chart Helm su Kubernetes, uno script di avvio o il poller dell'SDK.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: Non idoneo per ZDR, ad eccezione di Managed Agents self-hosted. Le sessioni sono risorse con stato; le trascrizioni restano finché non le elimini.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
---

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](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern).

Puoi configurarlo in tre modi:

* **[Chart Helm su Kubernetes](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes):** il dispatcher di Anthropic acquisisce il lavoro e avvia un pod per ogni sessione sul tuo cluster.
* **[Script di avvio](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script):** la CLI `ant` acquisisce il lavoro e chiama il tuo script, che avvia una sandbox su qualsiasi piattaforma.
* **[Poller dell’SDK](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-from-the-sdk-poller):** il tuo codice acquisisce il lavoro e avvia la sandbox.

Le sezioni successive a [Esegui le sandbox su Kubernetes](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-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](https://gvisor.dev/) 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.idleTimeout` del chart), il suo pod si arresta. Il suo volume `/workspace` rimane 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.warmPoolSize` del chart).

I pod delle sandbox eseguono il worker della CLI `ant`. Supportano i [memory store](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory) con le impostazioni di sincronizzazione predefinite e non supportano gli [strumenti personalizzati](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-custom-tools).

### 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](https://github.com/kubernetes-sigs/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](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes#run-your-first-session) e il certificato TLS del dispatcher.

La [guida all’installazione su GitHub](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md) 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:

<File filename="cma-values.yaml">
  ```yaml
  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 address
  ```
</File>

La 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:

```bash
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 \
  --wait
```

Dopo l’installazione, esegui il controllo preliminare descritto nella guida all’installazione.

<Warning>
  Non rimuovere il chart solo con `helm uninstall`. Quel comando elimina le network policy e lascia le sandbox delle sessioni in esecuzione senza di esse. Arresta prima il dispatcher ed elimina le sandbox, nell’ordine indicato dalla [sezione Removal della guida all’installazione](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#removal).
</Warning>

### 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](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#install) 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](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#network-egress) della guida all’installazione contiene i dettagli.

* **GKE con Dataplane V2:** imposta `egress.mode: fqdnGke` per limitare le connessioni alla porta 443 sugli host in `egress.fqdnGke.hosts`. Mantieni `api.anthropic.com` in 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](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#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.

<Steps>
  <Step title="Crea l’immagine della sandbox">
    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`; la build usa `curl` solo per scaricare `ant`.

    <File filename="Dockerfile">
      ```dockerfile
      FROM 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"]
      ```
    </File>
  </Step>

  <Step title="Scrivi lo script di avvio">
    Lo script inoltra i dettagli della sessione a una sandbox nuova. Richiede `jq` sull’host del poller.

    <File filename="spawn.sh">
      ```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
      ```
    </File>

    Il poller imposta `ANTHROPIC_WORK_ID`, `ANTHROPIC_ENVIRONMENT_ID`, `ANTHROPIC_SESSION_ID` e `ANTHROPIC_ENVIRONMENT_KEY`. `ANTHROPIC_BASE_URL` raggiunge lo script solo se lo imposti sull’host del poller. Lo script legge `ANTHROPIC_WORK_SECRET` dal JSON dell’elemento di lavoro sullo standard input. 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. Montandola in `/workspace` puoi recuperare i risultati della sessione dopo che la sandbox è terminata. Il mount raccoglie anche l’albero `skills/` scaricato e gli eventuali file intermedi.
  </Step>

  <Step title="Avvia il poller">
    ```bash
    ant beta:worker poll --on-work ./spawn.sh
    ```
  </Step>
</Steps>

## Inoltra il segreto dell’elemento di lavoro

Ogni elemento di lavoro acquisito può contenere un `secret` (csharp, go: `Secret`) che Anthropic emette per quella sessione. 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 passa il segreto da solo. `EnvironmentWorker` con `run()` (go: `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()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`) dell’SDK Python, TypeScript o Go | 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 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()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`). Interroga la coda e ti fornisce ogni sessione acquisita, mentre tu avvii la sandbox:

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    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 [Avvia le sandbox con uno script di avvio](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script).
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    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. Consulta [Avvia le sandbox con uno script di avvio](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script).
  </CodeGroupItem>

  ```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 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())
  ```

  ```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<void> {
    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 dell'elemento di lavoro: 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);
  }
  ```

  <CodeGroupItem language="C#">
    L’SDK C# non dispone di un helper che interroga la coda di lavoro. Per acquisire il lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work) per interrogare la coda alla ricerca di un elemento e confermarlo.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"fmt"
  	"log"
  	"os"
  	"os/exec"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  	"github.com/anthropics/anthropic-sdk-go/v2/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 dell'elemento di lavoro: 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)
  		}
  	}
  }
  ```

  <CodeGroupItem language="Java">
    L’SDK Java non dispone di un helper che interroga la coda di lavoro. Per acquisire il lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work) per interrogare la coda alla ricerca di un elemento e confermarlo.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    L’SDK PHP non dispone di un helper che interroga la coda di lavoro. Per acquisire il lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work) per interrogare la coda alla ricerca di un elemento e confermarlo.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    L’SDK Ruby non dispone di un helper che interroga la coda di lavoro. Per acquisire il lavoro dal tuo codice, chiama gli [endpoint Environments Work](https://platform.claude.com/docs/it/api/beta/environments/work) per interrogare la coda alla ricerca di un elemento e confermarlo.
  </CodeGroupItem>
</CodeGroup>

## 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.

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Un worker è un “long-running process” (processo di lunga durata), non una singola richiesta HTTP. Per servire strumenti personalizzati o modificare le impostazioni di sincronizzazione della memoria, usa `EnvironmentWorker` nell’SDK Python, TypeScript o Go.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Il worker della CLI `ant` (`ant beta:worker run`) non può servire strumenti personalizzati né modificare le impostazioni di sincronizzazione della memoria. Per fare l’una o l’altra cosa, usa `EnvironmentWorker` nell’SDK Python, TypeScript o Go.
  </CodeGroupItem>

  ```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 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())
  ```

  ```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();
  // L'interruzione all'arresto del container 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_* inoltrate dallo script
  // di avvio, inclusa ANTHROPIC_WORK_SECRET.
  await new EnvironmentWorker({
    client,
    workdir: "/workspace",
    signal: controller.signal
  }).handleItem();
  ```

  <CodeGroupItem language="C#">
    L’SDK C# non dispone di `EnvironmentWorker`.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"log"
  	"os"
  	"os/signal"
  	"syscall"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/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 avvio
  	// ha inoltrato, incluso ANTHROPIC_WORK_SECRET.
  	if err := worker.HandleItem(ctx, environments.HandleItemOptions{}); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    L’SDK Java non dispone di `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    L’SDK PHP non dispone di `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    L’SDK Ruby non dispone di `EnvironmentWorker`.
  </CodeGroupItem>
</CodeGroup>

## 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:

1. Passa i riferimenti ai file, come un percorso S3 o lo SHA di un commit, nel campo `metadata` (csharp, go: `Metadata`) della sessione.
2. Nel tuo script di avvio o nel gestore `--on-work`, recupera la sessione (`GET /v1/sessions/{session_id}`) e leggi `metadata` (csharp, go: `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 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](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation#set-up-federation). Quindi, scambia il token di identità del tuo workload con un token di accesso, come mostrato in [Autenticati dal tuo workload](https://platform.claude.com/docs/it/manage-claude/workload-identity-federation#authenticate-from-your-workload). Imposta `ANTHROPIC_AUTH_TOKEN` solo nella shell in cui esegui l’esempio cURL, perché ha la precedenza sulle tue impostazioni di federazione. [Autenticazione](https://platform.claude.com/docs/it/manage-claude/authentication) elenca le altre credenziali accettate dall’API, come la chiave API della guida rapida.

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "environment_id": "env_01595EKxaaTTGwwY3kyXdtbs",
      "metadata": {"input_file": "s3://my-bucket/data.csv"}
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent agent_011CYm1BLqPXpQRk5khsSXrs \
    --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
    --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<string, string> { ["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"}
  )
  ```
</CodeGroup>

## Passaggi successivi

<CardGroup cols={2}>
  <Card title="Monitorare e risolvere i problemi dei worker self-hosted" icon="lightning" href="https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-operations">
    Leggi la profondità della coda, arresta correttamente sessioni e worker e risolvi gli errori più comuni.
  </Card>
</CardGroup>
