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 prontos para uso.

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 com segurança em interações de várias rodadas.

• 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 de forma dinâmica, 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 de acordo 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 acesso à rede para ver exemplos de listas de permissão.

• 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 Skill Registry:quando você anexa 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. A sandbox não contém credenciais ambientais e não pode acessar outros repositórios ou arquivos no seu projeto.

• Escopo das 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 arnês Antigravity para orquestração.

• Time to live (TTL) do sandbox: o ambiente de sandbox tem um time to live (TTL) padrão de sete 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 de forma persistente as configurações do agente, que permanecem até que você envie uma solicitação DELETE explícita para a API Agents.

• Colaboração entre 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:

O agente pode instalar outros pacotes durante a 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 reutilizando 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 da sandbox. O sistema coloca cada habilidade nos diretórios de destino especificados, preservando a estrutura do diretório original 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 da 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:

A seguir