Managed Agents API in der Sandbox-Umgebung der Agent Platform

Die Managed Agents API auf der Agent Platform arbeitet mit standardmäßigen, isolierten Linux-Sandboxes. In diesem sicheren, vollständig verwalteten Ausführungscontainer können benutzerdefinierte KI-Agenten sofort logisch schlussfolgern, Workflows planen, Bash-Befehle ausführen und Dateien lesen oder schreiben.

Jede Sandbox-Umgebung bietet die folgenden Kernsysteme und ‑kontrollen:

  • Persistentes Dateisystem: Dateien, KI-Agentenlogik und Ausführungsstatus werden über mehrere Interaktionen hinweg sicher gespeichert.

  • Bash-Terminal: Bietet eine sichere Umgebung zum Ausführen von Terminalbefehlen, benutzerdefinierten Skripts und lokalen Dateien.

  • Netzwerkisolation: Standardmäßig deaktiviert. Sie können explizit ein Netzwerk allowlist deklarieren, damit der Agent auf öffentliche Internetressourcen zugreifen oder externe Bibliotheken herunterladen kann.

  • Erweiterbare Integrationen: Unterstützt das dynamische Importieren benutzerdefinierter Funktionen, einschließlich Standard-Web-APIs, MCP-Server (Model Context Protocol) oder Skills aus der Skill Registry.

Sandbox-Berechtigungen und -Sicherheit

Um die standardmäßigen Sicherheitsgrenzen des Unternehmens einzuhalten, wird die Remote-Sandbox mit den folgenden Berechtigungsmodellen betrieben:

  • Netzwerkisolation: Standardmäßig wird die Sandbox ohne externen Netzwerkzugriff ausgeführt. Aktivieren Sie die Verbindung explizit, indem Sie in Ihrer Umgebungskonfiguration eine Domain-Zulassungsliste festlegen. Beispiele für Zulassungslisten finden Sie unter Netzwerkzugriff konfigurieren.

  • Ausführung mit geringsten Berechtigungen: Sobald der Netzwerkzugriff aktiviert ist, verfügt der Container nicht mehr über privilegierte Administratoranmeldedaten oder -berechtigungen. Standardmäßig können nur öffentlich zugängliche Internetstandorte abgefragt werden.

  • Datenbereich für Cloud Storage- und Skill Registry-Bereitstellungen: Wenn Sie externe Datenquellen aus Cloud Storage oder der Skill Registry anhängen, erhält die Umgebung Autorisierungstokens mit eingeschränktem Bereich, die nur auf die in den Agent-Konfigurationen angegebenen Verzeichnisse oder Skills zugreifen können. Die Sandbox enthält keine Umgebungsinformationen und kann nicht auf andere Repositories oder Dateien in Ihrem Projekt zugreifen.

  • Bereich für MCP-Anmeldedaten: Header-Konfigurationen für Model Context Protocol-Server (MCP), die Backend-Authentifizierungstokens enthalten, werden nur übertragen, wenn auf die in Ihrer Konfiguration definierten spezifischen MCP-Endpunkte zugegriffen wird.

Ausführungs- und Lebenszyklusverwaltung

Diese Standardparameter steuern die Ausführung und den Lebenszyklus der Sandbox:

  • Sandbox-Umgebung: KI-Agenten werden in einer vollständig verwalteten Sandbox-Umgebung ausgeführt, wobei die Antigravity-Harness für die Orchestrierung verwendet wird.

  • Gültigkeitsdauer (TTL) der Sandbox: Die Sandbox-Umgebung hat eine Standardgültigkeitsdauer (TTL) von 7 Tagen. Bei jeder neuen Interaktion wird dieser Timer automatisch zurückgesetzt, damit aktive KI-Agenten verfügbar bleiben.

  • Persistenz der Agentenkonfiguration: Das Backend speichert Agentenkonfigurationen dauerhaft. Sie bleiben erhalten, bis Sie eine explizite DELETE-Anfrage an die Agents API senden.

  • Zusammenarbeit von Agenten: Mehrere Agenten nutzen dieselbe Umgebung, wenn Sie während der Interaktion dieselbe env_id angeben.

Vorinstallierte Software

Die Sandbox enthält eine Reihe von Linux-Standarddienstprogrammen:

Kategorie Pakete/Tools
UNIX-Tools
  • bc
  • curl
  • fd-find
  • gawk
  • gcloud CLI
  • git
  • htop
  • iproute2
  • jq
  • lsof
  • procps
  • ripgrep
  • rsync
  • tree
  • unzip
  • wget
  • which
Python 3.11-Pakete
  • ast-grep-cli
  • beautifulsoup4
  • google-genai
  • numpy
  • pandas
  • pyyaml
  • requests
Globale Node.js 20-Pakete
  • create-next-app
  • create-vite
  • typescript

Der Agent kann zusätzliche Pakete zur Laufzeit mit pip install oder npm install installieren, wenn der Netzwerkzugriff aktiviert ist. Diese Pakete bleiben im Umgebungs-Snapshot erhalten und sind für Interaktionen verfügbar, bei denen dieselbe env_id wiederverwendet wird.

Architektur für die Skill-Bereitstellung

Wenn Sie externe Skills aus Quellen wie der Skill Registry im base_environment.sources eines Agenten konfigurieren, werden diese Ressourcen direkt in das Sandbox-Dateisystem eingebunden. Das System platziert jeden Skill in den angegebenen Zielverzeichnissen und behält die ursprüngliche Verzeichnisstruktur des Skill-Pakets bei. Diese Organisation trägt dazu bei, dass einzelne Skill-Dateien für den Agenten auffindbar bleiben.

Beispielkonfiguration für Quellen

Im folgenden Beispiel werden drei Skills aus der Skill Registry angehängt:

"sources": [
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/pdf-skill",
    "target": "/.agent/skills/"
  },
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/finance-skill",
    "target": "/.agent/skills/"
  },
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/git-skill",
    "target": "/.agent/other-skills/"
  }
]

Sandbox-Dateisystemstruktur nach der Bereitstellung

Nachdem die Sandbox-Umgebung bereitgestellt wurde, werden die Dateien im Container so bereitgestellt und strukturiert:

/ (root)
└── .agent/
    ├── skills/                    <-- Mount Target for pdf-skill & finance-skill
    │   ├── pdf-skill/             <-- Preserved skill directory
    │   │   ├── SKILL.md
    │   │   └── scripts/
    │   └── finance-skill/         <-- Preserved skill directory
    │       ├── SKILL.md
    │       └── scripts/
    └── other-skills/              <-- Mount Target for git-skill
        └── git-skill/             <-- Preserved skill directory
            ├── SKILL.md
            └── scripts/

Integrierte Sandbox-Tools

Wenn der Agent in der verwalteten Umgebung ausgeführt wird, hat er Zugriff auf mehrere Standardtools:

Toolname Beschreibung
bash Führt einen Shell-Befehl im Sandbox-Terminal aus und gibt die Ausgabe zurück.
file_system Liest, schreibt und löscht den Inhalt einer Datei und listet den Inhalt eines Verzeichnisses auf.

Nächste Schritte

Übersicht

Informationen zur Managed Agents API auf der Agent Platform, einer konfigurationsgesteuerten, REST-basierten Umgebung zum Erstellen autonomer Agenten.

Anleitung

Hier erfahren Sie, wie Sie mit der REST API Agenten erstellen, aktualisieren, auflisten, abrufen und löschen.

Anleitung

Hier erfahren Sie, wie Sie zur Laufzeit mit Agenten interagieren, den Sitzungsstatus verwalten und Konfigurationen dynamisch überschreiben.