--- title: Référence des workers auto-hébergés url: https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-reference description: "Référence pour les workers de sandbox auto-hébergés : options de la CLI ant, variables d'environnement, exigences de l'hôte, chemins du système de fichiers et options des helpers du SDK." featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Cette page documente les workers préconstruits qui desservent un environnement `self_hosted`. Pour des guides orientés tâches, commencez par [Sandboxes auto-hébergées](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes) et [Déployer des workers auto-hébergés](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-workers). ## Commandes et options de la CLI | Commande | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ant beta:worker poll` | Réclame des éléments de travail dans la file d'attente de l'environnement et exécute chaque session dans le processus. Avec `--on-work`, appelle plutôt votre script pour chaque élément de travail. | | `ant beta:worker run` | Traite une session réclamée puis se termine. Utilisez-la comme point d'entrée d'une sandbox par session. | | Option | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--environment-id` | L'environnement à interroger pour obtenir du travail. Lit également `ANTHROPIC_ENVIRONMENT_ID`. | | `--environment-key` | Authentifie le worker auprès de cet environnement. Lit également `ANTHROPIC_ENVIRONMENT_KEY`. | | `--workdir` | Répertoire dans lequel les skills sont téléchargées et où les outils lisent et écrivent des fichiers. La valeur par défaut est `.` (le répertoire courant). | | `--on-work` | Script à appeler pour chaque élément de travail réclamé au lieu d'exécuter les outils dans le processus. Reçoit les détails de la session sous forme de variables d'environnement et l'élément de travail au format JSON sur l'entrée standard. | | `--max-idle` | Durée d'attente après que la session est devenue inactive avec une [raison d'arrêt](https://platform.claude.com/docs/fr/build-with-claude/handling-stop-reasons) `end_turn` avant l'arrêt. La valeur par défaut est `60s`. | | `--log-format` | Format de sortie des journaux. Utilisez `json` pour l'ingestion de journaux structurés. La valeur par défaut est `text`. | ## Variables d'environnement | Variable | Description | Définie par | | ------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ANTHROPIC_ENVIRONMENT_ID` | L'environnement dont le worker dessert la file d'attente. | Vous, sur l'hôte du worker. Le poller la transmet au script `--on-work`. | | `ANTHROPIC_ENVIRONMENT_KEY` | Authentifie le worker auprès de sa file d'attente. | Vous, sur l'hôte du worker. Le poller la transmet au script `--on-work`. | | `ANTHROPIC_SESSION_ID` | La session que représente un élément de travail réclamé. | Le poller, pour le script `--on-work`. | | `ANTHROPIC_WORK_ID` | L'élément de travail réclamé. | Le poller, pour le script `--on-work`. | | `ANTHROPIC_WORK_SECRET` | Le secret par session de l'élément de travail. | Vous. Le poller ne la définit pas. Consultez [Transmettre le secret de l'élément de travail](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). | | `ANTHROPIC_BASE_URL` | Remplace le point de terminaison de l'API par défaut. Facultative. | Vous, sur l'hôte du worker. | | `ANTHROPIC_WEBHOOK_SIGNING_KEY` | Vérifie les charges utiles des webhooks entrants. | Vous, sur un hôte de gestionnaire de webhooks. | ## Exigences de l'hôte | Worker | Exigence | | ---------------- | ---------------------------------------------------------------------------------------------------------------------- | | Tous les workers | Un hôte Linux avec `/bin/bash` à ce chemin exact. L'outil bash du worker l'invoque directement, sans consulter `PATH`. | | SDK TypeScript | `unzip` et `tar` dans le `PATH`, et Node.js 22 ou version ultérieure. | | SDK Python et Go | Aucun binaire supplémentaire. Ces SDK utilisent leurs bibliothèques standard pour l'extraction des archives. | Les [magasins de mémoire](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#requirements) ajoutent leurs propres exigences. ## Système de fichiers de la sandbox | Chemin | Contenu | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/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. 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. | | `/skills//` | Les skills téléchargées de l'agent. | | `/mnt/memory//` | Un répertoire par magasin de mémoire attaché, au `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) du magasin (par exemple, `/mnt/memory/user-preferences/`). Le worker crée ces répertoires lorsqu'il réclame la session et les supprime à la fin de la session. | Dans les environnements auto-hébergés, l'invite système de la session omet l'instruction `/mnt/session/outputs` utilisée dans les sandboxes gérées par Anthropic. Les livrables finaux se trouvent là où l'agent les écrit dans le système de fichiers de votre sandbox, généralement sous le répertoire de travail. Les skills peuvent inclure des exécutables que l'agent peut lancer directement. Les workers de la CLI et du SDK préservent les permissions d'exécution enregistrées dans le bundle de la skill lors de son extraction. Si vous implémentez manuellement le téléchargement des skills, il vous incombe de définir les permissions d'exécution. ## Helpers du SDK Les SDK Python, TypeScript et Go fournissent trois helpers offrant différents niveaux de contrôle : | Helper | Ce qu'il fait | Quand l'utiliser | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | [`EnvironmentWorker`](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-reference#environment-worker) | Gère l'interrogation, la configuration et l'exécution de bout en bout. | Dans la plupart des cas. | | [`work.poller()` (go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-reference#work-poller) | Interroge la file d'attente de travail et vous fournit chaque session réclamée. | Vous déterminez ce qui se passe pour chaque session, par exemple lancer une sandbox plutôt qu'exécuter les outils dans le processus. | | [`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-reference#session-tool-runner) | Exécute les appels d'outils pour une seule session, à partir de l'ID de session et d'une liste d'outils. | Vous avez déjà réclamé le travail et n'avez besoin que de la couche d'exécution. | ### EnvironmentWorker | Méthode | Description | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `run()` (go: `Run()`) | S'exécute indéfiniment, en prenant en charge les sessions à mesure qu'elles arrivent. | | `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | Traite un seul élément de travail réclamé puis retourne. Transmettez explicitement les identifiants du travail, de la session et de l'environnement ainsi que le `work_secret` (typescript: `workSecret`; go: `WorkSecret`), ou laissez-la lire les [variables `ANTHROPIC_*`](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-reference#environment-variables). | | Option | Description | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools` (go: `ToolsFunc`) | Une fabrique qui reçoit l'`AgentToolContext` de la session et renvoie la liste d'outils. Par défaut, il s'agit de l'ensemble d'outils standard de l'agent. | | `memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) | Fréquence à laquelle les magasins de mémoire attachés se synchronisent avec le serveur pendant l'exécution de la session. Consultez [Intervalle de synchronisation](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#sync-interval). | | `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) | Indique si les fichiers que l'agent supprime localement sont également supprimés du magasin. Consultez [Suppressions](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#deletions). | `EnvironmentWorker` gère automatiquement l'`AgentToolContext` et l'ensemble d'outils. Transmettez une fabrique `tools` (go: `ToolsFunc`) pour personnaliser la liste d'outils : ```python Python EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool]) ``` ```typescript TypeScript new EnvironmentWorker({ client, environmentId, environmentKey, tools: (ctx) => [betaBashTool(ctx), myCustomTool] }); ``` Le SDK C# ne dispose pas d'`EnvironmentWorker`. Pour répondre aux appels d'outils personnalisés depuis votre propre code, envoyez chaque résultat sur le flux d'événements de la session, comme dans [Renvoyer un résultat d'outil personnalisé](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming#return-a-custom-tool-result). ```go Go worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool { return []anthropic.BetaTool{agenttoolset.BetaBashTool(env), myCustomTool} }, }) ``` Le SDK Java ne dispose pas d'`EnvironmentWorker`. Pour répondre aux appels d'outils personnalisés depuis votre propre code, envoyez chaque résultat sur le flux d'événements de la session, comme dans [Renvoyer un résultat d'outil personnalisé](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming#return-a-custom-tool-result). Le SDK PHP ne dispose pas d'`EnvironmentWorker`. Pour répondre aux appels d'outils personnalisés depuis votre propre code, envoyez chaque résultat sur le flux d'événements de la session, comme dans [Renvoyer un résultat d'outil personnalisé](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming#return-a-custom-tool-result). Le SDK Ruby ne dispose pas d'`EnvironmentWorker`. Pour répondre aux appels d'outils personnalisés depuis votre propre code, envoyez chaque résultat sur le flux d'événements de la session, comme dans [Renvoyer un résultat d'outil personnalisé](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming#return-a-custom-tool-result). ### Work poller | Option | Description | | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `drain` (go: `Drain`) | Indique s'il faut arrêter l'interrogation une fois la file d'attente vide plutôt que d'attendre de nouveaux travaux. | | `block_ms` (typescript: `blockMs`; go: `BlockMs`) | Durée pendant laquelle chaque interrogation attend l'arrivée de travail avant de retourner, en millisecondes. Doit être comprise entre 1 et 999 ; le helper relance automatiquement l'interrogation. Transmettez `null` (python: `None`; go: `param.Null[int64]()`) pour une vérification non bloquante. Par défaut, il s'agit d'un long-poll de 999 ms. | | `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | Réclame à nouveau les éléments de travail qui ont été réclamés mais jamais acquittés dans ce nombre de millisecondes. | | `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | 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éfinissez-la sur `false` (python: `False`; go: `param.NewOpt(false)`) lorsque ce qui exécute l'élément de travail publie lui-même l'arrêt. C'est le cas de `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`), ainsi que d'une sandbox que vous lancez et qui est responsable de l'appel d'arrêt. | Pour un exemple complet, consultez [Lancer des sandboxes depuis le poller du SDK](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-workers#launch-sandboxes-from-the-sdk-poller). ### Tool runner de session `client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`) prend une liste d'outils via `tools` (go: `Tools`). Pour construire cette liste, configurez vous-même `AgentToolContext` et appelez `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`) : ```python Python 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// tools = beta_agent_toolset_20260401(env) ``` ```typescript TypeScript import { setupSkills, betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node"; const ctx = { workdir: "/workspace", client, sessionId: work.data.id }; await setupSkills(ctx); const tools = betaAgentToolset20260401(ctx); ``` Le SDK C# ne dispose pas d'`AgentToolContext`. ```go Go env := &agenttoolset.AgentToolContext{Workdir: "/workspace"} if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil { panic(err) } // skills téléchargées vers /workspace/skills// tools := agenttoolset.BetaAgentToolset20260401(env) ``` Le SDK Java ne dispose pas d'`AgentToolContext`. Le SDK PHP ne dispose pas d'`AgentToolContext`. Le SDK Ruby ne dispose pas d'`AgentToolContext`. ### AgentToolContext et l'ensemble d'outils de l'agent `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. | Option | Description | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`) | Répertoires, en plus du répertoire de travail, auxquels les outils de fichiers (`read`, `write`, `edit`, `glob`, `grep`) peuvent accéder. | | `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`) | Répertoires sous lesquels `write` et `edit` refusent les chemins. | `EnvironmentWorker` ajoute lui-même les répertoires des magasins de mémoire de la session à `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`), et les répertoires des magasins attachés avec `access: "read_only"` à `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`). Ce confinement est un garde-fou pour les outils de fichiers uniquement, et non une sandbox. Il ne restreint pas `bash`. `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`) prend un `AgentToolContext` et renvoie les implémentations d'outils standard (`bash`, `read`, `write`, `edit`, `glob`, `grep`).