Configuration de l'environnement cloud

Les environnements définissent la configuration du « sandbox » (bac à sable) dans lequel votre agent s'exécute. Vous créez un environnement une seule fois, puis vous référencez son ID chaque fois que vous démarrez une session. Plusieurs sessions peuvent partager le même environnement, mais chaque session obtient son propre sandbox isolé (un conteneur Linux neuf).

Cette page couvre les environnements type: cloud. Pour exécuter des sandboxes sur votre propre infrastructure, consultez Sandboxes auto-hébergés.

Créer un environnement

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: python-dev
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

Utilisez un name unique et descriptif afin de pouvoir distinguer les environnements les uns des autres.

Utiliser l'environnement dans une session

Transmettez l'ID de l'environnement sous forme de chaîne de caractères lors de la création d'une session.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

Options de configuration

Paquets

Le champ packages préinstalle des paquets dans le sandbox avant le démarrage de l'agent. Les paquets sont installés par leurs gestionnaires de paquets respectifs et mis en cache entre les sessions qui partagent le même environnement. Lorsque plusieurs gestionnaires de paquets sont spécifiés, ils s'exécutent par ordre alphabétique (apt, cargo, gem, go, npm, pip). Vous pouvez éventuellement épingler des versions spécifiques. Les paquets non épinglés installent la dernière version. Si l'environnement utilise le réseau limited, définissez également networking.allow_package_managers sur true ; sinon, la requête est rejetée avec une erreur 400.

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: data-analysis
config:
  type: cloud
  packages:
    pip:
      - pandas
      - numpy
      - scikit-learn
    npm:
      - express
  networking:
    type: unrestricted

Gestionnaires de paquets pris en charge :

Réseau

Le champ networking contrôle l'accès réseau sortant du sandbox. Il n'affecte pas les outils web_search ou web_fetch, qui s'exécutent sur les serveurs d'Anthropic ; pour restreindre les sites que ces outils peuvent atteindre, définissez allowed_domains ou blocked_domains sur l'entrée de l'outil dans l'ensemble d'outils de l'agent. Consultez Restreindre les domaines de recherche web et de récupération web.

L'exemple suivant crée un environnement avec le réseau limited :

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: api-access
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - api.example.com
    allow_mcp_servers: true
    allow_package_managers: true

Lors de l'utilisation d'un réseau limited :

• allowed_hosts spécifie les domaines que le sandbox peut atteindre. Spécifiez des noms d'hôte simples ou des motifs génériques (tels que *.example.com). N'incluez pas de schéma d'URL, de port ni de chemin.
• allow_mcp_servers autorise l'accès sortant aux points de terminaison des serveurs MCP configurés sur l'agent, au-delà de ceux répertoriés dans le tableau allowed_hosts. La valeur par défaut est false.
• allow_package_managers autorise l'accès sortant à un ensemble de registres de paquets publics et d'hébergeurs de code au-delà de ceux répertoriés dans le tableau allowed_hosts. Consultez Hôtes des gestionnaires de paquets pour la liste. La valeur par défaut est false. Définissez-le sur true chaque fois que l'environnement spécifie packages ; sinon, la requête est rejetée avec une erreur 400, même si les hôtes des registres sont répertoriés dans allowed_hosts.

Hôtes des gestionnaires de paquets

Lorsque allow_package_managers est true, le sandbox peut atteindre les hôtes suivants en plus de ceux figurant dans allowed_hosts. Anthropic maintient cette liste et peut la modifier.

Cycle de vie de l'environnement

• Les environnements persistent jusqu'à ce qu'ils soient explicitement archivés ou supprimés.
• Chaque session obtient sa propre instance de sandbox, même lorsque plusieurs sessions référencent le même environnement. Les sessions ne partagent pas l'état du système de fichiers.
• Les environnements ne sont pas versionnés. Si vous mettez fréquemment à jour un environnement, conservez votre propre registre des modifications afin de pouvoir déterminer quelle configuration chaque session a utilisée.

Gérer les environnements

# List environments
environments = client.beta.environments.list()

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
client.beta.environments.delete(environment.id)

Runtimes préinstallés

Les sandboxes cloud incluent d'emblée des « runtimes » (environnements d'exécution) de langages courants, des bases de données et des outils en ligne de commande. Consultez la Référence des sandboxes cloud pour la liste complète.

Étapes suivantes