> ## 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.
# Exécuter des agents sur Sandboxes
> Exécutez des agents interactifs et autonomes sur CoreWeave, avec des sessions plus longues, du travail en parallèle et des outils.
Offrez à votre agent un Workspace sur CoreWeave, où il peut modifier du code, exécuter des tests et enregistrer des résultats. Cet aperçu vous aide à choisir une intégration et à configurer l’environnement pour des sessions plus longues, des sous-agents et l’exécution d’outils.
Pour les agents qui pilotent un bureau graphique à l’aide de captures d’écran et d’entrées souris et clavier, consultez [Exécuter un agent d’utilisation d’ordinateur dans une sandbox](/fr/products/sandboxes/tutorials/computer-use).
Pour l’évaluation d’agents à partir de benchmarks, consultez [Exécuter des évaluations sur les bacs à sable CoreWeave](/fr/products/sandboxes/evals).
L’exemple [Sessions cloud Claude Code](/fr/products/sandboxes/agents/claude-code-cloud) provisionne à la demande une sandbox worker, par l’intermédiaire d’un orchestrateur hébergé dans une sandbox, pour chaque session que vous démarrez sur claude.ai/code. Le worker s’arrête une fois libéré.
Agents de développement interactifs et agents autonomes
Avec un agent de développement interactif, vous travaillez aux côtés de l’agent : vous posez des questions, examinez les modifications et approuvez les actions depuis un terminal, un navigateur ou une application mobile. Par exemple, utilisez Claude Code pour analyser un test en échec tout en orientant vous-même les modifications.
Avec un agent autonome, vous déléguez une tâche et récupérez les résultats plus tard. Par exemple, attribuez-lui la migration d’un dépôt, laissez-le exécuter les tests et réviser ses modifications, puis examinez le résultat. Configurez ses autorisations, ses identifiants d’authentification et ses conditions d’arrêt avant qu’il ne commence le travail. Il peut néanmoins se mettre en pause pour solliciter votre intervention si nécessaire.
Il s’agit de modes de travail, et non de types de sandbox distincts. Un harness de développement peut prendre en charge les deux. Le harness gère la boucle de l’agent, le contexte du modèle, la sélection des outils et la délégation. CoreWeave fournit les ressources de calcul et le système de fichiers dans lesquels les outils s’exécutent. Une durée de vie du bac à sable plus longue laisse à l’agent davantage de temps d’exécution, mais la compaction des conversations et la récupération des tâches dépendent du harness.
Choisir une intégration
Les intégrations suivantes exécutent des commandes dans une sandbox CoreWeave. Elles se distinguent par l’emplacement de la boucle d’agent et par l’interface que vous utilisez :
| Guide | Emplacement de la boucle d’agent | Interface utilisée | Cas d’usage |
| - | - | - | - |
| [Claude Code](/fr/products/sandboxes/agents/claude-code) | La sandbox | Un terminal attaché, l’application mobile ou Desktop de Claude, ou claude.ai/code | Travailler sur un dépôt depuis votre terminal ou utiliser Remote Control depuis un autre appareil. |
| [Cursor](/fr/products/sandboxes/agents/cursor) | La sandbox | Un terminal attaché ou un script | Modifier un dépôt de manière interactive ou exécuter des tâches de programmation sans supervision. |
| [OpenCode CLI](/fr/products/sandboxes/agents/opencode) | La sandbox | Un terminal attaché ou une commande | Exécuter des tâches de programmation avec Serverless Inference ou un autre fournisseur de modèles. |
| [Muse Code](/fr/products/sandboxes/agents/muse-code) | La sandbox | Le SDK Sandboxes | Exécuter une tâche CLI sur un dépôt et récupérer le résultat. |
| [Pi](/fr/products/sandboxes/agents/pi) | La sandbox | Un terminal attaché | Travailler sur un dépôt avec le fournisseur de modèles de votre choix, y compris Serverless Inference. |
| [Claude Managed Agents](/fr/products/sandboxes/agents/claude-managed-agents) | Le service managé d’Anthropic | L’API Managed Agents | Connecter un worker auto-hébergé à une session d’agent managée. |
| [Codex](/fr/products/sandboxes/agents/codex) | La sandbox | Codex CLI dans la sandbox, une CLI locale connectée à Codex App Server, ou des applications de bureau et mobiles appairées | Travailler sur un dépôt distant avec Codex. |
| [Devin Outposts](/fr/products/sandboxes/agents/devin-outposts) | Devin Cloud | Devin Cloud | Exécuter les commandes de Devin dans une sandbox via un worker d’avant-poste. |
| [OpenAI Agents API](/fr/products/sandboxes/agents/openai-agents-api) | Le service managé d’OpenAI | Votre application, via l’API Agents | Exécuter des outils d’agent et des analyses de sous-agents dans une sandbox auto-hébergée. |
Les exemples Claude Code et Pi démarrent un agent interactif dans un Workspace que vous gérez. Les exemples Cursor permettent aussi bien le travail interactif que les tâches sans supervision. L’exemple Muse Code exécute une tâche sans terminal interactif. Les exemples Managed Agents et Devin Outposts démarrent des workers qui réutilisent une même sandbox pour plusieurs sessions mises en file d’attente. Mettre fin à une session du fournisseur n’arrête pas la sandbox de ce worker.
L’inférence du modèle reste assurée par le fournisseur configuré pour votre agent. Exécuter des outils dans une sandbox n’empêche pas l’agent d’envoyer des prompts, le contenu des fichiers ou la sortie des outils à ce fournisseur. Consultez ses exigences en matière de gestion des données avant de connecter votre Workspace.
Créer votre propre intégration
Utilisez le [SDK Sandboxes](/fr/products/sandboxes/client) pour créer un environnement, exécuter des appels d’outils, récupérer les résultats et arrêter les ressources de calcul depuis votre propre harness. Commencez par l’[exécution de commandes](/fr/products/sandboxes/client/guides/execution), les [opérations sur les fichiers](/fr/products/sandboxes/client/guides/file-operations) et les [modèles de nettoyage](/fr/products/sandboxes/client/guides/cleanup-patterns).
Premiers pas avec cws-agent
[`cws-agent`](https://github.com/coreweave/cws-agent) automatise la création de la sandbox, l’installation de l’agent et la gestion du Workspace. La plupart des guides d’intégration proposent un parcours de démarrage rapide qui s’appuie sur cet outil. D’autres guides configurent la sandbox directement avec le SDK Sandboxes. Lorsqu’un guide décrit les deux approches, vous pouvez suivre l’une ou l’autre indépendamment.
Suivez les [instructions d’installation](https://github.com/coreweave/cws-agent#install), puis choisissez un guide d’intégration. Les exemples génériques de `cws-agent` utilisent un jeton d’accès à l’API CoreWeave pour accéder à la sandbox. L’authentification auprès du fournisseur de l’agent s’effectue séparément.
```bash theme={"system"}
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
```
Le jeton doit disposer du rôle **Sandbox User**. Voir [Choisir et obtenir des identifiants d’authentification](/fr/products/sandboxes/placement#choose-and-get-credentials). Lorsque c’est possible, les exemples du SDK transmettent explicitement les identifiants d’authentification Forge ; suivez la procédure de configuration des identifiants d’authentification propre à chaque guide. Les intégrations qui nécessitent une ancienne variable d’environnement indiquent comment la renseigner à partir de votre clé API Forge.
Pour l’importation de configurations, les sessions parallèles, ainsi que l’enregistrement ou la restauration de Workspaces, consultez la [documentation de `cws-agent`](https://github.com/coreweave/cws-agent#more). `cws-agent` n’est pas nécessaire pour intégrer directement un harness.
Choisir où s’exécutent les bacs à sable
Le [placement sans serveur](/fr/products/sandboxes/get-started#run-a-sandbox-on-serverless-capacity) s’appuie sur une capacité exploitée par CoreWeave. C’est le point de départ de ces guides.
Utilisez le [placement CoreWeave Kubernetes Service (CKS)](/fr/products/sandboxes/get-started-cks) si vous avez besoin de maîtriser le placement sur votre propre cluster et la politique de sandbox. Votre administrateur déploie l’exécuteur et configure le réseau ainsi que les contraintes de ressources. Les agents doivent disposer d’un accès sortant vers leur fournisseur, ainsi que vers les hôtes de paquets ou de sources qu’ils utilisent.
Exécuter des sessions plus longues
La durée de vie est une limite de temps réel (wall-clock), démarrage compris, et ne peut pas être prolongée après la création. Elle ne garantit pas que l’agent mène sa tâche à terme ni qu’il se rétablisse après une interruption.
Les bacs à sable sans serveur ont une durée de vie par défaut de 10 minutes lorsque vous omettez `max_lifetime_seconds`. La politique d’un exécuteur CKS peut définir une valeur par défaut différente. Définissez explicitement la durée de vie lors de la création, en prévoyant suffisamment de temps pour la configuration et la tâche.
Définir la durée de vie d’un sandbox sans serveur
Une fois l’[installation du SDK et l’authentification](/fr/products/sandboxes/get-started#run-your-first-sandbox) effectuées, utilisez cette requête de création pour obtenir un sandbox doté d’une durée de vie de 24 heures. Les exemples lisent `FORGE_API_KEY` et la transmettent explicitement au client :
```python theme={"system"}
import os
from cwsandbox import AuthHeaders, Sandbox
forge_auth = AuthHeaders(
headers={"x-wandb-api-key": os.environ["FORGE_API_KEY"]},
strategy="wandb_api_key",
)
sandbox = Sandbox.run(
auth=forge_auth,
placement_mode="serverless",
container_image="python:3.12-slim",
resources={"cpu": "4", "memory": "8Gi"},
max_lifetime_seconds=24 * 60 * 60,
)
print(f"Sandbox ID: {sandbox.sandbox_id}")
```
```typescript theme={"system"}
import { createSandboxClient } from "@coreweave/cwsandbox/wandb";
const client = createSandboxClient({
apiKey: process.env.FORGE_API_KEY,
});
const sandbox = await client.create({
containerImage: "python:3.12-slim",
resources: { cpu: "4", memory: "8Gi" },
maxLifetimeSeconds: 24 * 60 * 60,
waitUntilRunning: false,
});
console.log(`Sandbox ID: ${sandbox.sandboxId}`);
```
Conservez l’ID affiché pour [vous reconnecter avec le SDK](/fr/products/sandboxes/client/guides/sandbox-lifecycle#reconnection). L’ID confirme que la création a été acceptée, mais pas que le démarrage est terminé. Suivez un guide d’intégration pour attendre que le sandbox soit prêt, puis installer et démarrer votre agent, ou fournissez une image dans laquelle vos outils sont déjà installés.
Les deux appels de création autonomes laissent le sandbox en cours d’exécution une fois le script terminé. En TypeScript, `withSandbox()` l’arrête lorsque sa fonction de rappel se termine. Un bloc `with Sandbox.run(...)` l’arrête à la sortie du bloc. Les bacs à sable créés via une `Session` du SDK s’arrêtent à la fermeture de cette session, y compris lors du nettoyage effectué à la sortie du processus.
Une fois `cws-agent` installé et authentifié, définissez la même durée de vie au lancement de Claude Code. Remplacez `[SANDBOX-NAME]` par un nom de session `cws-agent` pour votre Workspace. Ce nom doit comporter de 1 à 40 lettres minuscules, chiffres ou traits d’union, et commencer par une lettre ou un chiffre :
```bash theme={"system"}
cws-agent launch [SANDBOX-NAME] --lifetime 24h --cpu 4 --memory 8Gi --permission-mode native
```
Pour qu’un agent interactif continue de s’exécuter après la fermeture de votre terminal, lancez-le dans un multiplexeur de terminal. Consultez le [guide `tmux`](https://github.com/tmux/tmux/wiki/Getting-Started) pour savoir comment détacher une session et vous y reconnecter. Une session détachée peut toujours rester en attente d’une approbation ou d’une connexion.
Le placement CKS nécessite un jeton d’accès à l’API CoreWeave disposant de l’action IAM `SANDBOX_USER`. Suivez [Utiliser votre propre infrastructure de calcul](/fr/products/sandboxes/get-started-cks). En Python, définissez `auth=AuthStrategy.COREWEAVE_API_KEY`, conservez `max_lifetime_seconds`, puis définissez `placement_mode="cks"` et `runner_ids=["[RUNNER-ID]"]`. Remplacez `[RUNNER-ID]` par l’identifiant de l’exécuteur de votre cluster. En TypeScript, utilisez le point d’entrée `@coreweave/cwsandbox/node`, conservez `maxLifetimeSeconds` et définissez `runnerIds: ["[RUNNER-ID]"]` pour sélectionner CKS.
L’exécuteur doit disposer d’une politique configurée, dont les plafonds de ressources doivent être suffisants pour la requête de création. Conservez les autres contraintes ainsi que les éventuels plafonds plus élevés requis par les charges de travail existantes. Toute écriture de politique remplace l’intégralité du document, et les modifications ne s’appliquent qu’aux bacs à sable créés par la suite.
Pour que la valeur par défaut soit de 24 heures pour les requêtes qui ne précisent pas de durée de vie, demandez à l’administrateur de modifier la politique existante avec la [CoreWeave Intelligent CLI](/fr/products/sandboxes/profiles/configure#update-a-policy) :
```bash theme={"system"}
cwic sandbox runner policy edit [RUNNER-ID]
```
Fusionnez ces champs dans l’objet `constraints` existant. Il s’agit d’un fragment de politique, et non d’un document complet de remplacement :
```json theme={"system"}
{
"constraints": {
"lifecycle": {
"defaultLifetimeSeconds": 86400
},
"resources": {
"maxCpu": "4",
"maxMemory": "8Gi"
}
}
}
```
Une durée de vie explicitement indiquée dans la requête prévaut sur `defaultLifetimeSeconds`. La plateforme impose une limite maximale de 30 jours. La politique ne comporte aucun champ `maxLifetimeSeconds` permettant de relever cette limite.
Pour autoriser les connexions aux fournisseurs, configurez également le [trafic sortant réseau](/fr/products/sandboxes/profiles/configure#constrain-network-access) : `allowedEgress` autorise les destinations demandées, tandis que `defaultEgress` accorde l'accès lorsque la requête ne précise aucune règle de trafic sortant. Une autorisation ne suffit pas, à elle seule, à accorder l'accès.
Dissocier le temps d’exécution de l’état de la conversation
Le paramètre `timeout_seconds` d’une commande d’outil est indépendant de la durée de vie du bac à sable. Définissez un délai d’expiration de commande adapté aux compilations et aux tests de longue durée. Pour les tâches sans surveillance, utilisez les fonctionnalités d’exécution en arrière-plan et de récupération prises en charge par le harness, et enregistrez les résultats intermédiaires. Voir [délais d’expiration des commandes](/fr/products/sandboxes/client/guides/execution#set-a-timeout) et [cycle de vie du bac à sable](/fr/products/sandboxes/client/guides/sandbox-lifecycle).
Déléguer le travail à des sous-agents
Configurez les sous-agents dans votre harness. Aucune option de création de sandbox n’active les sous-agents. Claude Code, par exemple, propose des sous-agents intégrés. Dans une session interactive, demandez-lui de répartir les analyses indépendantes entre plusieurs sous-agents :
```text theme={"system"}
Utilise des sous-agents distincts pour examiner l'API et ses tests en parallèle.
Demande à chacun d'indiquer les fichiers pertinents et ses constats, sans rien modifier.
Regroupe leurs constats dans un plan d'implémentation.
```
Pour définir un spécialiste réutilisable, créez ce fichier dans le projet de la sandbox avant de lancer Claude Code :
```markdown title=".claude/agents/test-reader.md" theme={"system"}
---
name: test-reader
description: Inspect tests and report coverage gaps without editing files.
tools: Read, Grep, Glob
---
Find tests relevant to the requested change. Summarize coverage gaps and
cite the test files. Do not modify files.
```
Demandez à Claude d’utiliser `test-reader` pour une tâche précise. La délégation est disponible par défaut. Une règle `permissions.deny` appliquée à l’outil `Agent` de l’agent parent bloque la délégation. Pour les autorisations des outils et les autres options, consultez la [configuration des sous-agents de Claude Code](https://code.claude.com/docs/en/sub-agents).
Les sous-agents qui utilisent la même sandbox se partagent ses ressources de calcul et son système de fichiers. Dimensionnez le CPU et la mémoire en fonction des outils exécutés en parallèle, et évitez que plusieurs sous-agents modifient les mêmes fichiers en même temps. Si les workers ont besoin d’identifiants d’authentification distincts ou d’une isolation, utilisez des bacs à sable séparés.
Pour des tâches de développement distinctes, les [sessions parallèles `cws-agent`](https://github.com/coreweave/cws-agent/blob/main/docs/sessions.md) fournissent des worktrees Git séparés au sein d’une même sandbox. Il s’agit de sessions indépendantes, et non de sous-agents gérés par le harness ni de périmètres de sécurité distincts.
Préparez l’environnement pour que les agents puissent consacrer leur temps à la tâche :
* **Installez les dépendances récurrentes dans l’image.** Transmettez une `container_image` préparée lors de la création pour éviter de réinstaller les mêmes outils de test et runtimes à chaque session. Voir [configuration du bac à sable](/fr/products/sandboxes/client/guides/sandbox-configuration).
* **Sélectionnez les outils nécessaires à la tâche.** Configurez les skills et les serveurs Model Context Protocol (MCP) dans le harness. Pour une session CLI gérée par `cws-agent`, prévisualisez la configuration locale et importez les éléments sélectionnés dans son sandbox :
```bash theme={"system"}
cws-agent config preview [SANDBOX-NAME] --verbose
cws-agent config sync [SANDBOX-NAME]
```
L’importation de configuration n’est pas disponible pour les workers Claude Managed Agents. La commande `sync` vous invite à effectuer vos sélections, puis à les confirmer. Redémarrez l’agent pour charger les modifications. Installez les exécutables requis dans le sandbox et remplacez les chemins propres à votre machine locale. Voir [importations de skills et de MCP](https://github.com/coreweave/cws-agent/blob/main/docs/config-import.md).
* **Renvoyez des résultats ciblés.** Faites filtrer ou synthétiser les données par les outils dans le sandbox avant de les renvoyer au modèle. Par exemple, enregistrez la sortie complète des tests dans un fichier et renvoyez uniquement les noms des tests en échec ainsi qu’une brève synthèse des échecs. Gardez le fichier à disposition pour une inspection ultérieure.
* **Parallélisez les opérations indépendantes.** Lorsque les ressources le permettent, exécutez les vérifications indépendantes en parallèle. Attendez que les prérequis soient satisfaits avant de lancer les étapes qui en dépendent. Le [guide d’exécution du SDK](/fr/products/sandboxes/client/guides/execution#sequential-compared-with-parallel-execution) montre comment lancer des commandes et récupérer leurs résultats.
La découverte des outils, le compactage du contexte et le choix des outils à appeler restent des fonctionnalités du harness. CoreWeave exécute les commandes et stocke leurs fichiers.
Conserver les résultats et arrêter les ressources de calcul
Quitter un agent ou mettre fin à une session du fournisseur n’arrête pas forcément sa sandbox. Suivez les étapes de nettoyage décrites dans le guide d’intégration et définissez une durée de vie lorsque vous créez des ressources de calcul.
Avant l’arrêt, copiez les résultats en dehors de la sandbox, téléversez vos modifications dans votre dépôt ou configurez un volume d’instantanés pour utiliser les [instantanés du système de fichiers](/fr/products/sandboxes/file-system-snapshots). Les instantanés conservent les fichiers, mais pas les processus en cours d’exécution. L’historique des conversations du fournisseur suit son propre cycle de vie.