Cloud-Umgebungseinrichtung

Umgebungen definieren die Container-Konfiguration, in der Ihr Agent ausgeführt wird. Sie erstellen eine Umgebung einmal und referenzieren dann deren ID jedes Mal, wenn Sie eine Sitzung starten. Mehrere Sitzungen können dieselbe Umgebung teilen, aber jede Sitzung erhält ihre eigene isolierte Container-Instanz.

Alle Managed Agents API-Anfragen erfordern den managed-agents-2026-04-01 Beta-Header. Das SDK setzt den Beta-Header automatisch.

Eine Umgebung erstellen

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "python-dev",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)
environment_id=$(jq -r '.id' <<< "$environment")

echo "Environment ID: $environment_id"

Der name muss innerhalb Ihrer Organisation und Ihres Arbeitsbereichs eindeutig sein.

Die Umgebung in einer Sitzung verwenden

Übergeben Sie die Umgebungs-ID als Zeichenkette beim Erstellen einer Sitzung.

Konfigurationsoptionen

Pakete

Das Feld packages installiert Pakete vorab in den Container, bevor der Agent startet. Pakete werden von ihren jeweiligen Paketmanagern installiert und über Sitzungen hinweg zwischengespeichert, die dieselbe Umgebung teilen. Wenn mehrere Paketmanager angegeben werden, werden sie in alphabetischer Reihenfolge ausgeführt (apt, cargo, gem, go, npm, pip). Sie können optional bestimmte Versionen festlegen; der Standard ist die neueste Version.

Unterstützte Paketmanager:

Feld	Paketmanager	Beispiel
`apt`	Systempakete (apt-get)	`"ffmpeg"`
`cargo`	Rust (cargo)	`"[email protected]"`
`gem`	Ruby (gem)	`"rails:7.1.0"`
`go`	Go-Module	`"golang.org/x/tools/cmd/goimports@latest"`
`npm`	Node.js (npm)	`"[email protected]"`

Netzwerk

Das Feld networking steuert den ausgehenden Netzwerkzugriff des Containers. Es hat keinen Einfluss auf die erlaubten Domains der Tools web_search oder web_fetch.

Modus	Beschreibung
`unrestricted`	Vollständiger ausgehender Netzwerkzugriff, mit Ausnahme einer allgemeinen Sicherheitsblockliste. Dies ist der Standard.
`limited`	Schränkt den Container-Netzwerkzugriff auf die Liste `allowed_hosts` ein. Weiterer Zugriff wird über die booleschen Werte `allow_package_managers` und `allow_mcp_servers` aktiviert.

Verwenden Sie für Produktionsbereitstellungen limited-Netzwerk mit einer expliziten allowed_hosts-Liste. Befolgen Sie das Prinzip der minimalen Rechtevergabe, indem Sie nur den minimalen Netzwerkzugriff gewähren, den Ihr Agent benötigt, und überprüfen Sie Ihre erlaubten Domains regelmäßig.

Bei Verwendung von limited-Netzwerk:

allowed_hosts gibt Domains an, die der Container erreichen kann. Diese müssen mit HTTPS beginnen.
allow_mcp_servers erlaubt ausgehenden Zugriff auf MCP-Server-Endpunkte, die auf dem Agenten konfiguriert sind, über die in der allowed_hosts-Liste aufgeführten hinaus. Standardmäßig false.
allow_package_managers erlaubt ausgehenden Zugriff auf öffentliche Paket-Registries (PyPI, npm usw.) über die in der allowed_hosts-Liste aufgeführten hinaus. Standardmäßig false.

Lebenszyklus von Umgebungen

Umgebungen bleiben bestehen, bis sie explizit archiviert oder gelöscht werden.
Mehrere Sitzungen können dieselbe Umgebung referenzieren.
Jede Sitzung erhält ihre eigene Container-Instanz. Sitzungen teilen keinen Dateisystemzustand.
Umgebungen werden nicht versioniert. Wenn Sie Ihre Umgebungen häufig aktualisieren, sollten Sie diese Aktualisierungen auf Ihrer Seite protokollieren, um den Umgebungszustand mit Sitzungen zu verknüpfen.

Umgebungen verwalten

Vorinstallierte Laufzeitumgebungen

Cloud-Container enthalten gängige Laufzeitumgebungen von Haus aus. Siehe Container-Referenz für die vollständige Liste der vorinstallierten Sprachen, Datenbanken und Hilfsprogramme.

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id"
}
EOF
)

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "data-analysis",
  "config": {
    "type": "cloud",
    "packages": {
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["express"]
    },
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

config=$(cat <<'EOF'
{
  "type": "cloud",
  "networking": {
    "type": "limited",
    "allowed_hosts": ["api.example.com"],
    "allow_mcp_servers": true,
    "allow_package_managers": true
  }
}
EOF
)

# List environments
environments=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Retrieve a specific environment
env=$(curl -fsS "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Archive an environment (read-only, existing sessions continue)
curl -fsS -X POST "https://api.anthropic.com/v1/environments/$environment_id/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

# Delete an environment (only if no sessions reference it)
curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"