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 immediatamente.

Ogni ambiente sandbox fornisce i seguenti sistemi e controlli di base:

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

  • Terminale Bash:fornisce un ambiente sicuro per l'esecuzione di 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 allowlist di rete 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 da Skill Registry.

Autorizzazioni e sicurezza della sandbox

Per mantenere i limiti di sicurezza aziendale standard, la sandbox remota opera con i seguenti modelli di autorizzazione:

  • Isolamento di rete:per impostazione predefinita, la sandbox funziona senza accesso alla rete esterna. Abilita esplicitamente la connettività impostando una allowlist di domini nella configurazione dell'ambiente. Per esempi di allowlist, consulta Configurare l'accesso alla rete.

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

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

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

Esecuzione e gestione 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'Antigravity Harness 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 permanente le configurazioni dell'agente, che rimangono fino a quando non invii una richiesta DELETE esplicita all'API Agents.

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

Software preinstallato

La sandbox contiene un set di utilità Linux standard:

Categoria Pacchetti/strumenti
Strumenti UNIX
  • 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 rimangono 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 Skill Registry all'interno di base_environment.sources di un agente, queste risorse vengono collegate direttamente al file system della sandbox. Il sistema inserisce ogni skill nelle directory di destinazione specificate, mantenendo la struttura della directory del pacchetto di skill originale. Questa organizzazione consente di garantire che i singoli file di skill rimangano rilevabili dall'agente.

Configurazione delle origini di esempio

L'esempio seguente collega tre skill da 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/"
  }
]

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 della 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 REST-first basato sulla configurazione 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.