API Managed Agents no ambiente de sandbox da Agent Platform

A API Agentes Gerenciados na Agent Platform opera com sandboxes Linux padrão e isolados. 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 prontos para uso.

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

  • Sistema de arquivos persistente:mantém arquivos, lógica de agente e estado de execução com segurança em interações multiturno.

  • 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 allowlist de rede para permitir que o agente acesse recursos da Internet pública ou faça o download de bibliotecas externas.

  • Integrações extensíveis:oferece suporte à importação dinâmica de recursos personalizados, incluindo APIs da Web padrão, servidores do Protocolo de Contexto de Modelo (MCP) ou habilidades do Skill Registry.

Permissões e segurança do sandbox

Para manter os limites de segurança corporativa padrão, o sandbox remoto opera nos 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 exemplos de lista de permissões.

  • Execução de privilégio mínimo:depois que o acesso à rede é ativado, o contêiner não tem credenciais ou permissões administrativas privilegiadas. Ele só pode consultar locais da Internet acessíveis publicamente por padrão.

  • Escopo de dados para montagens do Cloud Storage e do Skill Registry: ao anexar fontes de dados externas do Google Cloud Storage ou do Skill Registry, 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 ambientais 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 configuração.

Execução e gerenciamento do ciclo de vida

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

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

  • Tempo time to live (TTL) do sandbox : o ambiente de sandbox tem um tempo de vida útil (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 do agente: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 Linux padrão:

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

Ao configurar habilidades externas de fontes como o Skill Registry em 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 de diretório do pacote de habilidades original. 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 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/"
  }
]

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 de 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

Saiba 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 dinamicamente.