API Managed Agents dans l'environnement bac à sable Agent Platform

L'API Managed Agents sur Agent Platform fonctionne avec des bacs à sable Linux standards et isolés. Dans ce conteneur d'exécution sécurisé et entièrement géré, les agents personnalisés peuvent raisonner, planifier des workflows, exécuter des commandes Bash et lire ou écrire des fichiers prêts à l'emploi.

Chaque environnement de bac à sable fournit les systèmes et contrôles de base suivants :

  • Système de fichiers persistant : conserve de manière sécurisée les fichiers, la logique de l'agent et l'état d'exécution lors d'interactions multitours.

  • Terminal Bash : fournit un environnement sécurisé pour exécuter des commandes de terminal, exécuter des scripts personnalisés et traiter des fichiers locaux.

  • Isolation du réseau : désactivée par défaut. Vous pouvez déclarer explicitement une allowlist de réseau pour permettre à l'agent d'accéder aux ressources Internet publiques ou de télécharger des bibliothèques externes.

  • Intégrations extensibles : permet d'importer des fonctionnalités personnalisées de manière dynamique, y compris des API Web standards, des serveurs MCP (Model Context Protocol) ou des compétences à partir du Skill Registry.

Autorisations et sécurité du bac à sable

Pour maintenir les limites de sécurité standards de l'entreprise, le bac à sable à distance fonctionne selon les modèles d'autorisation suivants :

  • Isolation du réseau : par défaut, le bac à sable fonctionne sans accès au réseau externe. Activez explicitement la connectivité en définissant une liste d'autorisation de domaine dans la configuration de votre environnement. Pour obtenir des exemples de listes d'autorisation, consultez Configurer l'accès au réseau.

  • Exécution avec le moindre privilège : une fois l'accès au réseau activé, le conteneur ne dispose pas d'identifiants ni d'autorisations d'administration privilégiés. Par défaut, il ne peut interroger que les emplacements Internet accessibles au public.

  • Délimitation des données pour les installations Cloud Storage et Skill Registry : lorsque vous associez des sources de données externes à partir de Google Cloud Storage ou du Skill Registry, l'environnement reçoit des jetons d'autorisation à portée réduite conçus pour accéder uniquement aux répertoires ou compétences spécifiques spécifiés dans les configurations de l'agent. Le bac à sable ne contient aucun identifiant ambiant et ne peut pas accéder à d'autres dépôts ni fichiers de votre projet.

  • Délimitation des identifiants MCP : les configurations d'en-tête pour les serveurs Model Context Protocol (MCP), qui contiennent des jetons d'authentification backend, ne sont transmises que lorsque vous accédez aux points de terminaison MCP spécifiques définis dans votre configuration.

Exécution et gestion du cycle de vie

Ces paramètres standards régissent l'exécution et le cycle de vie du bac à sable :

  • Environnement de bac à sable : les agents s'exécutent dans un environnement de bac à sable entièrement géré, à l'aide du harnais Antigravity pour l'orchestration.

  • Valeur TTL (Time to Live) du bac à sable : l'environnement de bac à sable a une valeur TTL standard de sept jours. Chaque nouvelle interaction réinitialise automatiquement ce minuteur pour s'assurer que les agents actifs restent disponibles.

  • Persistance de la configuration de l'agent : le backend stocke de manière persistante les configurations de l'agent, qui restent en place jusqu'à ce que vous envoyiez une requête DELETE explicite à l'API Agents.

  • Collaboration entre agents : plusieurs agents partagent le même environnement lorsque vous fournissez le même env_id lors de l'interaction.

Logiciel pré-installé

Le bac à sable contient un ensemble d'utilitaires Linux standards :

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

L'agent peut installer des packages supplémentaires au moment de l'exécution à l'aide de pip install ou npm install lorsque l'accès au réseau est activé. Ces packages persistent dans l'instantané de l'environnement et restent disponibles pour les interactions qui réutilisent le même env_id.

Architecture d'installation des compétences

Lorsque vous configurez des compétences externes à partir de sources telles que le Skill Registry dans le base_environment.sources d'un agent, ces ressources sont directement associées au système de fichiers du bac à sable. Le système place chaque compétence dans les répertoires cibles spécifiés, en conservant la structure de répertoire d'origine du package de compétences. Cette organisation permet de s'assurer que les fichiers de compétences individuels restent détectables par l'agent.

Exemple de configuration des sources

L'exemple suivant associe trois compétences du Skill Registry :

"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/"
  }
]

Structure du système de fichiers du bac à sable après l'installation

Une fois l'environnement de bac à sable provisionné, les fichiers sont installés et structurés dans le conteneur comme suit :

/ (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/

Outils intégrés au bac à sable

Lorsqu'il s'exécute dans l'environnement géré, l'agent a accès à plusieurs outils par défaut :

Nom de l'outil Description
bash Exécute une commande shell dans le terminal du bac à sable et renvoie le résultat.
file_system Lit, écrit et supprime le contenu d'un fichier, et liste le contenu d'un répertoire.

Étape suivante

Présentation

Découvrez l'API Managed Agents sur Agent Platform, un environnement orienté REST basé sur la configuration pour créer des agents autonomes.

Guide

Découvrez comment créer, mettre à jour, lister, obtenir et supprimer des agents à l'aide de l'API REST.

Guide

Découvrez comment interagir avec les agents au moment de l'exécution, gérer l'état de la session et remplacer dynamiquement les configurations.