API Managed Agents no ambiente de sandbox da Agent Platform

A API Managed Agents na Agent Platform opera com sandboxes padrão e isolados do Linux. Nesse contêiner de execução seguro e totalmente gerenciado, os agentes personalizados podem raciocinar, planejar fluxos de trabalho, executar comandos bash e ler ou gravar arquivos de forma imediata.

Cada ambiente de sandbox oferece os seguintes sistemas e controles principais:

  • Sistema de arquivos persistente: mantém arquivos, lógica do agente e estado de execução de forma segura em interações de vários turnos.

  • Terminal Bash: oferece um ambiente seguro para executar comandos de terminal, scripts personalizados e processar arquivos locais.

  • Isolamento de rede: desativado por padrão. É possível declarar explicitamente uma rede allowlist para permitir que o agente acesse recursos públicos da Internet ou faça o download de bibliotecas externas.

  • Integrações extensíveis: permite importar recursos personalizados dinamicamente, incluindo APIs da Web padrão, servidores do Protocolo de Contexto de Modelo (MCP) ou habilidades do Registro de Habilidades.

Permissões e segurança do sandbox

Para manter os limites de segurança corporativos padrão, o sandbox remoto opera com os seguintes modelos de permissão:

  • Isolamento de rede: por padrão, o sandbox opera sem acesso à rede externa. Ative explicitamente a conectividade definindo uma lista de permissões de domínio na configuração do ambiente. Consulte Configurar o acesso à rede para ver exemplos de lista de permissões.

  • Execução com privilégio mínimo: quando o acesso à rede é ativado, o contêiner não tem credenciais ou permissões administrativas privilegiadas. Por padrão, ele só pode consultar locais da Internet acessíveis ao público.

  • Escopo de dados para montagens do Cloud Storage e do registro de habilidades: ao anexar fontes de dados externas do Cloud Storage ou do registro de habilidades, o ambiente recebe tokens de autorização com escopo reduzido projetados para acessar apenas os diretórios ou habilidades específicos especificados nas configurações do agente. O sandbox não contém credenciais de ambiente e não pode acessar outros repositórios ou arquivos no seu projeto.

  • Escopo de credenciais do MCP: as configurações de cabeçalho para servidores do Protocolo de Contexto de Modelo (MCP), que contêm tokens de autenticação de back-end, são transmitidas apenas ao acessar os endpoints específicos do MCP definidos na sua configuração.

Execução e gerenciamento do ciclo de vida

Estes parâmetros padrão controlam a execução e o ciclo de vida do sandbox:

  • Ambiente de sandbox: os agentes são executados em um ambiente de sandbox totalmente gerenciado, usando o harness Antigravity para orquestração.

  • Time to live (TTL) do sandbox: o ambiente de sandbox tem um time to live (TTL) padrão de 7 dias. Cada nova interação redefine automaticamente esse timer para garantir que os agentes ativos permaneçam disponíveis.

  • Persistência da configuração do agente: o back-end armazena as configurações do agente de forma persistente, e elas permanecem até que você envie uma solicitação DELETE explícita para a API Agents.

  • Colaboração de agentes: vários agentes compartilham o mesmo ambiente quando você fornece o mesmo env_id durante a interação.

Software pré-instalado

O sandbox contém um conjunto de utilitários padrão do Linux:

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

O agente pode instalar outros pacotes no ambiente de execução usando pip install ou npm install quando o acesso à rede está ativado. Esses pacotes persistem no snapshot do ambiente e permanecem disponíveis para interações que reutilizam o mesmo env_id.

Arquitetura de montagem de habilidades

Quando você configura habilidades externas de fontes como o registro de habilidades no base_environment.sources de um agente, esses recursos são anexados diretamente ao sistema de arquivos do sandbox. O sistema coloca cada habilidade nos diretórios de destino especificados, preservando a estrutura original do diretório do pacote de habilidades. Essa organização ajuda a garantir que os arquivos de habilidades individuais permaneçam detectáveis pelo agente.

Exemplo de configuração de fontes

O exemplo a seguir anexa três habilidades do registro de habilidades:

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

Estrutura do sistema de arquivos do sandbox após a montagem

Depois que o ambiente de sandbox é provisionado, os arquivos são montados e estruturados no contêiner da seguinte maneira:

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

Ferramentas integradas do Sandbox

Ao ser executado no ambiente gerenciado, o agente tem acesso a várias ferramentas padrão:

Nome da ferramenta Descrição
bash Executa um comando shell no terminal do sandbox e retorna a saída.
file_system Lê, grava e exclui o conteúdo de um arquivo e lista o conteúdo de um diretório.

A seguir

Visão geral

Aprenda mais sobre a API Agentes Gerenciados na Agent Platform, um ambiente orientado por configuração e com foco em REST para criar agentes autônomos.

Guia

Saiba como criar, atualizar, listar, receber e excluir agentes usando a API REST.

Guia

Saiba como interagir com agentes no ambiente de execução, gerenciar o estado da sessão e substituir configurações de forma dinâmica.