Sandboxes auto-hébergées

Par défaut, Managed Agents exécute les outils et le code dans des sandboxes cloud gérées par Anthropic. Les « self-hosted sandboxes » (sandboxes auto-hébergées, ou bacs à sable auto-hébergés) conservent l'orchestration du côté d'Anthropic mais déplacent l'exécution des outils vers une infrastructure que vous contrôlez, de sorte que le code de l'agent, son système de fichiers et son trafic réseau sortant ne quittent jamais votre environnement.

L'exécution des outils reste sur votre hôte : le système de fichiers que l'agent lit et écrit, les processus qu'il lance et le réseau qu'il peut atteindre sont tous sous votre contrôle. Les entrées et sorties des outils transitent toujours vers le plan de contrôle d'Anthropic (où Claude s'exécute) afin que le modèle puisse voir les résultats et déterminer la suite. Les skills (compétences) de l'agent et le contenu de tous les memory stores (magasins de mémoire) attachés à la session sont stockés par Anthropic et copiés dans votre sandbox pour la durée de la session ; les modifications que l'agent apporte aux fichiers de mémoire sont resynchronisées vers le magasin. Consultez le modèle de sécurité pour connaître la frontière complète des flux de données.

Différences avec les environnements cloud

L'auto-hébergement convient bien lorsque l'agent doit opérer sur des données qui ne peuvent pas quitter le périmètre de votre réseau, atteindre des services internes qui ne sont pas routables publiquement, ou s'exécuter sous les propres contrôles de conformité et d'audit de votre organisation.

Pour l'éligibilité à la rétention zéro des données (Zero Data Retention) et au HIPAA BAA, consultez API et rétention des données.

Quand combiner avec les tunnels MCP

L'auto-hébergement contrôle l'endroit où le code de l'agent s'exécute. Les tunnels MCP contrôlent la manière dont Anthropic atteint les serveurs MCP de votre réseau. Les deux sont indépendants : une session s'exécutant dans les sandboxes cloud d'Anthropic peut toujours atteindre des serveurs MCP privés via un tunnel, et une session auto-hébergée peut utiliser des serveurs MCP tunnelisés ou publics. Utilisez les deux lorsque vous souhaitez que l'exécution et l'accès aux outils restent à l'intérieur de votre périmètre. Pour donner à l'agent des outils provenant d'un serveur MCP situé dans votre réseau sans exécuter de tunnel, vous pouvez également encapsuler le serveur sous forme d'outils personnalisés servis par votre worker.

Worker d'environnement

Un « environment worker » (worker d'environnement) est un processus que vous exécutez sur votre propre infrastructure. Il reçoit des requêtes d'exécution d'outils de la part d'Anthropic et les exécute localement. L'environnement self_hosted agit comme une « work queue » (file d'attente de travail) : lorsqu'une session lui est assignée, Anthropic met la session en file d'attente sous forme de « work item » (élément de travail). Votre worker réclame les éléments de travail de cette file, crée un contexte d'exécution pour chacun d'eux, télécharge les skills de l'agent (des ressources réutilisables, basées sur le système de fichiers, qui confèrent à l'agent une expertise propre à un domaine), exécute les appels d'outils et renvoie les résultats.

Les éléments de travail sont réclamés en interrogeant la file d'attente de l'environnement : soit par un worker toujours actif qui interroge en continu, soit par un gestionnaire déclenché par webhook qui se réveille sur session.status_run_started et commence à interroger.

La CLI et le SDK fournissent tous deux des workers préconstruits. La CLI ant ne prend en charge que le modèle toujours actif ; le SDK prend en charge à la fois le modèle toujours actif et le modèle déclenché par webhook. Les deux sont configurables : consultez Worker auto-hébergé dans la référence pour les options de la CLI, et Assistants du SDK sur cette page pour les options du SDK. Pour plus de contrôle, appelez directement les points de terminaison Environments Work et implémentez votre propre worker.

Système de fichiers de la sandbox

• /workspace : le répertoire de travail par défaut du système pour l'exécution des outils et le téléchargement des skills. L'option --workdir de la CLI utilise par défaut le répertoire courant ; passez --workdir /workspace pour correspondre à la valeur par défaut du système. Les skills sont téléchargées dans <workdir>/skills/<name>/. Si vous utilisez un répertoire de travail différent, mettez à jour l'invite système de votre agent afin que Claude puisse localiser les fichiers des skills.
• Sorties : sur les environnements auto-hébergés, l'invite système de la session omet l'instruction /mnt/session/outputs utilisée sur les sandboxes gérées par Anthropic, de sorte que les livrables finaux se retrouvent là où l'agent les écrit dans le système de fichiers de votre sandbox, généralement sous le répertoire de travail.
• /mnt/memory/ : les magasins de mémoire attachés à la session sont matérialisés ici par le worker du SDK, un répertoire par magasin au mount_path du magasin (par exemple, /mnt/memory/user-preferences/). Le worker crée ces répertoires lorsqu'il réclame la session et les supprime lorsque la session se termine ; consultez Utiliser les magasins de mémoire.

Avant de commencer

Vous avez besoin de :

• Un agent existant. Si vous n'en avez pas, suivez d'abord le Démarrage rapide et notez son ID d'agent.
• Un hôte Linux avec /bin/bash à cet emplacement exact. L'outil bash du worker l'invoque directement, sans consulter PATH. Le SDK TypeScript requiert en outre unzip et tar dans le PATH ainsi que Node.js 22 ou ultérieur ; les SDK Python et Go utilisent leurs bibliothèques standard pour l'extraction d'archives et n'ont aucune exigence binaire supplémentaire.
• La CLI ant ou un SDK Anthropic (Python, TypeScript ou Go) sur l'hôte du worker.
• Des identifiants : une clé d'environnement (générée dans la Console lors des étapes qui suivent) authentifie le worker auprès de sa file d'attente ; votre clé API Claude crée les sessions et lit les statistiques de la file depuis l'extérieur de l'hôte du worker. La génération de clés se fait uniquement dans la Console. Les éléments de travail réclamés portent également un secret par session que le worker utilise pour monter les magasins de mémoire ; vous ne le générez pas, mais dans le modèle d'une sandbox par session, vous le transmettez vous-même à la sandbox (consultez Exécuter une sandbox par session).
• Pour les magasins de mémoire, un hôte préparé. Si les sessions de cet environnement attachent des magasins de mémoire, préparez /mnt/memory sur l'hôte du worker avant de démarrer le worker ; consultez Préparer l'hôte.

1. 1

   Créer un environnement auto-hébergé

   Dans la Console : Workspace > Environments > New > Self-hosted

   Ou via l'API :

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client = anthropic.Anthropic()
   
   environment = client.beta.environments.create(
       name="self-hosted", config={"type": "self_hosted"}
   )
   print(environment.id)

2. 2

   Générer une clé d'environnement

   Dans la Console, ouvrez l'environnement et cliquez sur Generate environment key. La génération de clés se fait uniquement dans la Console, que vous ayez créé l'environnement via la Console ou via l'API. Exportez ensuite l'ID et la clé de l'environnement sur l'hôte du worker :

   export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
   export ANTHROPIC_ENVIRONMENT_ID="env_..."

   

Exécuter un worker

Choisissez toujours actif pour la configuration la plus simple : un processus de longue durée interroge la file d'attente en continu et ne nécessite que du HTTPS sortant. Choisissez déclenché par webhook pour éviter d'exécuter un processus d'interrogation inactif ; cela nécessite un point de terminaison webhook qu'Anthropic peut atteindre (consultez Webhooks pour la configuration du point de terminaison et la vérification des signatures).

Assistants du SDK

Le SDK fournit trois « helpers » (assistants) à différents niveaux de contrôle. EnvironmentWorker couvre la plupart des cas d'usage ; descendez vers les assistants de plus bas niveau lorsque vous devez lancer votre propre processus par session ou exécuter des outils sur une session déjà réclamée.

• EnvironmentWorker : le worker prêt à l'emploi. Gère l'interrogation, la configuration et l'exécution de bout en bout.
  • .run() : s'exécute indéfiniment, prenant en charge les sessions au fur et à mesure de leur arrivée.
  • .handle_item() : gère un seul élément de travail réclamé puis se termine. Passez explicitement les identifiants de travail, de session et d'environnement, ou laissez-le lire les variables ANTHROPIC_* que ant beta:worker poll --on-work définit pour le processus qu'il lance. Pour permettre à la session de monter ses magasins de mémoire, passez également le secret de l'élément de travail en tant que work_secret (workSecret en TypeScript, WorkSecret en Go) ou définissez ANTHROPIC_WORK_SECRET ; ant beta:worker poll --on-work ne définit pas cette variable, lisez donc le secret depuis le JSON de l'élément de travail qu'il écrit sur l'entrée standard de votre script, comme indiqué dans Exécuter une sandbox par session.
  • memory_sync_interval (memorySyncIntervalMs en TypeScript, MemorySyncInterval en Go) et memory_sync_deletions (memorySyncDeletions, MemorySyncDeletions) : la fréquence à laquelle les magasins de mémoire attachés se réconcilient avec le serveur pendant l'exécution de la session, et si les fichiers que l'agent supprime localement sont également supprimés du magasin. Consultez Configurer la synchronisation pour les unités, les valeurs par défaut et la manière de désactiver la prise en charge de la mémoire.
• work.poller() : interroge la file d'attente de travail pour vous et vous remet chaque session réclamée. Utilisez-le lorsque vous souhaitez décider de ce qui se passe pour chaque session, par exemple lancer une sandbox plutôt que d'exécuter les outils dans le processus.
  • drain : indique s'il faut arrêter l'interrogation une fois la file vide plutôt que d'attendre un nouveau travail.
  • block_ms : durée d'attente de l'arrivée d'un travail avant de retourner, en millisecondes. Doit être comprise entre 1 et 999 (attente par interrogation ; l'assistant réinterroge automatiquement). Passez null (None en Python, param.Null[int64]() en Go) pour une vérification non bloquante ; omettre le paramètre utilise l'interrogation longue par défaut de 999 ms.
  • reclaim_older_than_ms : réclame à nouveau les éléments de travail qui ont été réclamés mais jamais acquittés dans ce délai en millisecondes.
  • auto_stop (autoStop en TypeScript, AutoStop en Go) : indique s'il faut publier un signal d'arrêt pour chaque élément de travail une fois que le corps de votre boucle en a terminé avec lui. Désactivez-le chaque fois que ce qui exécute l'élément de travail publie lui-même l'arrêt : handle_item() le fait, donc définissez-le à false lorsque vous transmettez des éléments réclamés à handle_item() comme le font les gestionnaires de webhook de cette page, et il en va de même pour une sandbox que vous lancez et qui est responsable de l'appel d'arrêt.
• client.beta.sessions.events.tool_runner() : exécute les appels d'outils pour une seule session, à partir de l'ID de session et d'une liste d'outils. À utiliser lorsque vous avez déjà réclamé le travail et n'avez besoin que de la couche d'exécution.

Utilisez directement le work poller lorsque vous souhaitez lancer votre propre processus par session, par exemple en démarrant une sandbox pour chaque session réclamée :

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-sdk-worker-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())

Quel que soit le mécanisme qui lance la sandbox, il doit y transmettre le secret de l'élément de travail réclamé (par exemple en tant que ANTHROPIC_WORK_SECRET) en plus des identifiants de session, de travail et d'environnement, afin que le worker à l'intérieur puisse monter les magasins de mémoire de la session ; consultez Exécuter une sandbox par session.

AgentToolContext est le contexte d'exécution des appels d'outils. Il définit le répertoire de travail et la politique de chemins, et peut télécharger les skills de la session. Les outils de fichiers (read, write, edit, glob, grep) sont confinés au répertoire de travail ainsi qu'aux répertoires listés dans allowed_roots (allowedRoots en TypeScript, AllowedRoots en Go), et write et edit refusent en outre les chemins situés sous read_only_roots (readOnlyRoots, ReadOnlyRoots). EnvironmentWorker ajoute lui-même les répertoires des magasins de mémoire de la session à ces listes. Le confinement est un garde-fou pour les outils de fichiers uniquement, pas une sandbox ; il ne contraint pas bash. beta_agent_toolset_20260401(env) prend un AgentToolContext et renvoie les implémentations d'outils standard (bash, read, write, edit, glob, grep).

Avec EnvironmentWorker : les deux sont gérés automatiquement. Passez une fabrique tools pour personnaliser la liste d'outils :

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

Avec work.poller() et tool_runner() : passez une liste d'outils en tant que tools à client.beta.sessions.events.tool_runner(). Pour construire cette liste, configurez vous-même AgentToolContext et appelez beta_agent_toolset_20260401(env) :

from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # skills téléchargés vers /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

Vérifier que le worker est connecté

Depuis un shell séparé, avec ANTHROPIC_API_KEY défini sur votre clé API Claude (et non la clé d'environnement), confirmez que workers_polling vaut au moins 1 :

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

Si workers_polling reste à 0, le worker n'atteint pas la file d'attente : confirmez que ANTHROPIC_ENVIRONMENT_KEY et ANTHROPIC_ENVIRONMENT_ID sont définis sur l'hôte du worker. Consultez Lire la profondeur de la file pour la réponse complète des statistiques et des exemples dans d'autres langages.

Démarrer une session

Une fois votre worker en cours d'exécution, créez une session qui cible l'environnement. Définissez AGENT_ID sur l'ID d'agent que vous avez noté dans Avant de commencer. La session entre dans la file d'attente de travail de l'environnement et y attend jusqu'à ce qu'un worker la réclame ; si aucun worker n'est connecté, la session reste en file d'attente au lieu d'échouer.

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, passez des références de fichiers (telles qu'un chemin S3 ou un SHA de commit) dans le champ metadata de la session. L'élément de travail réclamé ne porte pas les métadonnées de la session, mais il porte l'ID de session : votre script de lancement ou votre gestionnaire --on-work récupère la session (GET /v1/sessions/{session_id}) pour lire le champ metadata, puis prépare les fichiers dans le répertoire de travail avant le début de l'exécution des outils.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

Consultez Worker auto-hébergé dans la référence pour la liste complète des options de la CLI, et Assistants du SDK pour les options des assistants du SDK.

Utiliser les magasins de mémoire

Les sessions sur un environnement auto-hébergé attachent des magasins de mémoire exactement comme le font les sessions sur les environnements cloud : listez-les dans resources lorsque vous créez la session, comme indiqué dans Attacher un magasin de mémoire à une session. Une session accepte jusqu'à 8 magasins de mémoire. Sur un environnement auto-hébergé, c'est le worker du SDK, et non l'infrastructure d'Anthropic, qui matérialise chaque magasin pour l'agent ; les magasins de mémoire y requièrent donc EnvironmentWorker (ou sa méthode handle_item()) du SDK Python, TypeScript ou Go.

Le worker de la CLI ant (ant beta:worker poll et ant beta:worker run) ne monte pas les magasins de mémoire. Pour combiner le processus d'interrogation de la CLI avec les magasins de mémoire, exécutez le worker du SDK dans une sandbox par session comme décrit dans Exécuter une sandbox par session.

Les magasins de mémoire ne peuvent pas être attachés aux sessions sur des environnements auto-hébergés sur Claude Platform on AWS.

Comment le worker gère la mémoire

Lorsque le worker réclame un élément de travail dont la session a des magasins de mémoire attachés, il :

1. Télécharge chaque magasin attaché vers son mount_path sur l'hôte du worker, en s'authentifiant avec le secret par session de l'élément de travail. Le mount_path est le même répertoire sous /mnt/memory/ que celui utilisé par les sessions cloud (par exemple, /mnt/memory/user-preferences/ pour un magasin nommé « User Preferences »), et l'invite système de la session le décrit à l'agent.
2. Ajoute ces répertoires aux racines autorisées des outils de fichiers, et les répertoires des magasins attachés avec access: "read_only" à leurs racines en lecture seule, afin que l'agent travaille sur les mémoires avec les mêmes outils read, write, edit, glob et grep qu'il utilise dans le répertoire de travail.
3. Réconcilie les modifications locales et distantes après les appels d'outils, au plus une fois par intervalle de synchronisation (15 secondes par défaut) : les mémoires qui ont changé dans le magasin sont écrites sur le disque, et les fichiers que l'agent a modifiés sont téléversés vers le magasin.
4. Exécute une synchronisation finale lorsque la session se termine, vide les téléversements encore en attente pendant au plus 30 secondes, puis supprime les répertoires qu'il a créés. Un worker annulé pendant l'exécution d'une session ignore la synchronisation finale mais téléverse tout de même les fichiers modifiés et supprime les répertoires avant de se terminer.

Le magasin de mémoire du côté d'Anthropic reste la source de vérité. Les versions de mémoire, la rédaction (masquage), ainsi que la consultation ou la modification des mémoires dans la Console fonctionnent comme pour les sessions cloud, et les lectures et écritures de mémoire de l'agent apparaissent dans le flux d'événements comme des événements d'outils ordinaires. Comme chaque worker se synchronise à intervalle régulier, une modification écrite dans une session ne devient visible pour une autre session en cours qu'après que les deux se sont synchronisées, généralement bien en dessous d'une minute avec l'intervalle par défaut ; les sessions sur les sandboxes cloud voient les modifications des autres presque immédiatement.

Chaque répertoire de magasin contient un fichier marqueur nommé .anthropic-memory-store qui lie le répertoire à son magasin. Laissez-le en place : le worker ne synchronise pas un répertoire dont le marqueur est manquant ou altéré.

Préparer l'hôte

Les magasins de mémoire sur les sandboxes auto-hébergées nécessitent un système de fichiers POSIX sur l'hôte du worker (l'hôte Linux de Avant de commencer) ; les hôtes Windows ne sont pas pris en charge, car le worker requiert O_NOFOLLOW lorsqu'il ouvre les fichiers de mémoire. Un système de fichiers sensible à la casse est recommandé, afin que les chemins de mémoire qui ne diffèrent que par la casse n'entrent pas en collision.

Avant de démarrer le worker, créez le répertoire parent et rendez-le accessible en écriture à l'utilisateur sous lequel le worker s'exécute :

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

Ne créez pas vous-même les répertoires par magasin. Le worker crée le répertoire mount_path de chaque magasin (par exemple, /mnt/memory/user-preferences) lorsqu'une session démarre, refuse de démarrer le travail de la session si quelque chose existe déjà à ce chemin, et supprime le répertoire lorsque la session se termine. Deux règles d'exploitation en découlent :

• Exécutez une session par système de fichiers lorsque les sessions attachent le même magasin. Deux sessions ne peuvent pas monter le même magasin sur un même hôte en même temps, car les deux ont besoin du même chemin. Donner à chaque session sa propre sandbox, comme décrit dans Exécuter une sandbox par session, satisfait cette règle.
• Arrêtez les workers proprement. Lorsque vous arrêtez un worker pendant l'exécution d'une session, EnvironmentWorker téléverse les fichiers de mémoire modifiés de la session et supprime ses répertoires de magasin uniquement s'il est annulé plutôt que tué : un processus tué n'exécute aucun nettoyage, et le worker n'installe pas lui-même de gestionnaires de signaux. Reliez SIGTERM et SIGINT à l'annulation dans le processus qui l'exécute : interrompez le signal que vous passez au worker en TypeScript, annulez le contexte en Go, et en Python annulez la tâche qui exécute run() ou handle_item(). Faites-le depuis un gestionnaire de signaux lorsque votre worker est le processus, comme le font les workers autonomes de cette page, ou depuis le propre hook d'arrêt de votre serveur lorsque le worker s'exécute à l'intérieur d'un gestionnaire de webhook, qui ne doit pas prendre le contrôle des signaux du serveur. Arrêtez ensuite les workers avec SIGTERM et accordez-leur au moins 30 secondes pour se terminer avant tout arrêt forcé, car le téléversement final peut prendre ce temps. Si un worker est tué avant l'exécution de son nettoyage, supprimez le répertoire de magasin restant sous /mnt/memory/ avant la prochaine session qui attache ce magasin ; toutes les modifications qu'il contenait et qui n'avaient pas été synchronisées sont perdues.

Exécuter une sandbox par session

Le modèle « sandbox-per-session » (une sandbox par session) décrit dans Exécuter un worker donne à chaque session un système de fichiers neuf, ce qui est exactement ce que demande Préparer l'hôte lorsque des sessions attachent le même magasin. Conservez ant beta:worker poll --on-work (ou le poller de travail du SDK) comme poller sur l'hôte.

Le point d'entrée ant beta:worker run présenté à cet endroit ne monte pas les « memory stores » (magasins de mémoire) ; construisez donc plutôt l'image par session autour du worker du SDK : son point d'entrée construit EnvironmentWorker et appelle handle_item() (handleItem en TypeScript, HandleItem en Go), qui lit les identifiants de session, de travail et d'environnement depuis les variables ANTHROPIC_* et le secret par session de l'élément de travail depuis ANTHROPIC_WORK_SECRET. Vous pouvez également transmettre le secret explicitement via work_secret (workSecret en TypeScript, WorkSecret en Go).

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 lorsque le conteneur est arrêté permet au worker de téléverser
        # les fichiers mémoire modifiés et de supprimer les répertoires du store 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())

ant beta:worker poll --on-work ne définit pas ANTHROPIC_WORK_SECRET pour le script qu'il lance ; le script de lancement lit donc le secret depuis le JSON de l'élément de travail sur son entrée standard et le transmet à la sandbox :

#!/bin/bash
# spawn.sh : appelé une fois par élément de travail réclamé
# L'élément de travail réclamé arrive en JSON sur stdin. Son secret est
# l'identifiant par session requis par les endpoints du magasin de mémoire.
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-sdk-worker-image

Si vous réclamez le travail avec le poller de travail du SDK à la place, transmettez de la même manière le secret de chaque élément réclamé à la sandbox que vous lancez. Ne le transmettez qu'à la sandbox qui sert cette session, et ne le journalisez jamais.

L'image de la sandbox a également besoin d'un /mnt/memory accessible en écriture (voir Préparer l'hôte). Comme chaque sandbox sert une seule session et est supprimée ensuite, aucun répertoire résiduel n'a besoin d'être nettoyé, et les répertoires de mémoire n'ont pas besoin d'être montés par liaison (bind-mount) sur l'hôte : le worker téléverse leur contenu vers le magasin avant que la sandbox ne se termine. Si vous arrêtez un conteneur avant la fin de sa session, envoyez un signal que le point d'entrée transforme en annulation (voir Préparer l'hôte) plutôt que de le tuer, afin que ce téléversement s'exécute quand même. Laissez également au conteneur le temps de terminer le téléversement : Docker fait suivre le signal d'arrêt d'un SIGKILL après 10 secondes par défaut ; relevez donc cette limite à au moins les 30 secondes que demande Préparer l'hôte, avec --stop-timeout sur docker run ou le délai de grâce de terminaison de votre orchestrateur.

Configurer la synchronisation

Deux options de EnvironmentWorker contrôlent le comportement de la mémoire :

• memory_sync_interval (Python, en secondes ; memorySyncIntervalMs en TypeScript, en millisecondes ; MemorySyncInterval en Go, une durée) : la fréquence à laquelle les magasins attachés se réconcilient avec le serveur pendant l'exécution de la session. La valeur par défaut est de 15 secondes ; le minimum est de 5 secondes. Un intervalle plus court réduit la fenêtre pendant laquelle une autre session voit des mémoires obsolètes, au prix d'un plus grand nombre de requêtes vers le magasin de mémoire. None en Python, null en TypeScript ou une durée négative en Go désactive entièrement la prise en charge de la mémoire : le worker ne télécharge ni ne synchronise les magasins, et une session avec des magasins de mémoire attachés s'exécute sans eux même si son invite système les décrit toujours ; ne désactivez donc la prise en charge de la mémoire que sur les workers dont les sessions n'attachent aucun magasin de mémoire. Tant que la prise en charge de la mémoire est activée, un élément de travail qui arrive sans secret par session pour une session avec des magasins attachés échoue au lieu de s'exécuter sans mémoire (voir Dépanner les montages de mémoire).
• memory_sync_deletions (memorySyncDeletions en TypeScript, MemorySyncDeletions en Go) : indique si un fichier que l'agent supprime localement est également supprimé du magasin. La valeur est l'une de "enabled" (par défaut), "log_only" ou "disabled" en Python et TypeScript, et l'une des constantes environments.MemorySyncDeletionsEnabled (la valeur zéro), environments.MemorySyncDeletionsLogOnly ou environments.MemorySyncDeletionsDisabled en Go. Lorsqu'elle est activée, le worker supprime la mémoire du magasin une fois qu'une synchronisation ultérieure confirme que le fichier est toujours absent ; en mode journalisation seule, il effectue les mêmes vérifications mais ne fait que journaliser ce qu'il aurait supprimé, ce qui vous permet d'observer ce que vos workers supprimeraient avant de faire confiance au mode activé ; lorsqu'elle est désactivée, il ne supprime jamais rien du magasin. Les téléversements et téléchargements ne sont pas affectés par ce paramètre.

Définissez ces options là où vous construisez le worker, que ce soit via le constructeur EnvironmentWorker ou, en Python et TypeScript, via la fabrique client.beta.environments.work.worker() qu'utilise le gestionnaire de webhook.

Par exemple, pour synchroniser toutes les 10 secondes et ne faire que journaliser les suppressions que le worker aurait effectuées :

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

Magasins en lecture seule et conflits

Pour un magasin attaché avec access: "read_only", les outils write et edit refusent de modifier les fichiers à l'intérieur de son répertoire, et le worker ne téléverse jamais rien depuis celui-ci. Les modifications effectuées via bash, ou via un outil personnalisé ou un serveur MCP que vous servez depuis la sandbox, ne sont pas bloquées localement : elles ne sont jamais synchronisées vers le magasin, et la prochaine modification distante de cette mémoire les écrase. Si vous avez besoin que la copie locale elle-même reste inchangée pendant la session, désactivez l'outil bash pour cet agent et ne lui donnez aucun outil personnalisé qui écrit dans le système de fichiers de la sandbox ; ne montez pas le chemin du magasin en lecture seule, car le worker lui-même doit créer le répertoire et y écrire les mémoires téléchargées.

Les conflits se résolvent en faveur du magasin. Lorsque l'agent modifie un fichier de mémoire qui a également changé dans le magasin depuis la dernière synchronisation de la session, le worker conserve la version du magasin lors de la synchronisation suivante, écrase le fichier local avec celle-ci et journalise un avertissement ; les outils write et edit eux-mêmes réussissent et aucune erreur ne parvient à l'agent. Si la modification de l'agent s'applique toujours, il peut relire le fichier après la synchronisation et effectuer à nouveau la modification.

Dépanner les montages de mémoire

Le worker journalise les échecs de montage et de synchronisation en arrière-plan au lieu de les signaler à la session ; seuls les refus en lecture seule parviennent à l'agent, sous forme d'erreurs d'outil (voir Magasins en lecture seule et conflits). Si un magasin de mémoire ne peut pas être monté lorsque le worker réclame une session, le worker fait échouer l'élément de travail : la session n'émet aucun événement d'erreur et reste inactive.

Servir des outils personnalisés depuis votre sandbox

Les outils personnalisés sont des outils que votre propre code exécute : l'agent émet un événement agent.custom_tool_use et attend un user.custom_tool_result correspondant. Le worker peut être ce code, et comme il s'exécute à l'intérieur de votre sandbox, l'outil accède aux services internes, aux identifiants et à la sortie réseau que vous avez configurés pour la sandbox, et à rien de plus. La clé d'environnement autorise la publication des résultats d'outils personnalisés, de sorte que votre clé API Claude reste hors de l'hôte du worker.

1. 1

   Déclarer l'outil sur l'agent

   Ajoutez une entrée custom aux tools de l'agent dont le name correspond à l'outil que votre worker enregistre. Consultez Outils personnalisés pour la forme complète de la déclaration.

   {
     "type": "custom",
     "name": "get_order_status",
     "description": "Look up an order in the internal fulfillment system by order ID.",
     "input_schema": {
       "type": "object",
       "properties": {
         "order_id": { "type": "string", "description": "The order ID" }
       },
       "required": ["order_id"]
     }
   }

   
2. 2

   Enregistrer l'implémentation auprès du worker

   Transmettez l'outil via la fabrique tools du worker (voir Assistants du SDK), aux côtés de l'ensemble d'outils intégré :

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   import os
   from anthropic import AsyncAnthropic, beta_async_tool
   from anthropic.lib.environments import EnvironmentWorker
   from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
   
   
   @beta_async_tool
   async def get_order_status(order_id: str) -> str:
       """Look up an order in the internal fulfillment system by order ID."""
       # S'exécute sur l'hôte du worker : appelez tout ce que la sandbox peut atteindre.
       return f"Order {order_id}: shipped"
   
   
   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:
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
               tools=lambda env: [*beta_agent_toolset_20260401(env), get_order_status],
           ).run()
   
   
   asyncio.run(main())

Le worker ne répond qu'aux outils enregistrés auprès de lui. Un outil personnalisé déclaré sur l'agent mais enregistré auprès d'aucun worker ni client laisse la session en pause avec un motif d'arrêt requires_action jusqu'à ce que quelque chose publie son résultat ; consultez Gérer les appels d'outils personnalisés pour le flux d'événements.

Encapsuler un serveur MCP sous forme d'outils personnalisés

Le connecteur MCP se connecte aux serveurs MCP depuis le côté d'Anthropic ; un serveur doit donc exposer un point de terminaison HTTP qu'Anthropic peut atteindre, directement ou via un tunnel MCP. Pour utiliser un serveur que seul votre réseau peut atteindre, faites plutôt du worker le client MCP et déclarez les outils du serveur comme outils personnalisés. Le serveur MCP n'a besoin d'aucune connectivité entrante depuis l'extérieur de votre réseau ; Anthropic reçoit les définitions d'outils que vous déclarez sur l'agent, l'entrée de chaque appel et le résultat que votre worker publie en retour. À l'exécution, le modèle appelle un outil encapsulé comme n'importe quel autre outil personnalisé :

1. L'agent émet un événement agent.custom_tool_use.
2. Le worker, à l'intérieur de votre sandbox, transmet l'appel via sa session MCP ouverte au serveur sur votre réseau.
3. Le worker publie la réponse du serveur en tant que user.custom_tool_result.

Les assistants MCP côté client des SDK convertissent les outils du serveur en outils exécutables que le worker accepte ; installez un SDK MCP aux côtés du SDK Anthropic (pip install "anthropic[mcp]" "mcp>=1.24", npm install @modelcontextprotocol/sdk, go get github.com/modelcontextprotocol/go-sdk). Les exemples se connectent sans authentification ; pour envoyer des identifiants, configurez le client HTTP ou les options de requête que vous transmettez au transport MCP (http_client en Python, requestInit en TypeScript, HTTPClient en Go).

1. 1

   Déclarer les outils du serveur sur l'agent

   Listez les outils du serveur MCP et déclarez chacun d'eux comme outil custom ; les champs MCP name, description et inputSchema correspondent un à un aux champs de l'outil personnalisé. Si le serveur pagine sa liste d'outils, déclarez chaque page ; le worker doit lister les mêmes pages.

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   from typing import Any, cast
   from anthropic import AsyncAnthropic
   from anthropic.types.beta import BetaManagedAgentsCustomToolParams
   from mcp import ClientSession, types
   # Nécessite mcp >= 1.24, qui a renommé streamablehttp_client en streamable_http_client.
   from mcp.client.streamable_http import streamable_http_client
   
   MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
   
   
   def to_custom_tool(tool: types.Tool) -> BetaManagedAgentsCustomToolParams:
       # Les champs MCP correspondent un à un à une déclaration d'outil personnalisé. Le cast
       # transmet le dictionnaire de schéma au paramètre typé du SDK sans modification.
       return {
           "type": "custom",
           "name": tool.name,
           "description": tool.description or tool.name,
           "input_schema": cast(Any, tool.inputSchema),
       }
   
   
   async def main() -> None:
       # Exécutez ceci là où vous créez les agents, pas sur l'hôte worker : il
       # s'authentifie avec votre clé API Claude (ANTHROPIC_API_KEY).
       async with (
           streamable_http_client(MCP_SERVER_URL) as (read, write, _),
           ClientSession(read, write) as mcp_session,
           AsyncAnthropic() as client,
       ):
           await mcp_session.initialize()
           listed = await mcp_session.list_tools()
           agent = await client.beta.agents.create(
               name="Internal tools agent",
               model="claude-opus-5",
               tools=[
                   {"type": "agent_toolset_20260401"},
                   *[to_custom_tool(tool) for tool in listed.tools],
               ],
           )
           print(agent.id)
   
   
   asyncio.run(main())

2. 2

   Servir les outils depuis le worker

   Connectez-vous au même serveur MCP au démarrage, convertissez ses outils avec les assistants MCP et enregistrez-les aux côtés de l'ensemble d'outils intégré. Gardez une seule session MCP ouverte pendant toute la durée de vie du worker.

   PythonTypeScriptC#GoJavaPHPRuby

   

   import asyncio
   import os
   from datetime import timedelta
   from anthropic import AsyncAnthropic
   from anthropic.lib.environments import EnvironmentWorker
   from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
   from anthropic.lib.tools.mcp import async_mcp_tool
   from mcp import ClientSession
   # Nécessite mcp >= 1.24, qui a renommé streamablehttp_client en streamable_http_client.
   from mcp.client.streamable_http import streamable_http_client
   
   MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
   
   
   async def main() -> None:
       environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
       environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
       # Se connecte au serveur MCP une seule fois au démarrage et garde la session ouverte pendant
       # toute la vie du worker. Le timeout transforme un appel d'outil bloqué en un résultat
       # d'erreur plutôt qu'en un appel figé.
       async with (
           streamable_http_client(MCP_SERVER_URL) as (read, write, _),
           ClientSession(read, write, read_timeout_seconds=timedelta(seconds=60)) as mcp_session,
           AsyncAnthropic(auth_token=environment_key) as client,
       ):
           await mcp_session.initialize()
           listed = await mcp_session.list_tools()
           mcp_tools = [async_mcp_tool(tool, mcp_session) for tool in listed.tools]
           await EnvironmentWorker(
               client,
               environment_id=environment_id,
               environment_key=environment_key,
               workdir="/workspace",
               tools=lambda env: [*beta_agent_toolset_20260401(env), *mcp_tools],
           ).run()
   
   
   asyncio.run(main())

Gardez les points suivants à l'esprit lorsque vous encapsulez un serveur MCP :

• Les outils sont déclarés, et non découverts à l'exécution. Le worker liste les outils du serveur MCP une seule fois au démarrage et ne peut pas ajouter d'outils à une session en cours. Lorsque les outils du serveur changent, déclarez-les à nouveau, sur l'agent ou sur une session inactive via Mettre à jour la configuration de l'agent, et redémarrez le worker.
• Les noms et descriptions doivent respecter l'API Managed Agents. Les noms d'outils personnalisés sont uniques par agent et utilisent des lettres, des chiffres, des traits de soulignement et des tirets (1 à 128 caractères) ; une description non vide est requise ; et le tableau tools d'un agent accepte au plus 128 entrées (chaque outil encapsulé compte pour une entrée, et l'ensemble d'outils intégré pour une de plus). L'API rejette une déclaration qui réutilise un nom d'outil, qui nomme un outil personnalisé d'après un outil d'agent intégré tel que bash ou read, ou qui utilise le préfixe réservé mcp__. Les assistants MCP conservent les noms et descriptions du serveur ; renommez ou raccourcissez donc si nécessaire. Lorsque deux serveurs exposent le même nom d'outil, définissez vous-même l'encapsuleur sous un nom préfixé et faites-lui appeler le nom d'outil d'origine du serveur.
• La plupart des schémas passent sans modification. L'API accepte les mots-clés JSON Schema que les serveurs MCP émettent couramment, tels que additionalProperties et title. Elle rejette les mots-clés de référence tels que $ref où qu'ils se trouvent dans le input_schema d'un outil personnalisé ; intégrez donc en ligne les schémas que des générateurs tels que pydantic factorisent dans $defs. Elle rejette également oneOf, anyOf et allOf au niveau supérieur, ainsi que les noms de propriétés contenant autre chose que des lettres, des chiffres, des traits de soulignement, des points et des tirets (1 à 64 caractères).
• Les échecs d'outils apparaissent sous forme de résultats d'outil en erreur. Lorsque le serveur MCP signale une erreur d'outil, le worker publie un résultat d'outil en erreur auquel le modèle peut réagir. Le contenu MCP sans équivalent en résultat d'outil, tel que les blocs audio et les liens de ressources, apparaît également sous forme d'erreur. Définissez un délai d'expiration sur le client MCP pour un échec plus rapide et plus clair, comme le fait l'exemple de worker Python avec read_timeout_seconds. Sans cela, un appel bloqué ne devient un résultat en erreur que lorsque le délai d'expiration de requête par défaut du SDK MCP TypeScript se déclenche (environ une minute) ou lorsque le garde-fou propre au worker le fait : environ deux minutes et demie en Python, et deux minutes en Go, où le worker annule un appel d'outil qui dépasse sa valeur par défaut de 120 secondes et publie un résultat en erreur.
• Encapsulez des serveurs que vous exploitez ou auxquels vous faites confiance. Le nom, la description et les résultats d'un outil encapsulé entrent dans le contexte du modèle comme ceux de n'importe quel autre outil : une entrée non fiable qui peut influencer ce que l'agent fait avec ses autres outils, y compris bash sur l'hôte du worker. Ne déclarez que les outils que vous souhaitez que l'agent utilise.
• Les politiques d'autorisation ne s'appliquent pas aux outils personnalisés. Les politiques d'autorisation régissent les ensembles d'outils intégrés et MCP ; le worker exécute chaque appel d'outil encapsulé que le modèle effectue ; placez donc toute étape d'approbation dans votre propre code d'outil.

Surveillance et opérations

Ces appels s'exécutent depuis vos outils de surveillance ou d'exploitation, authentifiés avec votre clé API Claude, pour observer et gérer la flotte de workers. La boucle de réclamation et de maintien en vie est gérée à l'intérieur des assistants du worker ; vous n'appelez donc pas ces points de terminaison directement.

Lire la profondeur de la file d'attente

work.stats renvoie l'état de la file d'attente pour un environnement :

• depth est le nombre d'éléments en attente d'être réclamés. Dimensionnez votre flotte de workers ou déclenchez des alertes sur l'arriéré en fonction de cette valeur.
• pending est le nombre d'éléments réclamés par un worker mais pas encore acquittés. Les assistants du worker acquittent chaque élément avant de le traiter ; cette valeur reste donc proche de zéro en fonctionnement normal ; une valeur non nulle persistante signifie qu'un worker s'est bloqué entre la réclamation et l'acquittement.
• oldest_queued_at est l'horodatage de l'élément le plus ancien encore dans la file d'attente, en attente d'être réclamé ou réclamé mais pas encore acquitté, ou null lorsqu'il n'y en a aucun.
• workers_polling est le nombre de workers qui ont interrogé la file au cours des 30 dernières secondes. Utilisez cette valeur pour les alertes de vivacité.

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

Arrêter une session proprement

Utilisez work.stop pour demander au worker qui gère une session spécifique de l'arrêter. Par défaut, l'élément de travail passe à stopping : le worker le remarque lors de son prochain battement de cœur de bail, annule l'appel d'outil en cours de la session et confirme l'arrêt, moment auquel l'élément de travail devient stopped. Transmettez force: true dans le corps de la requête (avec la CLI, transmettez --force) pour marquer l'élément de travail comme stopped immédiatement au lieu d'attendre la confirmation du worker.

Comme ces appels s'exécutent depuis vos outils d'exploitation plutôt que depuis l'hôte du worker, ANTHROPIC_WORK_ID n'est pas défini automatiquement. Définissez-le sur l'ID de l'élément de travail cible avant d'exécuter les exemples suivants. Pour trouver l'ID d'un élément de travail, listez les éléments de travail de l'environnement via les points de terminaison Environments Work.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)

Étapes suivantes