Sandboxes auto-hébergés

Par défaut, Managed Agents exécute les outils et le code à l'intérieur de sandboxes cloud gérés par Anthropic. Les « self-hosted sandboxes » (sandboxes auto-hébergés) conservent l'orchestration du côté d'Anthropic mais déplacent l'exécution des outils dans une infrastructure que vous contrôlez, de sorte que le code de l'agent, le système de fichiers et la sortie réseau 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. Consultez le modèle de sécurité pour la frontière complète du flux de données.



En quoi cela diffère des environnements cloud

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

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



Quand combiner avec les tunnels MCP

L'auto-hébergement contrôle où le code de l'agent s'exécute. Les tunnels MCP contrôlent comment Anthropic atteint les serveurs MCP dans votre réseau. Ils 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 voulez que l'exécution et l'accès aux outils restent à l'intérieur de votre périmètre.



Worker d'environnement

Un « environment worker » (worker d'environnement) est un processus que vous exécutez sur votre propre infrastructure. Il reçoit les requêtes d'exécution d'outils d'Anthropic et les exécute localement. L'environnement self_hosted agit comme une file de travail : lorsqu'une session lui est assignée, Anthropic met la session en file d'attente en tant qu'élément de travail. Votre worker réclame les éléments de travail de cette file, lance 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 donnent à l'agent une expertise spécifique à 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 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 Helpers 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 du 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és 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 de skills.
• /mnt/session/outputs : le harnais du worker indique à Claude d'écrire les livrables finaux ici. En mode sandbox, montez un répertoire hôte à ce chemin pour récupérer les sorties après la fin de la session. En mode in-process, les outils de fichiers du worker écrivent plutôt sous le répertoire de travail, donc ce chemin ne s'applique pas.



Avant de commencer

Vous avez besoin de :

• Un agent existant. Si vous n'en avez pas, complétez d'abord le Démarrage rapide et notez son ID d'agent.
• Un hôte Linux avec /bin/bash à ce chemin exact. L'outil bash du worker l'invoque directement, sans consulter PATH. Le SDK TypeScript nécessite en plus 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 pas d'exigences binaires supplémentaires.
• La CLI ant ou un SDK Anthropic (Python, TypeScript ou Go) sur l'hôte du worker.
• Deux identifiants : une clé d'environnement (générée dans la Console dans les étapes qui suivent) authentifie le worker auprès de sa file ; votre clé API Claude crée des 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.



Exécuter un worker

Choisissez toujours actif pour la configuration la plus simple : un processus de longue durée interroge la file en continu et n'a besoin que d'HTTPS sortant. Choisissez déclenché par webhook pour éviter d'exécuter un poller 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 de signature).



Helpers du SDK

Le SDK fournit trois helpers à différents niveaux de contrôle. EnvironmentWorker couvre la plupart des cas d'usage ; descendez aux helpers 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é et 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.
• work.poller() : interroge la file de travail pour vous et vous donne chaque session réclamée. Utilisez ceci lorsque vous voulez décider de ce qui se passe pour chaque session, par exemple lancer un sandbox plutôt que d'exécuter les outils in-process.
  • drain : indique s'il faut arrêter l'interrogation une fois la file vide plutôt que d'attendre de nouveaux travaux.
  • block_ms : combien de temps attendre l'arrivée de travail avant de retourner, en millisecondes. Doit être compris entre 1 et 999 (attente par interrogation ; le helper ré-interroge automatiquement). Passez null (None en Python, param.Null[int64]() en Go) pour une vérification non bloquante ; l'omission du paramètre utilise le long-poll par défaut de 999 ms.
  • reclaim_older_than_ms : re-réclame les éléments de travail qui ont été réclamés mais jamais acquittés dans ce nombre de millisecondes.
  • auto_stop : 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. Le poller Go n'a pas d'option de désactivation et publie toujours le signal d'arrêt, donc bloquez dans le corps de la boucle jusqu'à ce que la session se termine plutôt que de vous détacher.
• client.beta.sessions.events.tool_runner() : exécute les appels d'outils pour une seule session, étant donné l'ID de session et une liste d'outils. Utilisez-le lorsque vous avez déjà réclamé le travail et que vous n'avez besoin que de la couche d'exécution.

Utilisez directement le poller de travail lorsque vous voulez lancer votre propre processus par session, par exemple démarrer un sandbox pour chaque session réclamée :

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Remplacez par votre propre lanceur de sandbox par session. Transmettez
    # ANTHROPIC_ENVIRONMENT_KEY dans la sandbox lancée, jamais
    # votre clé API.
    print(f"claimed session {work.data.id}")


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

AgentToolContext est le contexte d'exécution pour les 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. beta_agent_toolset_20260401(env) prend un AgentToolContext et retourne les implémentations d'outils standard (bash, read, write, edit, glob, grep).

Avec EnvironmentWorker : les deux sont gérés automatiquement. Passez une factory 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 (pas la clé d'environnement), confirmez que workers_polling est au moins égal à 1 :

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

Si workers_polling reste à 0, le worker n'atteint pas la file : 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 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 plutôt que d'échouer.

Anthropic ne monte pas de fichiers ni de dépôts GitHub dans les sandboxes auto-hébergés. Pour rendre disponibles des fichiers spécifiques à une session, passez des références de fichiers (comme un chemin S3 ou un SHA de commit) dans le champ metadata de la session. Votre script de lancement ou votre gestionnaire --on-work lit ces métadonnées depuis l'élément de travail réclamé (le poller de la CLI transmet le JSON de l'élément de travail au stdin du script, et les gestionnaires du SDK peuvent le lire via les points de terminaison Environments Work) et met en place 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 Helpers du SDK pour les options des helpers du SDK.



Surveillance et opérations

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



Lire la profondeur de la file

work.stats retourne l'état de la file 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 qu'un worker a réclamés et qu'il traite actuellement.
• oldest_queued_at est l'horodatage de l'élément le plus ancien encore en file d'attente ou en cours de traitement, 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 ceci 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 gérant une session spécifique de l'arrêter proprement. Le worker termine tout appel d'outil en cours, publie un statut final et libère la session. Passez force: true dans le corps de la requête (avec la CLI, passez --force) pour interrompre immédiatement au lieu d'attendre la fin de l'appel d'outil en cours.

Comme ces appels s'exécutent depuis vos outils d'opérations 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)



Prochaines étapes