Managed Agents API in der Sandbox-Umgebung der Agent Platform

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

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

  • Permanentes Dateisystem:Dateien, Agentenlogik und Ausführungsstatus werden sicher über Mehrfachdialoge hinweg gespeichert.

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

  • Netzwerkisolation:Standardmäßig deaktiviert. Sie können explizit eine allowlist für das Netzwerk 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-Servern (Model Context Protocol) oder Skills aus der Skill Registry.

Sandbox-Berechtigungen und ‑Sicherheit

Um die Standardsicherheitsgrenzen für Unternehmen einzuhalten, wird die Remote-Sandbox mit den folgenden Berechtigungsmodellen betrieben:

  • Netzwerkisolation:Standardmäßig funktioniert die Sandbox ohne externen Netzwerkzugriff. Aktivieren Sie die Verbindung explizit, indem Sie in der Umgebungskonfiguration eine Zulassungsliste für Domains 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, wird die Umgebung mit eingeschränkten Autorisierungstokens bereitgestellt, die nur auf die in den Agenten konfigurationen angegebenen Verzeichnisse oder Skills zugreifen können. Die Sandbox enthält keine Umgebungsanmeldedaten und kann nicht auf andere Repositories oder Dateien in Ihrem Projekt zugreifen.

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

Ausführung und Lebenszyklusverwaltung

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

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

  • Gültigkeitsdauer (Time to Live, TTL) der Sandbox : Die Sandbox-Umgebung hat eine Standard-TTL von 7 Tagen. Bei jeder neuen Interaktion wird dieser Timer automatisch zurückgesetzt, damit aktive Agenten weiterhin verfügbar sind.

  • Persistenz der Agentenkonfiguration:Die Agentenkonfigurationen werden im Backend dauerhaft gespeichert und bleiben erhalten, bis Sie eine explizite DELETE-Anfrage an die Agents API senden.

  • Zusammenarbeit von Agenten:Mehrere Agenten verwenden dieselbe Umgebung, wenn Sie bei der Interaktion dieselbe 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 Snapshot der Umgebung erhalten und sind für Interaktionen verfügbar, bei denen dieselbe env_id verwendet wird.

Architektur für die Bereitstellung von Skills

Wenn Sie externe Skills aus Quellen wie der Skill Registry in den 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 dabei die ursprüngliche Verzeichnisstruktur des Skill-Pakets bei. So können die einzelnen Skill-Dateien vom Agenten gefunden werden.

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 wie folgt 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

Bei der Ausführung in der verwalteten Umgebung hat der Agent Zugriff auf mehrere Standardtools:

Tool name 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

Informationen zum Erstellen, Aktualisieren, Auflisten, Abrufen und Löschen von Agenten mit der REST API.

Anleitung

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