---
title: Exécuter une sandbox par session
url: https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-per-session
description: Donnez à chaque session sa propre sandbox auto-hébergée avec le chart Helm sur Kubernetes, un script de lancement ou le poller du 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 éligible à la ZDR, sauf pour Managed Agents auto-hébergé. Les sessions sont des ressources avec état ; les transcriptions persistent jusqu’à ce que vous les supprimiez.
  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
---

Dans le modèle d’une sandbox par session, chaque session s’exécute dans une nouvelle sandbox, qui peut avoir son propre système de fichiers, ses propres limites de ressources et ses propres contrôles réseau. Pour le comparer aux autres modèles, consultez [Choisir un modèle de déploiement](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern).

Vous pouvez le mettre en place de trois façons :

* **[Chart Helm sur Kubernetes](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes) :** le « dispatcher » (répartiteur) d’Anthropic réclame le travail et démarre un pod pour chaque session sur votre cluster.
* **[Script de lancement](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script) :** la CLI `ant` réclame le travail et appelle votre script, qui lance une sandbox sur n’importe quelle plateforme.
* **[Poller du SDK](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-from-the-sdk-poller) :** votre propre code réclame le travail et lance la sandbox.

Les sections qui suivent [Exécuter des sandboxes sur Kubernetes](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes) s’appliquent au script de lancement et au poller du SDK.

## Exécuter des sandboxes sur Kubernetes

Anthropic publie un chart Helm, `cma-sandboxes`, ainsi que ses images. Le chart exécute une sandbox par session sur votre propre cluster Kubernetes. Son dispatcher interroge la file de travail de l’environnement et attribue à chaque session son propre pod :

* **Isolation :** chaque pod s’exécute sous [gVisor](https://gvisor.dev/) derrière les politiques réseau du chart. Il dispose de son propre système de fichiers et de ses propres limites de ressources. Seul le dispatcher détient la clé d’environnement.
* **Affinité de session :** chaque message d’une session est envoyé à la sandbox de cette session. Lorsque la session est inactive depuis 30 minutes (la valeur par défaut du paramètre `sandbox.idleTimeout` du chart), son pod s’arrête. Son volume `/workspace` est conservé jusqu’à la fin de la session. Le message suivant démarre un pod sur le même volume.
* **Pool préchauffé :** sauf sur Google Kubernetes Engine (GKE), le chart maintient deux pods prêts pour les nouvelles sessions (la valeur par défaut du paramètre `sandbox.warmPoolSize` du chart).

Les pods de sandbox exécutent le worker de la CLI `ant`. Ils prennent en charge les [magasins de mémoire](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory) avec les paramètres de synchronisation par défaut, et ne prennent pas en charge les [outils personnalisés](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-custom-tools).

### Installer le chart

Le chart fonctionne sur GKE, Amazon EKS et d’autres clusters. Mettez en place les éléments suivants avant de l’installer :

* **Dans le cluster :** le contrôleur [Agent Sandbox](https://github.com/kubernetes-sigs/agent-sandbox) (sur GKE, le module complémentaire Agent Sandbox), des nœuds qui exécutent gVisor et un plugin réseau qui applique les NetworkPolicy.
* **Dans votre propre namespace :** les labels du Pod Security Standard Restricted, un Secret contenant l’ID d’environnement et la [clé d’environnement](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes#run-your-first-session), ainsi que le certificat TLS du dispatcher.

Le [guide d’installation sur GitHub](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md) contient les étapes de configuration pour chaque type de cluster. Il couvre également les mises à niveau et la rotation des clés.

Enregistrez vos paramètres dans `cma-values.yaml`. L’installation échoue sans les trois paramètres de ce fichier :

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

Le guide d’installation répertorie les paramètres qui dépendent de votre cluster, comme `gke.dns` sur GKE Autopilot. Il indique également quand `egress.clusterIsPrivate: true` remplace `egress.clusterCIDRs`.

Ensuite, installez le 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
```

Après l’installation, exécutez la vérification préalable décrite dans le guide d’installation.

<Warning>
  Ne supprimez pas le chart avec `helm uninstall` seul. Cette commande supprime les politiques réseau et laisse les sandboxes des sessions s’exécuter sans elles. Arrêtez d’abord le dispatcher et supprimez les sandboxes, dans l’ordre indiqué dans la [section Removal du guide d’installation](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#removal).
</Warning>

### Ajouter des outils à l’image de sandbox

L’image de sandbox publiée est une Alpine Linux avec `bash`, `curl`, `jq` et la CLI `ant`. Le chart l’exécute avec un système de fichiers racine en lecture seule et en tant qu’utilisateur non root, de sorte qu’un agent ne peut pas installer de paquets pendant une session.

Pour donner davantage d’outils à vos agents, comme Python ou Git, construisez les deux images à partir du dépôt au tag de la version. La [section Install du guide d’installation](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#install) contient les commandes. Poussez les images vers votre registre sous les noms `cma-dispatcher` et `cma-sandbox`, avec la version du chart comme tag. Ensuite, définissez `image.registry` sur ce registre. Si vous épinglez des digests d’images, utilisez les digests de vos propres images.

### Restreindre le trafic réseau sortant

Par défaut, les politiques réseau du chart permettent à une sandbox d’atteindre l’internet IPv4 public. Elles bloquent les plages d’adresses privées, le serveur de métadonnées du cloud et les adresses de `egress.clusterCIDRs`. Un agent victime d’une « prompt injection » (injection de prompt) peut envoyer ce qu’il lit à n’importe quelle adresse que sa sandbox peut atteindre. La section [Network egress](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#network-egress) du guide d’installation fournit les détails.

* **GKE avec Dataplane V2 :** définissez `egress.mode: fqdnGke` pour limiter les connexions au port 443 des hôtes de `egress.fqdnGke.hosts`. Conservez `api.anthropic.com` dans cette liste et ajoutez chaque hôte dont les commandes de vos agents ont besoin. Contrairement au mode par défaut, ce mode n’a pas de liste de plages bloquées. Il autorise toute adresse vers laquelle le nom d’un hôte listé est résolu, donc ne listez que des hôtes dont vous jugez le DNS fiable. Une sandbox peut toujours exfiltrer des données dans des requêtes DNS.
* **Autres clusters et GKE sans Dataplane V2 :** le mode par défaut est le seul mode.
* **Tous les clusters :** les politiques réseau ne couvrent pas les ports sur lesquels écoutent les propres nœuds du cluster. Consultez [Node isolation you own](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#node-isolation-you-own) dans le guide d’installation.

## Lancer des sandboxes avec un script de lancement

Un poller sur l’hôte réclame le travail et appelle votre script une fois pour chaque élément de travail. Le script lance une sandbox pour cette session unique.

<Steps>
  <Step title="Construire l’image de sandbox">
    Installez `ant` et définissez `ant beta:worker run` comme point d’entrée. Lorsqu’une sandbox démarre, elle lit les détails de la session à partir des variables d’environnement, traite cette session, puis se termine. L’image de base doit fournir `/bin/bash` ; la construction utilise `curl` uniquement pour télécharger `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="Écrire le script de lancement">
    Le script transmet les détails de la session à une nouvelle sandbox. Il nécessite `jq` sur l’hôte du poller.

    <File filename="spawn.sh">
      ```bash
      #!/bin/bash
      # spawn.sh : appelé une fois pour chaque élément de travail réclamé.
      # L'élément de travail réclamé arrive au format JSON sur 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>

    Le poller définit `ANTHROPIC_WORK_ID`, `ANTHROPIC_ENVIRONMENT_ID`, `ANTHROPIC_SESSION_ID` et `ANTHROPIC_ENVIRONMENT_KEY`. `ANTHROPIC_BASE_URL` n’atteint le script que si vous la définissez sur l’hôte du poller. Le script lit `ANTHROPIC_WORK_SECRET` à partir du JSON de l’élément de travail sur l’entrée standard. Consultez [Variables d’environnement](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-reference#environment-variables).

    `/host/outputs` est un répertoire de l’hôte que vous choisissez. Le monter sur `/workspace` vous permet de récupérer les livrables de la session après la fin de la sandbox. Le montage récupère également l’arborescence `skills/` téléchargée et tous les fichiers intermédiaires.
  </Step>

  <Step title="Démarrer le poller">
    ```bash
    ant beta:worker poll --on-work ./spawn.sh
    ```
  </Step>
</Steps>

## Transmettre le secret de l’élément de travail

Chaque élément de travail réclamé peut porter un `secret` (csharp, go: `Secret`) qu’Anthropic émet pour cette session. Le worker qui exécute la session en a besoin pour monter les [magasins de mémoire](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory).

Un worker qui réclame et exécute des sessions dans un même processus transmet lui-même le secret. `EnvironmentWorker` avec `run()` (go: `Run()`) est l’un de ces workers, et `ant beta:worker poll` sans `--on-work` en est un autre. Lorsque votre propre code se situe entre la réclamation et le worker, c’est vous qui transmettez le secret :

| Vous réclamez le travail avec                                                                                        | Le secret arrive sous la forme                                                          | Transmettez-le au worker sous la forme                                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ant beta:worker poll --on-work`                                                                                     | Le champ `secret` du JSON de l’élément de travail sur l’entrée standard de votre script | `ANTHROPIC_WORK_SECRET` dans l’environnement de la sandbox                                                                                                                                              |
| `work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`) du SDK Python, TypeScript ou Go | Le champ `secret` (go: `Secret`) de chaque élément de travail réclamé                   | `ANTHROPIC_WORK_SECRET` dans l’environnement de la sandbox ou l’argument `work_secret` (typescript: `workSecret`; go: `WorkSecret`) de `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) |

Transmettez le secret uniquement à la sandbox qui sert cette session, et ne le journalisez jamais. Consultez [Modèle de sécurité](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-security) pour savoir comment il se rapporte à la clé d’environnement.

## Lancer des sandboxes depuis le poller du SDK

Pour réclamer le travail depuis votre propre code plutôt qu’avec `ant beta:worker poll --on-work`, utilisez le poller du SDK Python, TypeScript ou Go : `work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`). Il interroge la file et vous remet chaque session réclamée, et c’est vous qui lancez la sandbox :

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Réclamer du travail en boucle et lancer une sandbox pour chaque session nécessite plus de logique qu’une simple commande shell. Depuis le shell, exécutez `ant beta:worker poll --on-work` avec un script de lancement, comme dans [Lancer des sandboxes avec un script de lancement](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script).
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Pour réclamer du travail depuis le shell et lancer une sandbox pour chaque session, exécutez `ant beta:worker poll --on-work` avec un script de lancement. Consultez [Lancer des sandboxes avec un script de lancement](https://platform.claude.com/docs/fr/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}")
      # Remplacez `docker run` par votre propre lanceur de sandbox. Transmettez la clé d'environnement
      # (jamais votre clé API) et le secret par session de l'élément de travail : le worker
      # à l'intérieur a besoin du secret pour monter les magasins de mémoire de la session.
      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}`);
    // Remplacez `docker run` par votre propre lanceur de sandbox. Transmettez la clé
    // d'environnement (jamais votre clé API) et le secret par session de l'élément de travail : le worker
    // à l'intérieur a besoin du secret pour monter les magasins de mémoire de la session.
    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#">
    Le SDK C# ne dispose pas d’un utilitaire qui interroge la file de travail. Pour réclamer du travail depuis votre propre code, appelez les [points de terminaison de travail d’environnement](https://platform.claude.com/docs/fr/api/beta/environments/work) pour interroger la file à la recherche d’un élément et l’acquitter.
  </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)
  	// Remplacez `docker run` par votre propre lanceur de sandbox. Transmettez la clé
  	// d'environnement (jamais votre clé API) et le secret par session de l'élément de travail : le worker
  	// à l'intérieur a besoin du secret pour monter les magasins de mémoire de la session.
  	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">
    Le SDK Java ne dispose pas d’un utilitaire qui interroge la file de travail. Pour réclamer du travail depuis votre propre code, appelez les [points de terminaison de travail d’environnement](https://platform.claude.com/docs/fr/api/beta/environments/work) pour interroger la file à la recherche d’un élément et l’acquitter.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    Le SDK PHP ne dispose pas d’un utilitaire qui interroge la file de travail. Pour réclamer du travail depuis votre propre code, appelez les [points de terminaison de travail d’environnement](https://platform.claude.com/docs/fr/api/beta/environments/work) pour interroger la file à la recherche d’un élément et l’acquitter.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Le SDK Ruby ne dispose pas d’un utilitaire qui interroge la file de travail. Pour réclamer du travail depuis votre propre code, appelez les [points de terminaison de travail d’environnement](https://platform.claude.com/docs/fr/api/beta/environments/work) pour interroger la file à la recherche d’un élément et l’acquitter.
  </CodeGroupItem>
</CodeGroup>

## Exécuter le worker du SDK dans la sandbox

Remplacez le point d’entrée `ant beta:worker run` par un point d’entrée du SDK lorsque la sandbox doit [servir des outils personnalisés](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-custom-tools) ou utiliser des [paramètres de synchronisation de la mémoire autres que ceux par défaut](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#configure-sync). Le point d’entrée construit `EnvironmentWorker` et appelle `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`), qui lit les mêmes variables `ANTHROPIC_*` que celles transmises par le script de lancement.

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Un worker est un processus de longue durée, pas une simple requête HTTP. Pour servir des outils personnalisés ou modifier les paramètres de synchronisation de la mémoire, utilisez `EnvironmentWorker` dans le SDK Python, TypeScript ou Go.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Le worker de la CLI `ant` (`ant beta:worker run`) ne peut pas servir d’outils personnalisés ni modifier les paramètres de synchronisation de la mémoire. Pour l’un ou l’autre, utilisez `EnvironmentWorker` dans le SDK Python, TypeScript ou 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")
          # Sans arguments, handle_item() lit les variables ANTHROPIC_* que le script de lancement
          # a transmises, y compris ANTHROPIC_WORK_SECRET.
          task = asyncio.create_task(worker.handle_item())
          # Annuler la tâche à l'arrêt du conteneur permet au worker de téléverser
          # les fichiers de mémoire modifiés et de supprimer les répertoires du magasin avant de quitter.
          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();
  // Abandonner à l'arrêt du conteneur permet au worker d'envoyer les fichiers mémoire modifiés
  // et de supprimer les répertoires du magasin avant de quitter.
  process.once("SIGTERM", () => controller.abort());
  process.once("SIGINT", () => controller.abort());

  // Sans arguments, handleItem() lit les variables ANTHROPIC_* que le script de lancement
  // a transmises, y compris ANTHROPIC_WORK_SECRET.
  await new EnvironmentWorker({
    client,
    workdir: "/workspace",
    signal: controller.signal
  }).handleItem();
  ```

  <CodeGroupItem language="C#">
    Le SDK C# ne dispose pas de `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() {
  	// Annuler le contexte à l'arrêt du conteneur permet au worker de téléverser
  	// les fichiers de mémoire modifiés et de supprimer les répertoires du magasin avant de quitter.
  	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",
  	})
  	// Avec des options à valeur zéro, HandleItem lit les variables ANTHROPIC_* que le script de lancement
  	// a transmises, dont ANTHROPIC_WORK_SECRET.
  	if err := worker.HandleItem(ctx, environments.HandleItemOptions{}); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    Le SDK Java ne dispose pas de `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    Le SDK PHP ne dispose pas de `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Le SDK Ruby ne dispose pas de `EnvironmentWorker`.
  </CodeGroupItem>
</CodeGroup>

## Préparer des fichiers pour une session

Anthropic ne monte pas de fichiers ni de dépôts GitHub dans les sandboxes auto-hébergées. Pour rendre disponibles des fichiers propres à une session :

1. Transmettez des références de fichiers, comme un chemin S3 ou un SHA de commit, dans le champ `metadata` (csharp, go: `Metadata`) de la session.
2. Dans votre script de lancement ou votre gestionnaire `--on-work`, récupérez la session (`GET /v1/sessions/{session_id}`) et lisez `metadata` (csharp, go: `Metadata`). L’élément de travail réclamé porte l’ID de session, mais pas les métadonnées.
3. Préparez les fichiers dans le répertoire de travail avant l’exécution de tout outil.

L’exemple cURL lit un « access token » (jeton d’accès) depuis `ANTHROPIC_AUTH_TOKEN`. Pour en obtenir un, configurez Workload Identity Federation avec la portée par défaut `workspace:developer`, comme décrit dans [Configurer la fédération](https://platform.claude.com/docs/fr/manage-claude/workload-identity-federation#set-up-federation). Ensuite, échangez le jeton d’identité de votre charge de travail contre un jeton d’accès, comme illustré dans [S’authentifier depuis votre charge de travail](https://platform.claude.com/docs/fr/manage-claude/workload-identity-federation#authenticate-from-your-workload). Définissez `ANTHROPIC_AUTH_TOKEN` uniquement dans le shell où vous exécutez l’exemple cURL, car il a priorité sur vos paramètres de fédération. [Authentification](https://platform.claude.com/docs/fr/manage-claude/authentication) répertorie les autres identifiants acceptés par l’API, comme la clé API du démarrage rapide.

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

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Surveiller et dépanner les workers auto-hébergés" icon="lightning" href="https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-operations">
    Consultez la profondeur de la file, arrêtez proprement les sessions et les workers, et corrigez les défaillances courantes.
  </Card>
</CardGroup>
