Configuration de la sandbox

Une nouvelle sandbox ne contient que les éléments fournis par son image. Vous ajoutez des outils avec un script de configuration ou une autre image, et une identité git avec un hook de sandbox. Les exemples utilisent MistralSandbox ; la section Sandbox locales présente les mêmes options pour LocalDockerSandbox.

Image et configuration

L'image utilisée par défaut est celle de la sandbox du SDK, fixée par son empreinte à chaque version du SDK. Elle repose sur Debian et inclut Python 3.12, git, gh, curl, jq, ripgrep, Node 22 avec pnpm, uv et pre-commit. Les commandes s'exécutent sous appuser, sans sudo. Un script de configuration ne peut donc pas installer de paquets système avec apt-get.

Pour ajouter vos propres outils, définissez setup_script pour les installer au démarrage de la sandbox, ou utilisez image pour choisir une autre image :

agents.MistralSandbox(
    setup_script="pip install --quiet pandas",
    setup_script_timeout_seconds=600,
    network=agents.Network.all(),  # pip needs outbound access
)

agents.MistralSandbox(image="ghcr.io/your-org/agent-sandbox:1.0")

agents.MistralSandbox(
    setup_script="pip install --quiet pandas",
    setup_script_timeout_seconds=600,
    network=agents.Network.all(),  # pip needs outbound access
)

agents.MistralSandbox(image="ghcr.io/your-org/agent-sandbox:1.0")

Le script de configuration s'exécute une seule fois, avant la première commande de l'agent. S'il se termine avec un code de sortie non nul, la sandbox est supprimée et la session échoue.

Une image personnalisée doit être publique et fournir un shell ainsi que python3. Avec une image personnalisée, les processus en arrière-plan sont désactivés, sauf si vous définissez supports_background_processes=True.

Identifiants

Pour permettre à la sandbox d'appeler un service externe, utilisez une liaison d'en-tête : l'identifiant n'entre jamais dans la sandbox.

Définir une identité git

Une nouvelle sandbox n'a pas d'identité git. La commande git commit échoue donc tant que user.name et user.email ne sont pas définis. Ajoutez un hook de sandbox agents.pattern.sandbox_hook.GitIdentity pour les définir à la création de la sandbox :

agent = agents.Agent(
    model="mistral-large-4",
    environment=agents.MistralSandbox(
        hooks=[agents.pattern.sandbox_hook.GitIdentity(name="Acme Bot", email="bot@acme.com")],
    ),
)

agent = agents.Agent(
    model="mistral-large-4",
    environment=agents.MistralSandbox(
        hooks=[agents.pattern.sandbox_hook.GitIdentity(name="Acme Bot", email="bot@acme.com")],
    ),
)

La sandbox doit disposer de git : l'image par défaut de MistralSandbox l'inclut, contrairement à BashkitSandbox. DangerousLocalSandbox refuse GitIdentity, car le hook écraserait votre propre fichier ~/.gitconfig.

Problèmes courants

Message affiché	Cause	Solution
`git config failed with exit code 127: bash: line 1: git: command not found`	La sandbox ne dispose pas de `git`, comme dans le cas de `BashkitSandbox`.	Utilisez `MistralSandbox` ou une image contenant `git`.
`DangerousLocalSandbox runs on the host, so it refuses GitIdentity: it would change the host user's own configuration`	`GitIdentity` écraserait votre propre configuration git.	Utilisez `LocalDockerSandbox` ou `MistralSandbox` pour travailler avec git.

Aller plus loin

Hooks de sandbox : initialisez l'espace de travail à la création de la sandbox, et enregistrez ce que l'agent a produit.