Claude Platform Docs
Managed AgentsSandboxes auto-hébergées

Référence des workers auto-hébergés

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.

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 et Déployer des workers auto-hébergés.

Commandes et options de la CLI

CommandeDescription
ant beta:worker pollRé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 runTraite une session réclamée puis se termine. Utilisez-la comme point d’entrée d’une sandbox par session.
OptionDescription
--environment-idL’environnement à interroger pour obtenir du travail. Lit également ANTHROPIC_ENVIRONMENT_ID.
--environment-keyAuthentifie le worker auprès de cet environnement. Lit également ANTHROPIC_ENVIRONMENT_KEY.
--workdirRépertoire dans lequel le worker télécharge les skills et où les outils lisent et écrivent des fichiers. La valeur par défaut est . (le répertoire courant). Le répertoire doit exister avant le démarrage du worker.
--on-workScript à 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-idleDurée pendant laquelle le worker attend lorsqu’une session est inactive avant que ant beta:worker run ne se termine ou que ant beta:worker poll ne passe à l’élément de travail suivant. Le temps d’inactivité avec une raison d’arrêt requires_action n’est pas comptabilisé. La valeur par défaut est 60s. Définissez-la sur 0 pour désactiver le délai d’expiration. Avec un script --on-work, ant beta:worker poll ignore cette option. Transmettez-la plutôt à la commande ant beta:worker run que votre script lance.
--log-formatFormat de sortie des journaux. Utilisez json pour l’ingestion de journaux structurés. La valeur par défaut est text.

Variables d’environnement

VariableDescriptionDéfinie par
ANTHROPIC_ENVIRONMENT_IDL’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_KEYAuthentifie 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_IDLa session que représente un élément de travail réclamé.Le poller, pour le script --on-work.
ANTHROPIC_WORK_IDL’élément de travail réclamé.Le poller, pour le script --on-work.
ANTHROPIC_WORK_SECRETLe secret de l’élément de travail pour sa session.Vous. Le poller ne la définit pas. Consultez Transmettre le secret de l’élément de travail.
ANTHROPIC_BASE_URLRemplace le point de terminaison de l’API par défaut. Facultative.Vous, sur l’hôte du worker.
ANTHROPIC_WEBHOOK_SIGNING_KEYVérifie les charges utiles des webhooks entrants.Vous, sur un hôte de gestionnaire de webhooks.

Exigences de l’hôte

WorkerExigence
Tous les workersUn hôte Linux ou macOS avec /bin/bash à ce chemin exact. L’outil bash du worker l’exécute directement, sans consulter PATH. Sur macOS, il s’agit du Bash 3.2 du système.
SDK TypeScriptunzip et tar dans le PATH, et Node.js 22 ou version ultérieure.
SDK Python et GoAucun binaire supplémentaire. Ces SDK utilisent leurs bibliothèques standard pour l’extraction des archives.

Les magasins de mémoire ajoutent leurs propres exigences.

Sur macOS, le volume racine est en lecture seule, de sorte que mkdir ne peut pas créer /workspace. Définissez le répertoire de travail du worker sur un répertoire dans lequel vous pouvez écrire, par exemple un répertoire workspace dans votre répertoire personnel. Pour utiliser des magasins de mémoire sur macOS, commencez par préparer l’hôte macOS.

Système de fichiers de la sandbox

CheminContenu
/workspaceLe répertoire de travail utilisé dans les exemples des pages sur les sandboxes auto-hébergées. Ce n’est pas la valeur par défaut du worker : le worker utilise le répertoire courant, sauf si vous définissez --workdir ou workdir. Les sandboxes cloud d’Anthropic conservent les skills et les dépôts dans /workspace. 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.
<workdir>/skills/<name>/Les skills téléchargées de l’agent.
/mnt/memory/<store>/Une copie locale de chaque magasin de mémoire attaché, un répertoire par magasin. L’API renvoie le chemin complet de chaque répertoire dans le champ mount_path de la ressource de magasin de mémoire de la session (par exemple, /mnt/memory/user-preferences/).

Le worker crée les répertoires des magasins de mémoire lorsqu’il réclame une session. Il les supprime lorsqu’il en a terminé avec cette session ou lorsque vous arrêtez le worker proprement. Cela ne supprime que les copies locales, et les mémoires restent dans le magasin.

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 téléchargez vous-même les skills, définissez vous-même leurs permissions d’exécution.

Quand le worker en a terminé avec une session

Le worker en a terminé avec une session dans l’un des cas suivants :

  • La session se termine.
  • Vous arrêtez l’élément de travail de la session.
  • La session reste inactive pendant la durée de la limite d’inactivité du worker. La session elle-même reste ouverte. Lorsque vous lui envoyez ensuite un nouvel événement, tel qu’un message utilisateur, le même worker ou un autre la réclame. Ce worker télécharge à nouveau les magasins.

La limite d’inactivité est de 60 secondes par défaut. Pour la modifier, utilisez --max-idle pour le worker de la CLI ant ou max_idle pour EnvironmentWorker. Le chart Helm cma-sandboxes démarre plutôt ses workers avec une limite de 30 minutes. Pour modifier cette limite, modifiez le paramètre sandbox.idleTimeout du chart.

Livrables finaux

Les sandboxes auto-hébergées n’ont pas de répertoire /mnt/session/outputs. Dans les sandboxes cloud d’Anthropic, l’invite système de la session indique à l’agent d’y copier les livrables finaux. Dans les environnements auto-hébergés, l’invite système omet cette instruction. Les livrables finaux restent là où l’agent les écrit, généralement sous le répertoire de travail, et le worker ne les téléverse pas.

Pour rassembler les livrables finaux en un seul endroit, indiquez le chemin complet d’un répertoire dans l’invite système de votre agent. Choisissez un répertoire dans lequel les outils de fichiers du worker peuvent écrire :

  • À l’intérieur du répertoire de travail : par exemple, /workspace/outputs si le répertoire de travail est /workspace.
  • N’importe où ailleurs, avec un worker du SDK uniquement : ajoutez le répertoire à allowed_roots. Consultez AgentToolContext et l’ensemble d’outils de l’agent.

Helpers du SDK

Les SDK Python, TypeScript et Go fournissent trois helpers offrant différents niveaux de contrôle :

HelperCe qu’il faitQuand l’utiliser
EnvironmentWorkerGère l’interrogation, la configuration et l’exécution des outils de bout en bout.Dans la plupart des cas.
work.poller()Interroge la file d’attente de travail et vous fournit chaque session réclamée.Vous déterminez comment traiter chaque session, par exemple en lançant une sandbox plutôt qu’en exécutant les outils dans le processus.
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.Vous avez déjà réclamé le travail et n’avez besoin que d’exécuter les outils.

EnvironmentWorker

MéthodeDescription
run()S’exécute indéfiniment, en prenant en charge les sessions à mesure qu’elles arrivent.
handle_item()Traite un élément de travail déjà réclamé par un poller. Le poller peut être ant beta:worker poll --on-work ou votre propre code. La méthode retourne lorsque le worker en a terminé avec la session de l’élément. Vous pouvez transmettre work_id, session_id, environment_id et work_secret. Pour chacun de ceux que vous omettez, la méthode lit la variable ANTHROPIC_* correspondante.
OptionDescription
toolsUne 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.
max_idleDurée pendant laquelle le worker attend lorsqu’une session est inactive avant d’en avoir terminé avec la session. Le temps d’inactivité avec une raison d’arrêt requires_action n’est pas comptabilisé. La valeur par défaut est de 60 secondes. Pour attendre 5 minutes, définissez-la sur 300. Pour désactiver la limite, définissez-la sur None.
memory_sync_intervalLe délai le plus court entre deux synchronisations des magasins de mémoire attachés pendant l’exécution de la session. Le worker vérifie l’intervalle après chaque appel à un outil qui s’exécute dans votre sandbox, et non selon un minuteur. La valeur par défaut est de 15 secondes. Consultez Intervalle de synchronisation.
memory_sync_deletionsIndique si les fichiers que l’agent supprime localement sont également supprimés du magasin. Consultez Suppressions.

EnvironmentWorker gère automatiquement l’AgentToolContext et l’ensemble d’outils. Transmettez une fabrique tools pour personnaliser la liste d’outils :

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic, beta_async_tool
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_bash_tool


@beta_async_tool
async def get_order_status(order_id: str) -> str:
    """Look up an order in the internal fulfillment system by order ID."""
    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:
        worker = EnvironmentWorker(
            client,
            environment_id=environment_id,
            environment_key=environment_key,
            # Listez chaque outil que l'agent peut appeler. Le worker ne répond à aucun autre outil.
            tools=lambda env: [beta_bash_tool(env), get_order_status],
        )
        task = asyncio.create_task(worker.run())
        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())

Work poller

OptionDescription
drainIndique s’il faut arrêter l’interrogation une fois la file d’attente vide plutôt que d’attendre de nouveaux travaux.
block_msDuré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 None pour une vérification non bloquante. Utilise par défaut un long-poll de 999 ms.
reclaim_older_than_msRéclame à nouveau les éléments de travail qui ont été réclamés mais jamais acquittés dans ce nombre de millisecondes.
auto_stopIndique si le poller publie un signal d’arrêt pour chaque élément de travail une fois que le corps de votre boucle en a terminé avec lui. La valeur par défaut est True. Définissez-la sur False dans les deux cas qui suivent ce tableau.

Définissez auto_stop sur False dans deux cas :

  1. Votre boucle appelle handle_item(), qui publie lui-même l’arrêt.
  2. Votre boucle lance une sandbox pour l’élément et passe à la suite. Le worker de cette sandbox doit publier l’arrêt lorsque le travail de la session se termine, comme le font ant beta:worker run et handle_item().

Pour un exemple complet, consultez Lancer des sandboxes depuis le poller du SDK.

Exécuteur d’outils de session

client.beta.sessions.events.tool_runner() prend une liste d’outils via tools. 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 dans /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

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.

OptionDescription
allowed_rootsRépertoires, en plus du répertoire de travail, auxquels les outils de fichiers (read, write, edit, glob, grep) peuvent accéder.
read_only_rootsRé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, et les répertoires des magasins attachés avec access: "read_only" à read_only_roots.

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) prend un AgentToolContext et renvoie les implémentations d’outils standard (bash, read, write, edit, glob, grep).

Cette page vous a-t-elle été utile ?