Construindo Agentes Gerenciados com a Gemini API: Um Guia Completo para Desenvolvedores

Agentes autônomos que raciocinam, escrevem e executam código, navegam na web e gerenciam arquivos antes exigiam semanas de trabalho de infraestrutura. Com o lançamento de Agentes Gerenciados na Gemini API, o Google condensou essa configuração em uma única chamada de API. Uma solicitação cria um sandbox Linux seguro e efêmero hospedado pelo Google — e um agente pronto para fazer trabalho real dentro dele.

Este guia cobre tudo o que os desenvolvedores precisam saber: como funciona o agente Antigravity, como construir e implantar agentes personalizados, como bifurcar ambientes para execuções reproduzíveis, como restringir rede e credenciais e como a nova Gemini CLI se encaixa em um fluxo de trabalho agent-first.

O que São os Agentes Gerenciados da Gemini API?

Agentes Gerenciados são a nova primitive (primitiva) para desenvolvedores do Google para agentes autônomos de IA na Gemini API. Em vez de costurar você mesmo a lógica de orquestração, os ambientes de execução de código, a infraestrutura de chamadas de ferramentas e os controles de segurança, a API cuida de tudo.

Uma única chamada à Interactions API provisiona um ambiente Linux isolado, inicia um agente alimentado por Gemini e executa sua tarefa de ponta a ponta. O agente pode raciocinar e planejar, chamar ferramentas, executar código, gerenciar arquivos e navegar na web — tudo dentro de um runtime seguro que o Google gerencia para você.

Duas superfícies tornam isso possível:

• A Interactions API — a interface de runtime. Envie uma tarefa e receba de volta um agente que raciocina e age.
• A Agents API — o plano de controle. Defina, registre e gerencie agentes nomeados com instruções, ferramentas, habilidades e configurações de ambiente personalizadas.

O Agente Antigravity: Um Agente de Uso Geral Pronto para Usar

O primeiro agente gerenciado de uso geral na Gemini API é o Antigravity. Ele é alimentado pelo Gemini 3.5 Flash e executa no mesmo harness por trás do Antigravity IDE e de outros produtos de agente first-party do Google. Antes do Antigravity, o Deep Research era o único agente gerenciado disponível — um agente especializado para fluxos de trabalho de pesquisa em várias etapas.

O Antigravity é o equivalente de uso geral: uma única chamada de API que provisiona um ambiente Linux remoto e começa a trabalhar.

O que o Antigravity Pode Fazer

Dentro do seu sandbox gerenciado, o agente Antigravity pode:

• Raciocinar e planejar usando o harness de agente do Gemini
• Executar código e gerenciar arquivos em um ambiente Linux seguro
• Navegar na web para obter e processar dados em tempo real
• Usar ferramentas, incluindo busca na web, execução de código e I/O de arquivos

Sua Primeira Chamada à API do Antigravity

Aqui está a invocação mais simples possível do Antigravity — uma chamada de API que provisiona um ambiente remoto, executa o agente e retorna a saída:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # Remote Linux environment hosted by Google
)

print(interaction.output_text)

É só isso. Sem configuração de container. Sem código de sandboxing. Sem estrutura para chamadas de ferramentas. O Google cuida de tudo.

Ambientes Persistentes: Agentes Multiturno com Estado

Os ambientes persistem entre chamadas. A primeira interação provisiona um sandbox e retorna um environment_id. Passe esse ID nas solicitações seguintes e o agente continua com todos os arquivos, pacotes e estado exatamente do ponto em que a chamada anterior terminou.

# First call — provisions a new remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment="remote",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
)

# Second call — resumes in the same environment with full state intact
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using javascript and html",
)

print(interaction_2.output_text)

Esse comportamento com estado é o que torna fluxos de trabalho em várias etapas práticos. Um agente que instala pacotes, escreve arquivos e executa análises em uma chamada pode transferir tudo isso perfeitamente para a chamada seguinte — sem nova configuração, sem novo download, sem nova execução.

Os ambientes também aceitam dados externos na inicialização: repositórios Git, objetos do Google Cloud Storage ou conteúdo inline podem ser montados no sandbox antes de o agente começar a trabalhar.

Construindo Agentes Gerenciados Personalizados

O agente Antigravity cobre bem tarefas de uso geral. Mas casos de uso de produção quase sempre exigem comportamento personalizado — instruções específicas, skills (habilidades) de domínio, ferramentas proprietárias ou fontes de dados curadas. É para isso que serve a Agents API.

Os Agentes Gerenciados da Gemini permitem agrupar instruções, skills, ferramentas e um ambiente em um agente nomeado que você invoca por ID. Em vez de escrever código complexo de orquestração, você define tudo de forma declarativa — em arquivos markdown como AGENTS.md e SKILL.md — e registra tudo uma única vez.

Definindo um Agente a partir de Fontes

Crie um agente do zero especificando instruções do sistema e fontes. As fontes podem ser repositórios GitHub, caminhos do Google Cloud Storage ou conteúdo inline. A plataforma provisiona um sandbox novo com seus arquivos a cada invocação.

agent = client.agents.create(
    name="data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "You are a data analyst agent..."
            },
            {
                "type": "inline",
                "target": ".agents/slide-maker/SKILL.md",
                "content": "Instructions for creating slides..."
            },
            {
                "type": "github",
                "source": "https://github.com/my-org/data-templates.git",
                "target": "/workspace/"
            },
            {
                "type": "gcs",
                "source": "gs://my-bucket/analysis-skills/",
                "target": "/.agents/skills/"
            },
        ]
    }
)

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)

print(result.output_text)

Depois de registrado, data-analyst é um agente durável que você pode invocar pelo nome. Cada execução provisiona um ambiente limpo com sua configuração exata — sem vazamento de estado entre invocações.

Bifurcando um Ambiente Existente

Às vezes, o caminho mais rápido para um agente personalizado é a iteração. Comece trabalhando de forma interativa com o agente base Antigravity — instale pacotes, crie templates, configure o ambiente — e depois bifurque esse snapshot do ambiente em um agente nomeado reutilizável.

# Step 1: Iterate with the base agent in a remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# Step 2: Create a new agent from the existing environment snapshot
agent = client.agents.create(
    name="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a data analyst that creates slide presentations.",
    base_environment=interaction.environment_id,
)

Depois de salvo, cada invocação subsequente de my-data-analyst é bifurcada a partir desse snapshot base — começando sempre de um estado limpo e pré-configurado.

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote"
)

print(result.output_text)

O padrão de bifurcar e registrar é particularmente eficaz para agentes que dependem de uma configuração pesada: grafos de dependência complexos, grandes artefatos de modelo ou templates pré-compilados que demorariam demais para serem reconstruídos a cada invocação.

Rede Segura e Proxy de Credenciais

Agentes de produção quase sempre precisam acessar serviços externos — GitHub, APIs internas, registries de pacotes — e quase sempre precisam fazer isso sem expor credenciais sensíveis dentro do sandbox. Os Agentes Gerenciados lidam com ambos com um egress proxy configurável.

A configuração de rede atende a dois propósitos:

1. Allowlists restringem conexões de saída a domínios explicitamente permitidos, impedindo que um agente acesse serviços externos não intencionais.
2. Header transforms injetam credenciais no lado do servidor, de modo que tokens de API e secrets nunca sejam passados para o próprio ambiente do sandbox.

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

Nesta configuração, o agente só pode acessar api.github.com e pypi.org. Qualquer tentativa de conexão com outro domínio é bloqueada. As solicitações ao GitHub são automaticamente transformadas para incluir o header Authorization — o código do sandbox nunca vê o token diretamente.

Essa arquitetura é essencial para agentes implantados em repositórios de código internos, APIs proprietárias ou qualquer ambiente em que a higiene de credenciais seja um requisito de compliance.

A Gemini API CLI: Uma Experiência de Desenvolvimento Agent-First

Além da API, o Google lançou uma Gemini API CLI experimental e open-source, projetada para que agentes de codificação interajam com a Gemini API de forma estruturada e amigável a agentes.

# Run a prompt against any model
gemini-api run "What is the capital of France?"

# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# Scaffold, test, and deploy an agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

O fluxo agents init / agents test / agents create reflete uma mudança na forma como o Google espera que os desenvolvedores construam sobre a Gemini API: defina o comportamento do agente em arquivos, teste localmente, implante como um agente gerenciado nomeado — o mesmo padrão familiar das ferramentas de infraestrutura como código.

Ferramentas Complementares

Além da CLI, duas adições mantêm os agentes de codificação atualizados com a Gemini API:

• Gemini API Docs MCP server — fornece acesso em tempo real à documentação da Gemini, SDKs e informações de modelos via MCP. Agentes de codificação podem consultar a documentação diretamente em vez de depender de dados de treinamento desatualizados.
• gemini-interactions-api Skill — injeta padrões e boas práticas da Interactions API automaticamente no contexto de um agente, para que agentes construídos com os Agentes Gerenciados da Gemini escrevam código de interação idiomático desde o início.

Por Que os Agentes Gerenciados Importam para Casos de Uso em Produção

A aposta central por trás dos Agentes Gerenciados é que a maior parte do trabalho difícil no desenvolvimento de agentes não é o modelo — é a infraestrutura ao redor dele. Sandboxing, integração de ferramentas, gerenciamento de credenciais, reprodutibilidade de ambientes e segurança de rede são problemas que toda equipe que entrega agentes precisa resolver por conta própria. Os Agentes Gerenciados tornam isso um problema do Google.

Essa mudança tem implicações práticas para implantações em produção:

Execuções reproduzíveis. Ambientes bifurcados garantem que cada invocação do agente comece a partir de uma base idêntica — sem deriva de dependências, sem contaminação de estado entre execuções.

Superfície de ataque reduzida. Credenciais nunca entram no sandbox. A saída de rede é controlada por allowlist. O ambiente de execução é efêmero e isolado. Esses não são passos opcionais de hardening; são o padrão.

Iteração mais rápida. O fluxo de bifurcar e registrar permite que equipes experimentem de forma interativa, estabilizem uma configuração e a promovam para um agente nomeado — sem reescrever a infraestrutura entre o protótipo e a produção.

Compatibilidade com frameworks. Os Agentes Gerenciados funcionam com os frameworks de orquestração que as equipes já usam. Entre os parceiros de lançamento estão Vercel AI SDK, LiteLLM, Agno, Eigent e LlamaIndex — então os fluxos de trabalho existentes não exigem uma reescrita completa para aproveitar a infraestrutura gerenciada.

Agentes Gerenciados para Empresas

Para empresas que precisam executar agentes gerenciados personalizados em escala, o Google oferece a Gemini Enterprise Agent Platform — as mesmas APIs, com governança adicional, visibilidade centralizada e controles de política em nível organizacional.

Os Agentes Gerenciados na Gemini API estão atualmente disponíveis em preview. Equipes corporativas podem acessar as mesmas primitivas de agentes gerenciados por meio da Enterprise Agent Platform, com controles adicionais para auditoria, enforcement de DLP e governança entre equipes.

Principais Conclusões

O lançamento dos Agentes Gerenciados da Gemini API oferece aos desenvolvedores três coisas que antes eram difíceis de reunir: um agente geral competente (Antigravity) pronto para uso imediatamente, uma API limpa para definir e implantar agentes personalizados com segurança de nível de produção e uma experiência de desenvolvedor — CLI, servidor MCP, Skills — projetada para agentes que constroem agentes.

As decisões de infraestrutura são sólidas: ambientes persistentes, bifurcação de ambientes, egress allowlists e injeção de credenciais no lado do servidor são as primitivas certas para implantações de agentes em produção. A CLI open-source e o Skill refletem o reconhecimento do Google de que a experiência do desenvolvedor para agentes é tão importante quanto os recursos do modelo por baixo.

Para equipes que estão construindo sobre a plataforma agnóstica de modelos da Eigent, os Agentes Gerenciados da Gemini representam um alvo de implantação atraente — um que combina bem com a capacidade da Eigent de rotear tarefas de forma inteligente entre provedores de modelos enquanto o Google cuida da camada de execução em sandbox.

Para começar, experimente o agente Antigravity no AI Studio Playground, leia a documentação de Agentes Gerenciados e instale o Python SDK ou o JavaScript SDK.

Perguntas Frequentes

O que são os Agentes Gerenciados da Gemini API?

Os Agentes Gerenciados da Gemini API são agentes autônomos de IA que executam dentro de ambientes Linux isolados e hospedados pelo Google. Uma única chamada à Interactions API provisiona o sandbox, inicia um agente alimentado por Gemini e executa sua tarefa — incluindo execução de código, navegação na web e gerenciamento de arquivos — sem que você precise configurar nenhuma infraestrutura.

O que é o agente Antigravity?

Antigravity é o agente gerenciado de uso geral do Google na Gemini API, alimentado pelo Gemini 3.5 Flash. Ele pode raciocinar e planejar, executar código, gerenciar arquivos e navegar na web dentro de um ambiente Linux remoto seguro. Ele usa o mesmo harness de agente que alimenta o Antigravity IDE e outros produtos de agente first-party do Google.

Como funcionam os ambientes persistentes?

A primeira chamada de interação com environment="remote" provisiona um novo sandbox e retorna um environment_id. Passar esse ID nas chamadas subsequentes retoma o agente no mesmo ambiente — com todos os arquivos, pacotes instalados e estado preservados. Isso permite fluxos de trabalho com estado e em várias etapas sem nova configuração entre chamadas.

Como construo um agente gerenciado personalizado?

Use a Agents API para definir um agente nomeado especificando um agente base, instruções e fontes (repositórios GitHub, objetos GCS ou conteúdo inline). Depois de registrado, invoque seu agente pelo nome via Interactions API. Como alternativa, itere interativamente com o Antigravity e depois bifurque o ambiente resultante em um agente nomeado usando client.agents.create() com base_environment apontando para um environment_id existente.

Como funciona o proxy de credenciais?

O egress proxy do agente gerenciado fica entre o sandbox e a internet. Você configura uma allowlist de domínios permitidos e, opcionalmente, regras de transform de headers por domínio. O proxy injeta headers (como Authorization: Bearer <token>) nas solicitações de saída correspondentes automaticamente — assim, o código do sandbox nunca tem acesso direto aos valores do token.

Quais frameworks são compatíveis com os Agentes Gerenciados da Gemini?

Os Agentes Gerenciados da Gemini funcionam com Vercel AI SDK, LiteLLM, Agno, Eigent e LlamaIndex já no lançamento. A Interactions API é baseada em REST, então qualquer framework de orquestração capaz de fazer HTTP pode integrá-la.

O que é a Gemini API CLI?

A Gemini API CLI é uma ferramenta experimental open-source projetada para que agentes de codificação interajam com a Gemini API. Ela suporta execução de prompts, geração de imagens e áudio e gerenciamento do ciclo de vida completo de agentes gerenciados — init, test, create e run — pela linha de comando.

Os Agentes Gerenciados da Gemini estão disponíveis para uso corporativo?

Sim. As mesmas APIs de Agentes Gerenciados estão disponíveis por meio da Gemini Enterprise Agent Platform, com controles adicionais de governança, visibilidade centralizada, enforcement de DLP e gerenciamento de políticas organizacionais. Os Agentes Gerenciados na Gemini API estão atualmente disponíveis em preview.