> ## Documentation Index > Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt > Use this file to discover all available pages before exploring further. # Utiliser CoreWeave Sandboxes avec Claude Managed Agents > Connectez un worker de sandbox auto-hébergé à Claude Managed Agents et vérifiez l’exécution d’outils sur CoreWeave. Connectez [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) à 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](https://platform.claude.com/docs/en/managed-agents/overview#beta-access).

Prérequis

Avant de commencer, vous devez disposer des éléments suivants : * Un [jeton d’accès à l’API CoreWeave](/fr/products/sandboxes/placement#choose-and-get-credentials) 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](https://platform.claude.com/docs/en/managed-agents/quickstart) d’Anthropic, puis notez son ID. * Pour les exemples du SDK, Python 3.11 ou version ultérieure avec [`uv`](https://docs.astral.sh/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 : ```bash theme={"system"} export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]" ```

Créer un environnement

Dans la [Claude Console](https://platform.claude.com/environments), 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](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#create-a-self-hosted-environment). 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`](https://github.com/coreweave/cws-agent#install). L’outil configure un volume de snapshots pour enregistrer et restaurer votre Workspace à l’aide de [snapshots du système de fichiers](/fr/products/sandboxes/file-system-snapshots#start-a-sandbox-with-a-snapshot-mount). 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 : ```bash theme={"system"} export ANTHROPIC_ENVIRONMENT_KEY="[ENVIRONMENT-KEY]" cws-agent launch [SANDBOX-NAME] --claude-env [ENVIRONMENT-ID] ``` 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 : ```bash theme={"system"} cws-agent connect [SANDBOX-NAME] --cmd 'tmux attach -t claude-0' ``` Détachez la session avec **Ctrl-b**, puis **d**. Passez ensuite à [Exécuter et vérifier une tâche](#run-and-verify-a-task). 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 : ```bash theme={"system"} export ANTHROPIC_ENVIRONMENT_KEY="[ENVIRONMENT-KEY]" export ANTHROPIC_ENVIRONMENT_ID="[ENVIRONMENT-ID]" ``` Utilisez Python 3.11 ou une version ultérieure, ainsi que `uv` : ```bash theme={"system"} uv venv --python 3.11 source .venv/bin/activate uv pip install 'cwsandbox>=1.14.2' ``` Utilisez Node.js 22 ou une version ultérieure. Installez le client et l’exécuteur TypeScript dans votre projet : ```bash theme={"system"} npm install @coreweave/cwsandbox@0.5.0-beta.0 tsx ```

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. ```python title="start_claude_worker.py" theme={"system"} import os from cwsandbox import Sandbox worker = """ set -o pipefail case "$(uname -m)" in x86_64) arch=amd64 ;; aarch64) arch=arm64 ;; *) echo "Unsupported architecture" >&2; exit 1 ;; esac version=1.33.0 curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${version}/ant_${version}_linux_${arch}.tar.gz" \ | tar -xz -C /usr/local/bin ant mkdir -p /workspace exec ant beta:worker poll --workdir /workspace """ sandbox = Sandbox.run( "bash", "-ec", worker, container_image="python:3.12-bookworm", environment_variables={ "ANTHROPIC_ENVIRONMENT_KEY": os.environ["ANTHROPIC_ENVIRONMENT_KEY"], "ANTHROPIC_ENVIRONMENT_ID": os.environ["ANTHROPIC_ENVIRONMENT_ID"], }, resources={"cpu": "2", "memory": "4Gi"}, max_lifetime_seconds=8 * 3600, tags=["claude-managed-agents-worker"], ) try: sandbox.wait() except BaseException: sandbox.stop().result() raise print(f"Worker sandbox ID: {sandbox.sandbox_id}") ``` ```typescript title="start_claude_worker.mts" theme={"system"} import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node"; const token = process.env.ANTHROPIC_ENVIRONMENT_KEY; if (!token) throw new Error("Set ANTHROPIC_ENVIRONMENT_KEY."); const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID; if (!environmentId) throw new Error("Set ANTHROPIC_ENVIRONMENT_ID."); const worker = ` set -o pipefail case "$(uname -m)" in x86_64) arch=amd64 ;; aarch64) arch=arm64 ;; *) echo "Unsupported architecture" >&2; exit 1 ;; esac version=1.33.0 curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v\${version}/ant_\${version}_linux_\${arch}.tar.gz" \\ | tar -xz -C /usr/local/bin ant mkdir -p /workspace exec ant beta:worker poll --workdir /workspace `; const client = createSandboxClientFromEnv(); const sandbox = await client.run(["bash", "-ec", worker], { containerImage: "python:3.12-bookworm", environmentVariables: { ANTHROPIC_ENVIRONMENT_KEY: token, ANTHROPIC_ENVIRONMENT_ID: environmentId, }, resources: { cpu: "2", memory: "4Gi" }, maxLifetimeSeconds: 8 * 3600, waitUntilRunning: false, tags: ["claude-managed-agents-worker"], }); try { await sandbox.wait(); } catch (error) { await sandbox.stop(); throw error; } console.log(`Worker sandbox ID: ${sandbox.sandboxId}`); ``` Exécutez le script : ```bash theme={"system"} python start_claude_worker.py ``` ```bash theme={"system"} npx tsx start_claude_worker.mts ``` 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é : ```python theme={"system"} from cwsandbox import Sandbox sandbox = Sandbox.from_id("[SANDBOX-ID]").result() print("Sandbox status:", sandbox.get_status()) for container in sandbox.container_statuses: print(container.name, container.state, container.exit_code, container.restart_count) for line in sandbox.stream_logs(tail_lines=100): print(line, end="") ``` ```typescript theme={"system"} import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node"; const client = createSandboxClientFromEnv(); const sandbox = await client.fromId("[SANDBOX-ID]"); console.log("Sandbox status:", sandbox.status, "Exit code:", sandbox.exitCode); for (const line of await sandbox.logs.read({ tailLines: 100 })) { process.stdout.write(line); } ``` 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](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes) d’Anthropic.

Facultatif : utiliser un magasin de secrets

Vous pouvez transmettre une [référence de secret Forge](/fr/products/sandboxes/secrets) 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 : ```bash theme={"system"} export FORGE_API_KEY="[FORGE-API-KEY]" export FORGE_TEAM="[FORGE-TEAM]" ``` 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 : ```python theme={"system"} import os from cwsandbox import AuthHeaders auth = AuthHeaders( headers={ "x-wandb-api-key": os.environ["FORGE_API_KEY"], "x-entity-id": os.environ["FORGE_TEAM"], }, strategy="wandb_api_key", ) ``` 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 l’importation et l’initialisation du client par le code suivant. Utilisez également cette configuration du client dans les exemples TypeScript suivants : ```typescript theme={"system"} import { createSandboxClient } from "@coreweave/cwsandbox/wandb"; const client = createSandboxClient({ apiKey: process.env.FORGE_API_KEY, entity: process.env.FORGE_TEAM, }); ``` 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()`. Supprimez la déclaration `const token` ainsi que sa vérification `if (!token)`. Supprimez `ANTHROPIC_ENVIRONMENT_KEY` de `environmentVariables`, puis ajoutez `secrets: [{ store: "wandb", name: "[SECRET-NAME]", envVar: "ANTHROPIC_ENVIRONMENT_KEY" }]` aux options passées à `client.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 : ```bash theme={"system"} uv venv --python 3.11 .claude-client source .claude-client/bin/activate uv pip install 'anthropic>=1.6.0' ``` ```bash theme={"system"} npm install @anthropic-ai/sdk@0.126.0 tsx ``` 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 : ```bash theme={"system"} export ANTHROPIC_API_KEY="[ANTHROPIC-API-KEY]" export ANTHROPIC_AGENT_ID="[AGENT-ID]" export ANTHROPIC_ENVIRONMENT_ID="[ENVIRONMENT-ID]" ``` 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. ```python title="verify_claude_worker.py" theme={"system"} import os import uuid from anthropic import Anthropic client = Anthropic() proof = uuid.uuid4().hex session = client.beta.sessions.create( agent=os.environ["ANTHROPIC_AGENT_ID"], environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"], title="CoreWeave worker verification", ) print(f"Session ID: {session.id}") print(f"Expected file contents: {proof}") events_by_id = {} with client.beta.sessions.events.stream(session.id) as events: client.beta.sessions.events.send( session.id, events=[{ "type": "user.message", "content": [{ "type": "text", "text": f"Write exactly {proof} to managed-agent-proof.txt in your working directory and read it back.", }], }], ) for event in events: print(event.model_dump_json()) events_by_id[event.id] = event if event.type == "session.status_idle": reason = event.stop_reason if reason and reason.type == "requires_action": pending = [events_by_id.get(event_id) for event_id in reason.event_ids] if pending and all( getattr(tool, "evaluated_permission", None) == "allow" for tool in pending ): continue break ``` ```typescript title="verify_claude_worker.mts" theme={"system"} import { randomUUID } from "node:crypto"; import Anthropic from "@anthropic-ai/sdk"; const agent = process.env.ANTHROPIC_AGENT_ID; const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID; if (!agent || !environmentId) { throw new Error("Set ANTHROPIC_AGENT_ID and ANTHROPIC_ENVIRONMENT_ID."); } const client = new Anthropic(); const proof = randomUUID().replaceAll("-", ""); const session = await client.beta.sessions.create({ agent, environment_id: environmentId, title: "CoreWeave worker verification", }); console.log(`Session ID: ${session.id}`); console.log(`Expected file contents: ${proof}`); const allowedEvents = new Map(); await client.beta.sessions.events.send(session.id, { events: [{ type: "user.message", content: [{ type: "text", text: `Write exactly ${proof} to managed-agent-proof.txt in your working directory and read it back.`, }], }], }); const events = await client.beta.sessions.events.stream(session.id); try { for await (const event of events) { console.log(JSON.stringify(event)); if ("id" in event) { allowedEvents.set(event.id, "evaluated_permission" in event && event.evaluated_permission === "allow"); } if (event.type === "session.status_idle") { const reason = event.stop_reason; if (reason?.type === "requires_action" && reason.event_ids.length > 0 && reason.event_ids.every((id) => allowedEvents.get(id) === true)) { continue; } break; } } } finally { events.controller.abort(); } ``` Exécutez-la et examinez les événements : ```bash theme={"system"} python verify_claude_worker.py ``` ```bash theme={"system"} npx tsx verify_claude_worker.mts ``` 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](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#tool-confirmation) 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é : ```bash theme={"system"} cws-agent exec [SANDBOX-NAME] 'cat /workspace/claude/0/managed-agent-proof.txt' ``` ```python theme={"system"} from cwsandbox import Sandbox sandbox = Sandbox.from_id("[SANDBOX-ID]").result() result = sandbox.exec(["cat", "/workspace/managed-agent-proof.txt"], check=True).result() print(result.stdout, end="") ``` ```typescript theme={"system"} import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node"; const client = createSandboxClientFromEnv(); const sandbox = await client.fromId("[SANDBOX-ID]"); const result = await sandbox.commands.run(["cat", "/workspace/managed-agent-proof.txt"], { check: true }); process.stdout.write(result.stdout); ``` 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 : ```bash theme={"system"} cws-agent down [SANDBOX-NAME] ``` `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`. ```python theme={"system"} from cwsandbox import Sandbox sandbox = Sandbox.from_id("[SANDBOX-ID]").result() sandbox.stop().result() ``` ```typescript theme={"system"} import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node"; const client = createSandboxClientFromEnv(); const sandbox = await client.fromId("[SANDBOX-ID]"); await sandbox.stop(); ``` Cet exemple ne configure pas de stockage persistant. Copiez vos fichiers hors de la sandbox avant de l’arrêter. 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](https://platform.claude.com/docs/en/managed-agents/overview#beta-access). Consultez le [modèle de sécurité des environnements auto-hébergés](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-security) pour en savoir plus sur la gestion des données et les autorisations des workers.