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. Pour donner à l'agent des outils provenant d'un serveur MCP à l'intérieur de votre réseau sans exécuter de tunnel, vous pouvez également encapsuler le serveur en tant qu'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 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 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 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 celui 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 endpoints 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.
• 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és par Anthropic, de sorte que les livrables finaux atterrissent là où l'agent les écrit dans le système de fichiers de votre sandbox, généralement sous le répertoire de travail.



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 sur 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 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. 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 d'attente 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 endpoint webhook qu'Anthropic peut atteindre (consultez Webhooks pour la configuration de l'endpoint 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, récupérant 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 d'attente de travail pour vous et vous donne chaque session réclamée. Utilisez-le 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 dans le processus.
  • 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 ; omettre le 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 délai en 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. À utiliser lorsque vous avez déjà réclamé le travail et 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 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 d'attente 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 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. 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 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 de la CLI, et Helpers du SDK pour les options des helpers du SDK.



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 atteint les services internes, les identifiants et la sortie réseau que vous avez configurés pour le 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 en dehors de l'hôte du worker.

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 une raison d'arrêt requires_action jusqu'à ce que quelque chose publie son résultat ; consultez Gestion des appels d'outils personnalisés pour le flux d'événements.



Encapsuler un serveur MCP en tant qu'outils personnalisés

Le connecteur MCP se connecte aux serveurs MCP depuis le côté d'Anthropic, donc un serveur doit exposer un endpoint 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 en tant qu'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 renvoie. À 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 helpers 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).

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

• Les outils sont déclarés, pas 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 Mise à jour de 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 est requise (1 à 4 096 caractères) ; et le tableau tools d'un agent accepte au plus 128 entrées (chaque outil encapsulé est une entrée, et l'ensemble d'outils intégré en est une de plus). L'API rejette une déclaration qui réutilise un nom d'outil, nomme un outil personnalisé d'après un outil d'agent intégré tel que bash ou read, ou utilise le préfixe réservé mcp__. Les helpers MCP conservent les noms et descriptions du serveur, donc renommez ou raccourcissez si nécessaire. Lorsque deux serveurs exposent le même nom d'outil, définissez vous-même le wrapper sous un nom préfixé et faites-le appeler le nom d'outil original 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 n'importe où dans l'input_schema d'un outil personnalisé, donc intégrez en ligne les schémas que des générateurs comme pydantic factorisent dans $defs. Elle rejette également oneOf, anyOf et allOf au niveau supérieur, ainsi que les noms de propriétés en dehors des lettres, chiffres, traits de soulignement, points et tirets (1 à 64 caractères).
• Les échecs d'outils apparaissent comme des résultats d'outils 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 de résultat d'outil, comme les blocs audio et les liens de ressources, apparaît également comme une erreur. Définissez un timeout 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 d'erreur que lorsque le timeout de requête par défaut du SDK MCP TypeScript se déclenche (environ une minute) ou lorsque le garde-fou propre au worker se déclenche : 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 d'erreur.
• Encapsulez des serveurs que vous opérez ou en qui vous avez 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 avez l'intention de faire utiliser à l'agent.
• Les politiques de permissions ne s'appliquent pas aux outils personnalisés. Les politiques de permissions 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, donc placez 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'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 endpoints directement.



Lire la profondeur de la file d'attente

work.stats retourne 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 helpers du worker acquittent chaque élément avant de le traiter, donc cette valeur reste proche de zéro en fonctionnement normal ; une valeur non nulle soutenue 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, 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 à l'état stopping : le worker le remarque lors de son prochain heartbeat 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. Passez force: true dans le corps de la requête (avec la CLI, passez --force) pour marquer immédiatement l'élément de travail comme stopped 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 Work des Environments.

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