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 sandboxes auto-hébergées 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, le système de fichiers et le 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 auquel il peut accéder 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 prochaine action. Consultez le modèle de sécurité pour connaître la délimitation 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 votre périmètre réseau, accéder à 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 HIPAA BAA, 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. Ces deux mécanismes 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.



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 d'attente de travail : lorsqu'une session lui est assignée, Anthropic place la session dans la file en tant qu'é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, 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 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 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 prend uniquement en charge le modèle toujours actif ; le SDK prend en charge les deux modèles (toujours actif et déclenché par webhook). Les deux sont configurables : consultez Worker auto-hébergé dans la référence pour les options CLI, et Helpers SDK sur cette page pour les options SDK. Pour plus de contrôle, appelez directement les endpoints 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 de skills.
• /mnt/session/outputs : le harnais du worker indique à Claude d'écrire les livrables finaux à cet emplacement. 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 Quickstart et notez son ID d'agent.
• Un hôte Linux avec /bin/bash à ce chemin exact. Le SDK TypeScript nécessite en plus unzip, tar et Node.js 22 ou version ultérieure ; le SDK Python utilise la bibliothèque standard pour l'extraction d'archives et n'a aucune exigence binaire supplémentaire. Ces dépendances sont résolues à des chemins fixes et ne respectent pas les surcharges de PATH.
• 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 les étapes qui suivent) authentifie le worker auprès de sa file d'attente ; 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.



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 ne nécessite que du HTTPS sortant. Choisissez déclenché par webhook pour éviter d'exécuter un poller inactif ; cela nécessite un endpoint webhook qu'Anthropic peut atteindre (consultez Webhooks pour la configuration de l'endpoint et la vérification de signature).



Helpers SDK

Le SDK fournit trois helpers à différents niveaux de contrôle. EnvironmentWorker couvre la plupart des cas d'usage ; descendez vers les 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, récupérant les sessions au fur et à mesure de leur arrivée. Se termine proprement sur SIGTERM.
  • .handle_item() : récupère une session en attente, la traite et se termine.
• work.poller() : interroge la file de travail pour vous et vous remet chaque session réclamée. Utilisez-le lorsque vous voulez décider ce qui se passe pour chaque session, par exemple lancer une sandbox plutôt qu'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 éléments.
  • block_ms : durée d'attente de 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 ; omettre le paramètre utilise le long-poll par défaut de 999 ms.
  • reclaim_older_than_ms : réclame à nouveau les éléments de travail loués à un worker qui a cessé de répondre.
  • auto_stop : indique s'il faut envoyer un signal d'arrêt sur l'élément de travail après la sortie de l'itérateur. Le poller Go n'a pas d'option de désactivation et envoie toujours le signal d'arrêt ; bloquez donc 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. À 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 créant une 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 au sandbox lancé, 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 télécharge optionnellement les skills de la session lorsqu'il est utilisé comme gestionnaire de contexte. 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 comme 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é, en utilisant votre clé API Claude (et non 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 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. 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ées. Pour rendre disponibles des fichiers spécifiques à la 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é (via les endpoints Environments Work) et place les fichiers dans le répertoire de travail avant que l'exécution des outils ne commence.

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 CLI, et Helpers SDK pour les options des helpers 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 de worker, vous n'appelez donc pas ces endpoints 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 de réclamation. 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 traite actuellement.
• oldest_queued_at est l'horodatage de l'élément le plus ancien dans la file, ou null si la file est vide.
• workers_polling est le nombre de workers ayant interrogé la file au cours des 30 dernières secondes. Utilisez cette valeur pour les alertes de disponibilité.

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

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