Skip to main content
Connectez Claude Managed Agents à un worker exécuté dans un sandbox CoreWeave. Anthropic gère la boucle de l’agent et la conversation, tandis que le worker exécute les outils et renvoie leurs résultats à Anthropic. Cette intégration repose sur un environnement auto-hébergé et se distingue de la CLI Claude Code et de Remote Control. Claude Managed Agents est également en version bêta. Son API requiert l’en-tête bêta managed-agents-2026-04-01, que le SDK Anthropic utilisé dans ce guide ajoute automatiquement. Voir Accès à la version bêta d’Anthropic.

Prérequis

Avant de commencer, vous devez disposer des éléments suivants :
  • Un jeton d’accès à l’API CoreWeave disposant de l’action SANDBOX_USER.
  • Un accès à Claude Managed Agents dans votre workspace Anthropic et une clé API de la Console pour le client qui crée les sessions.
  • Un agent existant configuré avec agent_toolset_20260401. Pour en créer un, suivez le guide de démarrage rapide de Managed Agents d’Anthropic, puis notez son ID.
  • Pour les exemples du SDK, Python 3.11 ou version ultérieure avec uv, ou bien Node.js 22 ou version ultérieure.
Exportez votre jeton d’accès à l’API CoreWeave dans le terminal depuis lequel vous suivez ce guide :

Créer un environnement

Dans la Claude Console, créez un environnement Self-hosted. Ouvrez-le et générez une clé d’environnement. Notez l’ID de l’environnement et conservez la clé en lieu sûr. Consultez la documentation d’Anthropic sur la configuration de l’environnement. La clé d’environnement authentifie les workers auprès de cet environnement. La clé API de la Console permet de créer des sessions depuis votre client. Ne mélangez pas ces deux identifiants d’authentification. Pour la tâche de vérification, utilisez un environnement qui ne contient que le worker créé dans ce guide. Vous évitez ainsi qu’un autre worker ne s’approprie la session de test. Une fois l’environnement prêt, choisissez cws-agent ou le SDK Sandboxes pour démarrer son worker, puis exécutez la tâche de vérification.

Démarrage rapide avec cws-agent

Suivez les instructions d’installation de cws-agent. L’outil configure un volume de snapshots pour enregistrer et restaurer votre Workspace à l’aide de snapshots du système de fichiers. Remplacez [ENVIRONMENT-KEY], [ENVIRONMENT-ID] et [SANDBOX-NAME] par votre clé d’environnement, votre ID d’environnement et un nom de session cws-agent pour la sandbox. Le nom de session doit comporter de 1 à 40 caractères (lettres minuscules, chiffres ou tirets) et commencer par une lettre ou un chiffre :
Launch démarre un worker dans /workspace/claude/0, puis vous rend la main dans votre shell. L’outil transmet la clé d’environnement à la sandbox. Pour afficher le terminal du worker, exécutez :
Détachez la session avec Ctrl-b, puis d. Passez ensuite à Exécuter et vérifier une tâche. Envoyez les tâches via l’API Managed Agents. La commande cws-agent run ne pilote pas les conversations Managed Agents.

Configurer avec le SDK Sandboxes

Cette méthode alternative lance le worker ant d’Anthropic comme processus principal de la sandbox. Elle ne nécessite pas cws-agent et ne configure pas de snapshots. Exécutez les extraits de code Python dans l’environnement virtuel créé dans ce guide. Enregistrez les extraits de code TypeScript dans des fichiers .mts au sein du projet où vous installez le client, puis exécutez-les avec npx tsx [FILENAME].mts.

Configurer les identifiants et installer le client

Dans le terminal où vous exécutez le script, exportez la clé et l’ID de l’environnement indiqués dans la Console :
Utilisez Python 3.11 ou une version ultérieure, ainsi que uv :

Démarrer le worker

Enregistrez le script correspondant à votre langage sous le nom de fichier indiqué. Le script installe la CLI ant dans une image Linux disposant de Bash, démarre un worker et affiche l’ID de la sandbox. Le client lit ANTHROPIC_ENVIRONMENT_KEY dans votre environnement local et transmet sa valeur dans la requête de sandbox afin de définir la variable d’environnement du worker.
start_claude_worker.py
Exécutez le script :
Le script attend la fin du démarrage. En Python, wait() peut également rendre la main si le processus principal est déjà terminé. L’affichage d’un ID de sandbox ne garantit pas que le worker est authentifié ni qu’il interroge la file d’attente. Avant de lancer une tâche, vérifiez le statut du worker et ses journaux récents. Remplacez [SANDBOX-ID] par l’ID affiché :
Le client Python indique également l’état, le code de sortie et le nombre de redémarrages de chaque conteneur. Le client TypeScript n’expose pas encore ces informations. Relancez cette vérification pour récupérer les journaux les plus récents. Ce worker effectue ses interrogations via des connexions HTTPS sortantes et ne nécessite aucun service entrant. Toutes les sessions partagent le même système de fichiers de la sandbox ; cet exemple ne fournit donc pas de nouvelle sandbox par session. Pour ce type d’architecture, consultez le guide d’intégration des sandboxes auto-hébergées d’Anthropic.

Facultatif : utiliser un magasin de secrets

Vous pouvez transmettre une référence de secret Forge au lieu de la valeur de la clé d’environnement. Cette option nécessite l’authentification Forge et un placement sans serveur. Stockez la clé d’environnement dans le Secret Manager de votre équipe Forge, puis exportez les identifiants d’authentification de cette équipe :
Configurez explicitement le SDK avec ces identifiants d’authentification. FORGE_API_KEY et FORGE_TEAM ne sont que des exemples de noms de variables d’environnement : le SDK ne les détecte donc pas automatiquement.
Importez AuthHeaders et définissez auth avant de créer la sandbox :
Passez auth=auth à Sandbox.run(). Dans les exemples Python suivants, incluez cette configuration et passez également auth=auth à chaque appel de Sandbox.from_id().
Remplacez [SECRET-NAME] par le nom du secret de l’équipe :
Importez Secret depuis cwsandbox, supprimez ANTHROPIC_ENVIRONMENT_KEY de environment_variables, puis ajoutez secrets=[Secret(store="wandb", name="[SECRET-NAME]", env_var="ANTHROPIC_ENVIRONMENT_KEY")] à Sandbox.run().
La plateforme résout la référence et définit la variable d’environnement du worker.

Exécuter et vérifier une tâche

Exécutez le client de session sur votre propre machine, quelle que soit la méthode de configuration choisie. Installez le SDK Anthropic correspondant à votre langage :
Remplacez [ANTHROPIC-API-KEY] par votre clé API de la Console, [AGENT-ID] par l’ID de votre agent existant et [ENVIRONMENT-ID] par l’ID de l’environnement connecté à votre worker :
Enregistrez le script de vérification correspondant à votre langage sous le nom de fichier indiqué. Il demande à l’agent d’écrire une valeur unique et non secrète dans son répertoire de travail. L’exécution d’outil auto-hébergée génère des événements d’inactivité temporaires pendant que le worker traite les appels autorisés. Le script patiente pendant ces événements et s’arrête lorsque le tour de conversation se termine ou qu’une autre action est requise. Vérifiez le motif d’arrêt affiché avant de récupérer le fichier.
verify_claude_worker.py
Exécutez-la et examinez les événements :
Si le script s’arrête sur requires_action, examinez les événements d’outil référencés. Les appels avec evaluated_permission: "ask" nécessitent le flux de travail de confirmation d’outil d’Anthropic. Le worker traite les appels autorisés. S’ils restent bloqués, consultez ses journaux. Conservez l’ID de session pour reprendre cette session plutôt que d’en créer une nouvelle. Une fois la tâche terminée, lisez le fichier depuis la sandbox à l’aide de la commande correspondant à votre configuration. Remplacez [SANDBOX-NAME] ou [SANDBOX-ID] par le nom du Workspace ou par l’ID de sandbox affiché :
Pour Python, réactivez si nécessaire l’environnement virtuel dans lequel vous avez installé cwsandbox. Pour TypeScript, enregistrez l’extrait de code du SDK dans un fichier .mts et exécutez-le avec npx tsx. Le contenu du fichier doit correspondre à la valeur affichée par le client. Cela relie l’exécution d’outil de l’agent à cette sandbox CoreWeave précise.

Conserver les résultats et arrêter

Attendez que les tâches actives se terminent, puis copiez hors de la sandbox les résultats dont vous avez besoin. Arrêtez-la ensuite à l’aide de la commande correspondant à votre configuration :
down crée un snapshot du Workspace avant l’arrêt. Si la capture échoue, vérifiez cws-agent status [SANDBOX-NAME] et corrigez le problème avant toute nouvelle tentative. Si vous pouvez abandonner les modifications non enregistrées, utilisez down --no-snapshot.
L’expiration de la durée de vie de la sandbox peut interrompre une tâche en cours. Mettre fin à une session Managed Agents n’arrête pas ce worker toujours actif. Par ailleurs, l’arrêt ou la restauration de la sandbox ne supprime ni ne restaure l’historique de conversation d’Anthropic.

Dépannage

Effectuez les vérifications suivantes pour résoudre les problèmes courants :
  • Si la session attend un worker, vérifiez l’ID de l’environnement et les journaux du worker, et assurez-vous qu’aucune autre tâche n’occupe déjà le worker.
  • Si le worker ne parvient pas à s’authentifier, vérifiez sa clé d’environnement. La clé API de la Console utilisée par le client de session est un identifiant d’authentification distinct.
  • S’il manque un outil, compilez une image avec les dépendances requises. L’exemple utilise une image Python et n’installe aucune chaîne d’outils propre au projet.
Les entrées et sorties des outils sont transmises à Anthropic, même si l’exécution a lieu sur CoreWeave. Managed Agents n’est éligible ni à la Zero Data Retention ni à la couverture par un HIPAA Business Associate Agreement. Consultez l’éligibilité d’Anthropic en matière de rétention des données. Consultez le modèle de sécurité des environnements auto-hébergés pour en savoir plus sur la gestion des données et les autorisations des workers.
Dernière modification le 15 octobre 2026