API Managed Agents nell'ambiente sandbox di Agent Platform

L'API Managed Agents su Agent Platform funziona con sandbox Linux standard e isolate. In questo container di esecuzione sicuro e completamente gestito, gli agenti personalizzati possono ragionare, pianificare flussi di lavoro, eseguire comandi bash e leggere o scrivere file out-of-the-box.

Ogni ambiente sandbox fornisce i seguenti sistemi e controlli principali:

  • File system persistente: archivia in modo sicuro file, logica dell'agente e stato di esecuzione in interazioni multi-turno.

  • Terminale Bash: fornisce un ambiente sicuro per l'esecuzione dei comandi del terminale, l'esecuzione di script personalizzati e l'elaborazione di file locali.

  • Isolamento di rete:disattivato per impostazione predefinita. Puoi dichiarare esplicitamente una rete allowlist per consentire all'agente di accedere alle risorse internet pubbliche o scaricare librerie esterne.

  • Integrazioni estensibili: supporta l'importazione dinamica di funzionalità personalizzate, tra cui API web standard, server Model Context Protocol (MCP) o skill di Skill Registry.

Autorizzazioni e sicurezza della sandbox

Per mantenere i confini di sicurezza standard dell'enterprise, la sandbox remota opera in base ai seguenti modelli di autorizzazione:

  • Isolamento di rete:per impostazione predefinita, la sandbox funziona senza accesso alla rete esterna. Attiva esplicitamente la connettività impostando una lista consentita di domini nella configurazione dell'ambiente. Consulta Configura l'accesso alla rete per esempi di liste consentite.

  • Esecuzione con privilegi minimi:una volta abilitato l'accesso alla rete, il container non dispone di credenziali o autorizzazioni amministrative privilegiate. Per impostazione predefinita, può eseguire query solo su posizioni internet accessibili pubblicamente.

  • Definizione dell'ambito dei dati per i montaggi di Cloud Storage e Skill Registry:quando colleghi origini dati esterne da Google Cloud Storage o Skill Registry, l'ambiente riceve token di autorizzazione con ambito ridotto progettati per accedere solo alle directory o alle skill specifiche indicate nelle configurazioni dell'agente. La sandbox non contiene credenziali ambientali e non può accedere ad altri repository o file nel tuo progetto.

  • Definizione dell'ambito delle credenziali MCP: le configurazioni delle intestazioni per i server Model Context Protocol (MCP), che contengono token di autenticazione backend, vengono trasmesse solo quando si accede agli endpoint MCP specifici definiti nella configurazione.

Gestione dell'esecuzione e del ciclo di vita

Questi parametri standard regolano l'esecuzione e il ciclo di vita della sandbox:

  • Ambiente sandbox: gli agenti vengono eseguiti con un ambiente sandbox completamente gestito, utilizzando l'imbracatura Antigravity per l'orchestrazione.

  • Durata (TTL) della sandbox: l'ambiente sandbox ha una durata (TTL) standard di 7 giorni. Ogni nuova interazione reimposta automaticamente questo timer per garantire che gli agenti attivi rimangano disponibili.

  • Persistenza della configurazione dell'agente: il backend archivia in modo persistente le configurazioni dell'agente, che rimangono fino a quando non invii una richiesta DELETE esplicita all'API Agents.

  • Collaborazione tra agenti: più agenti condividono lo stesso ambiente quando fornisci lo stesso env_id durante l'interazione.

Software preinstallato

La sandbox contiene un insieme di utilità Linux standard:

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

L'agente può installare pacchetti aggiuntivi in fase di runtime utilizzando pip install o npm install quando l'accesso alla rete è abilitato. Questi pacchetti persistono nello snapshot dell'ambiente e rimangono disponibili per le interazioni che riutilizzano lo stesso env_id.

Architettura di montaggio delle skill

Quando configuri skill esterne da origini come il registro delle skill all'interno di base_environment.sources di un agente, queste risorse vengono allegate direttamente al file system sandbox. Il sistema inserisce ogni skill nelle directory di destinazione specificate, preservando la struttura originale della directory del pacchetto di skill. Questa organizzazione contribuisce a garantire che i singoli file delle skill rimangano rilevabili dall'agente.

Configurazione delle origini di esempio

L'esempio seguente associa tre skill dal registro delle skill:

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

Struttura del file system della sandbox dopo il montaggio

Dopo il provisioning dell'ambiente sandbox, i file vengono montati e strutturati all'interno del container come segue:

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

Strumenti integrati della sandbox

Quando viene eseguito nell'ambiente gestito, l'agente ha accesso a diversi strumenti predefiniti:

Nome strumento Descrizione
bash Esegue un comando shell nel terminale della sandbox e restituisce l'output.
file_system Legge, scrive ed elimina i contenuti di un file ed elenca i contenuti di una directory.

Passaggi successivi

Panoramica

Scopri l'API Managed Agents su Agent Platform, un ambiente basato sulla configurazione e REST-first per la creazione di agenti autonomi.

Guida

Scopri come creare, aggiornare, elencare, ottenere ed eliminare gli agenti utilizzando l'API REST.

Guida

Scopri come interagire con gli agenti in fase di runtime, gestire lo stato della sessione ed eseguire l'override dinamico delle configurazioni.