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.
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, choisissezcws-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 decws-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 :
/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 :
cws-agent run ne pilote pas les conversations Managed Agents.
Configurer avec le SDK Sandboxes
Cette méthode alternative lance le workerant 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 :- Python
- TypeScript
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 CLIant 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.
- Python
- TypeScript
start_claude_worker.py
- Python
- TypeScript
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é :
- Python
- TypeScript
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 :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.
- Python
- TypeScript
Importez Passez
AuthHeaders et définissez auth avant de créer la sandbox :auth=auth à Sandbox.run(). Dans les exemples Python suivants, incluez cette configuration et passez également auth=auth à chaque appel de Sandbox.from_id().[SECRET-NAME] par le nom du secret de l’équipe :
- Python
- TypeScript
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().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 :- Python
- TypeScript
[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 :
- Python
- TypeScript
verify_claude_worker.py
- Python
- TypeScript
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é :
- cws-agent
- SDK Sandboxes
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 :- cws-agent
- SDK Sandboxes
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.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.