Managed Agents API in der Sandbox-Umgebung der Agent Platform

Die Managed Agents API auf der Agent Platform wird mit standardmäßigen, isolierten Linux-Sandboxes betrieben. 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, Agent-Logik und Ausführungsstatus werden über mehrere Interaktionen hinweg sicher gespeichert.

  • Bash-Terminal:Bietet eine sichere Umgebung zum Ausführen von Terminalbefehlen, zum Ausführen benutzerdefinierter Skripts und zum Verarbeiten lokaler 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:Das Importieren benutzerdefinierter Funktionen wird dynamisch unterstützt, einschließlich Standard-Web-APIs, MCP-Servern (Model Context Protocol) oder Skills aus der Skill Registry.

Sandbox-Berechtigungen und ‑Sicherheit

Um die standardmäßigen Sicherheitsgrenzen für Unternehmen einzuhalten, wird die Remote-Sandbox unter den folgenden Berechtigungsmodellen betrieben:

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

  • Ausführung mit den geringsten Berechtigungen:Sobald der Netzwerkzugriff aktiviert ist, fehlen dem Container privilegierte Administratoranmeldedaten oder -berechtigungen. Standardmäßig können nur öffentlich zugängliche Internetadressen abgefragt werden.

  • Datenbereich für Cloud Storage- und Skill Registry-Bereitstellungen: Wenn Sie externe Datenquellen aus Google Cloud Storage oder der Skill Registry anhängen, erhält die Umgebung Autorisierungstokens mit eingeschränktem Bereich, die nur auf die in den Agentenkonfigurationen 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.

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

Ausführung und Lebenszyklusverwaltung

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

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

  • Gültigkeitsdauer (Time To Live, TTL) für die Sandbox: Die Sandbox-Umgebung hat eine standardmäßige Gültigkeitsdauer 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 Agents:Mehrere Agents teilen sich dieselbe Umgebung, wenn Sie während der Interaktion denselben env_id angeben.

Vorinstallierte Software

Die Sandbox enthält eine Reihe von Standard-Linux-Dienstprogrammen:

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 zur Laufzeit zusätzliche Pakete 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-Einbindung

Wenn Sie externe Skills aus Quellen wie der Skill Registry in der base_environment.sources eines Agents konfigurieren, werden diese Ressourcen direkt an das Sandbox-Dateisystem angehängt. Das System platziert jeden Skill in den angegebenen Zielverzeichnissen und behält dabei die ursprüngliche Verzeichnisstruktur des Skill-Pakets bei. So wird sichergestellt, 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

In der verwalteten Umgebung hat der Agent 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.

Leitfaden

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

Leitfaden

Informationen zum Interagieren mit Agents zur Laufzeit, zum Verwalten des Sitzungsstatus und zum dynamischen Überschreiben von Konfigurationen.