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 de manière prête à 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 des 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 un réseau allowlist 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 de Skill Registry.

Autorisations et sécurité du bac à sable

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

  • Isolation 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 domaines dans la configuration de votre environnement. Consultez Configurer l'accès réseau pour obtenir des exemples de listes d'autorisation.

  • Exécution avec privilèges minimum : une fois l'accès 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 publiquement.

  • Définition du champ d'application des données pour les montages Cloud Storage et Skill Registry : lorsque vous associez des sources de données externes depuis Cloud Storage ou Skill Registry, l'environnement reçoit des jetons d'autorisation à champ d'application réduit conçus pour n'accéder qu'aux répertoires ou compétences spécifiques spécifiés dans les configurations de l'agent. Le bac à sable ne contient pas d'identifiants ambiants et ne peut pas accéder à d'autres dépôts ou fichiers de votre projet.

  • Champ d'application des identifiants MCP : les configurations d'en-tête des serveurs MCP (Model Context Protocol), qui contiennent des jetons d'authentification de backend, ne sont transmises que lors de l'accès 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é, en utilisant le 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 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 sont conservées 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 sont conservés dans l'instantané de l'environnement et restent disponibles pour les interactions réutilisant le même env_id.

Architecture de montage de compétences

Lorsque vous configurez des compétences externes à partir de sources telles que le registre de compétences dans le base_environment.sources d'un agent, ces ressources sont associées directement au système de fichiers du bac à sable. Le système place chaque compétence dans les répertoires cibles spécifiés, en préservant la structure de répertoires du package de compétences d'origine. 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 registre des compétences :

"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 du 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.

Étapes suivantes

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, modifier, 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 les configurations de manière dynamique.