Einrichtung der Cloud-Umgebung

Environments (Umgebungen) definieren die Sandbox-Konfiguration, in der dein Agent läuft. Du erstellst eine Umgebung einmal und referenzierst dann ihre ID jedes Mal, wenn du eine Session startest. Mehrere Sessions können dieselbe Umgebung gemeinsam nutzen, aber jede Session erhält ihre eigene isolierte Sandbox (einen frischen Linux-Container).

Diese Seite behandelt Umgebungen vom Typ type: cloud. Um Sandboxes auf deiner eigenen Infrastruktur auszuführen, siehe Selbst gehostete Sandboxes.

Eine Umgebung erstellen

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

Verwende einen eindeutigen, aussagekräftigen name, damit du Umgebungen voneinander unterscheiden kannst.

Die Umgebung in einer Session verwenden

Übergib die Umgebungs-ID als String beim Erstellen einer Session.

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

Konfigurationsoptionen

Pakete

Das Feld packages installiert Pakete vorab in der Sandbox, bevor der Agent startet. Pakete werden von ihren jeweiligen Paketmanagern installiert und über Sessions hinweg, die dieselbe Umgebung nutzen, zwischengespeichert. Wenn mehrere Paketmanager angegeben sind, werden sie in alphabetischer Reihenfolge ausgeführt (apt, cargo, gem, go, npm, pip). Du kannst optional bestimmte Versionen festlegen. Pakete ohne festgelegte Version installieren die neueste Version. Wenn die Umgebung limited Networking verwendet, setze außerdem networking.allow_package_managers auf true; andernfalls wird die Anfrage mit einem 400-Fehler abgelehnt.

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

Unterstützte Paketmanager:

Networking

Das Feld networking steuert den ausgehenden Netzwerkzugriff der Sandbox. Es wirkt sich nicht auf die Tools web_search oder web_fetch aus, die auf den Servern von Anthropic laufen; um die Websites einzuschränken, die diese Tools erreichen können, setze allowed_domains oder blocked_domains im Eintrag des Tools im Agent-Toolset. Siehe Domains für Websuche und Web-Fetch einschränken.

Das folgende Beispiel erstellt eine Umgebung mit limited Networking:

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

Bei Verwendung von limited Networking:

• allowed_hosts gibt die Domains an, die die Sandbox erreichen kann. Gib reine Hostnamen oder Wildcard-Muster (wie *.example.com) an. Füge kein URL-Schema, keinen Port und keinen Pfad hinzu.
• allow_mcp_servers erlaubt ausgehenden Zugriff auf die im Agenten konfigurierten MCP-Server-Endpunkte, zusätzlich zu denen, die im Array allowed_hosts aufgeführt sind. Standardwert ist false.
• allow_package_managers erlaubt ausgehenden Zugriff auf eine Reihe öffentlicher Paket-Registries und Code-Hosts, zusätzlich zu denen, die im Array allowed_hosts aufgeführt sind. Die Liste findest du unter Paketmanager-Hosts. Standardwert ist false. Setze den Wert auf true, wann immer die Umgebung packages angibt; andernfalls wird die Anfrage mit einem 400-Fehler abgelehnt, selbst wenn die Registry-Hosts in allowed_hosts aufgeführt sind.

Paketmanager-Hosts

Wenn allow_package_managers auf true gesetzt ist, kann die Sandbox zusätzlich zu den Hosts in allowed_hosts die folgenden Hosts erreichen. Anthropic pflegt diese Liste und kann sie ändern.

Lebenszyklus von Umgebungen

• Umgebungen bleiben bestehen, bis sie explizit archiviert oder gelöscht werden.
• Jede Session erhält ihre eigene Sandbox-Instanz, auch wenn mehrere Sessions dieselbe Umgebung referenzieren. Sessions teilen keinen Dateisystemzustand.
• Umgebungen sind nicht versioniert. Wenn du eine Umgebung häufig aktualisierst, führe deine eigenen Aufzeichnungen über die Änderungen, damit du nachvollziehen kannst, welche Konfiguration jede Session verwendet hat.

Umgebungen verwalten

# 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)

Vorinstallierte Laufzeitumgebungen

Cloud-Sandboxes enthalten standardmäßig gängige Sprach-Laufzeitumgebungen, Datenbanken und Kommandozeilen-Tools. Siehe Cloud-Sandbox-Referenz für die vollständige Liste.

Nächste Schritte