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
| 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 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. |
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 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. |
<workdir>/skills/<name>/ | Les skills téléchargées de l'agent. |
/mnt/memory/<store>/ | Un répertoire par magasin de mémoire attaché, au mount_path du magasin (par exemple, /mnt/memory/user-preferences/). Le worker crée ces répertoires lorsqu'il réclame la session et les supprime lorsque la session se termine. |
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 | Gère l'interrogation, la configuration et l'exécution 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 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() | 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() | S'exécute indéfiniment, en prenant en charge les sessions à mesure qu'elles arrivent. |
handle_item() | 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, ou laissez-la lire les variables ANTHROPIC_*. |
| Option | Description |
|---|---|
tools | 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 | 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. |
memory_sync_deletions | Indique 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 :
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])Work poller
| Option | Description |
|---|---|
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 | 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 None pour une vérification non bloquante. Par défaut, il s'agit d'un long-poll de 999 ms. |
reclaim_older_than_ms | 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 | 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 lorsque ce qui exécute l'élément de travail publie lui-même l'arrêt. C'est le cas de handle_item(), 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.
Tool runner 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 vers /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.
| Option | Description |
|---|---|
allowed_roots | 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 | 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, 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).
Was this page helpful?