Managed Agents na API do Gemini: um tutorial prático

Quanto custam os Managed Agents na API do Gemini?

Há muitos componentes envolvidos na precificação dos Gemini Managed Agents, o que dificulta estimativas precisas. O custo é determinado por quatro fatores principais:

1. Uso do modelo (tokens): Você paga pelo número de tokens de entrada e saída processados pelo modelo Gemini subjacente. Note que isso inclui tokens gerados em resultados intermediários. Por exemplo, se o agente gerar um script em Python para criar um relatório, os tokens necessários para esse script também são cobrados.
2. Infraestrutura e taxas de plataforma: Os managed agents rodam no ambiente integrado do Google, o que envolve taxas de serviço pelo uso das ferramentas da plataforma (como o Vertex AI Agent Builder) para gerenciar e implantar os agentes.
3. Context caching: Se os agentes reutilizam com frequência os mesmos dados, é possível usar context caching. Isso normalmente gera uma redução significativa de custo em comparação com a precificação padrão por token.
4. Grounding: Se o agente usa serviços de grounding do Google, como o Google Search ou o Google Maps, eles são cobrados separadamente, geralmente com uma cota gratuita inicial seguida de um custo por 1.000 consultas (tipicamente em torno de US$ 14/1.000 consultas). 

Neste tutorial, vamos construir um agente sobre o agente antigravity-preview-05-2026, alimentado pelo Gemini 3.5 Flash. Os custos de token do Gemini 3.5 Flash são os seguintes:

Como criar Managed Agents na API do Gemini

Neste guia, vamos criar um managed agent usando a API do Gemini e Python. Como os managed agents são um lançamento recente e estão em beta, lembre-se de que alguns detalhes de implementação podem evoluir.

Todo o código que escrevemos neste tutorial está no repositório no GitHub, que também usaremos para compartilhar dados com o agente analista de dados.

Configuração da API

Para criar uma chave de IA, acesse o Google AI Studio e clique em “Create API Key” no canto superior direito.

As chaves de API precisam estar associadas a um projeto no Google Cloud. Você pode selecionar um existente ou criar um novo. Aqui, criei um chamado gemini-managed-agents.

Após criar a chave, copie-a. Em seguida, crie um arquivo chamado .env na pasta onde você vai criar seus agentes e cole no seguinte formato:

GEMINI_API_KEY=<paste_your_api_key_here>

Antes de fechar o Google AI Studio, é preciso configurar o faturamento (billing) na API key recém-criada. Sem isso, suas requisições serão negadas, pois o Google não conseguirá cobrar. Para configurar o faturamento, clique no botão “Set up billing”.

Configuração do ambiente Python

Vamos usar o Anaconda para configurar um ambiente Python para este projeto. Para criar um ambiente com o Anaconda, use o comando:

conda create --name gemini_agents python=3.12 -y

Isso cria um ambiente chamado gemini_agents com Python 3.12. O parâmetro -y apenas confirma automaticamente todas as perguntas durante a criação do ambiente.

Depois, ative o ambiente:

conda activate gemini_agents

Por fim, instale as dependências necessárias. Assim:

pip install google-genai requests python-dotenv

Criando uma interação básica com um managed agent

Agora temos tudo pronto para rodar nosso primeiro agente. Este primeiro agente não fará muita coisa: ele vai apenas instalar o matplotlib e informar a versão instalada.

Veja um passo a passo de como interagir com um managed agent (o código completo está no script simple_interaction.py no repositório):

Primeiro, importamos os pacotes necessários e carregamos a API key do arquivo .env criado anteriormente:

from dotenv import load_dotenv
from google import genai

# Load secure environment variables
load_dotenv()

Em seguida, inicializamos o cliente do Gemini e criamos uma interação com o agente base, atualmente chamado antigravity-preview-05-2026, pedindo que ele instale o matplotlib:

# Initialize the GenAI Client
client = genai.Client()

# Create a basic interaction with a managed agent
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install the matplotlib package, verify its version, and report back.",
    environment="remote"
)

Por fim, obtemos a saída do agente inspecionando as propriedades status, environment_id e output_text:

# Output the status of the agent
print(f"Status: {interaction.status}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output:\n{interaction.output_text}")

Veja o resultado:

Status: completed
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6
Output:
I have successfully installed the matplotlib package in the sandbox environment and verified its installation.

Here are the details:
- **Installation Command:** python3 -m pip install --break-system-packages matplotlib
- **Installed Version:** 3.10.9

Estados do ciclo de vida do sandbox

No exemplo acima, mostramos o identificador do ambiente da interação do managed agent:

Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6

Esse valor é importante, pois representa o identificador do ambiente onde o agente foi executado. As interações dos agentes são armazenadas em um ambiente efêmero que é retido por até 7 dias após a última atividade antes de ser excluído.

O diagrama abaixo ilustra o ciclo de vida do sandbox onde o agente é executado durante uma interação.

Enquanto o ambiente não é excluído, podemos acessá-lo e realizar novas interações usando o identificador do ambiente.

Realizando múltiplas interações

Neste exemplo, mostramos como realizar múltiplas interações. O código completo está no arquivo multiple_interactions.py do repositório.

# First interaction
inter1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script sum.py that adds all integers from 1 to 100.",
    environment="remote"
)

# Second interaction
inter2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=inter1.id, # Passes the conversation history
    environment=inter1.environment_id, # Keeps the same filesystem state
    input="Execute 'sum.py' using Python and display the standard output."
)

# Output the status of the agent
print(f"Output:\n{inter2.output_text}")

Observe que, na segunda interação, adicionamos dois parâmetros:

• previous_interaction_id: o identificador da interação anterior, para que o agente conheça o histórico da conversa.

• environment: o identificador do ambiente, indicando em qual sandbox o agente deve executar.

Compartilhando arquivos com um agente

Não conseguimos construir um agente analista de dados se não pudermos dar acesso aos dados. Existem algumas formas de compartilhar dados com um agente:

• Inline data: carregar o conteúdo do arquivo em uma string e enviá-lo durante a interação.
• Arquivo hospedado: hospedar os dados em uma URL pública e fornecer o link para o agente baixar.
• Repositório no GitHub: fornecer ao agente a URL de um repositório público no GitHub.
• Bucket do Google Cloud: hospedar um arquivo em um bucket do Google Cloud Storage e configurar o projeto para que o agente tenha acesso a esse bucket.

Não vamos explorar todas as opções neste artigo. Vamos mostrar como enviar dados inline carregando um arquivo local em uma string e como compartilhar um repositório do GitHub. A primeira opção é ideal para arquivos locais pequenos (até 1 MB por arquivo, com limite total de 2 MB entre todos os arquivos), enquanto a segunda é mais adequada para arquivos maiores, como datasets.

Compartilhando dados inline

Veja um exemplo de como fornecer dados inline (código completo em inline_example.py):

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                # The file where to store the data in the agent environment
                "target": "/workspace/numbers.txt",
                # Assumes that the file data/numbers.txt exists
                "content": utils.read_text_file("data/numbers.txt")
            }
        ]
    }
)

Os dados são fornecidos pelo parâmetro sources na configuração de environment. O target define o local onde os dados serão armazenados no ambiente do agente. Os arquivos devem ficar na pasta workspace. Neste caso, será um arquivo chamado number.txt. 

O parâmetro content fornece o conteúdo do arquivo. Para fontes inline, é simplesmente uma string, que neste caso lemos com a função read_text_file() no arquivo utils.py.

Compartilhando um repositório do GitHub

Para compartilhar arquivos maiores, podemos fornecer a URL de um repositório do GitHub. Assim:

inter = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Add all the numbers in the /workspace/repository/numbers.txt file.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                "target": "/workspace/repository"
            }
        ]
    }
)

No exemplo acima, o repositório com URL https://github.com/fran-aubry/gemini-agents-tutorial é clonado em uma pasta chamada repository, dentro do workspace do agente.

Baixando o ambiente de um agente

Já aprendemos como interagir com managed agents e como fornecer arquivos para eles. Para criar nosso agente analista de dados, falta aprender a baixar o ambiente do agente. Isso é necessário para acessarmos os gráficos e resultados gerados.

Cada workspace pode ser baixado na URL:

https://generativelanguage.googleapis.com/v1beta/files/environment-<env_id>:download

Onde <env_id> deve ser substituído pelo identificador do ambiente que queremos baixar.

Aqui está uma função em Python que usa o pacote requests para baixar um pacote (esta função faz parte do arquivo utils.py que criamos):

def download_env(env_id, path="environments"):
    download_url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download"
    try:
        request_params = {"alt": "media"}  # Retrieves raw media binary
        request_headers = {"x-goog-api-key": os.environ.get("GEMINI_API_KEY")}
        # Download the environment
        print(f"Downloading environment: {env_id}")
        response = requests.get(
            download_url,
            params=request_params,
            headers=request_headers,
            allow_redirects=True
        )
        response.raise_for_status()
        # Save the compressed workspace archive locally
        archive_name = f"{env_id}.tar"
        output_path = os.path.join(path, archive_name)
        with open(output_path, "wb") as archive_file:
            archive_file.write(response.content)
        print(f"Successfully downloaded workspace snapshot archive: {output_path}")     
    except requests.exceptions.RequestException as error:
        print(f"Failed to download sandbox workspace via HTTP request: {error}")
    except tarfile.TarError as archive_error:
        print(f"Failed to unpack download tarball: {archive_error}")

Construindo um agente analista de dados

Nesta seção, vamos criar um agente que realiza análise de dados. Para testá-lo, vamos usar este dataset da Netflix do Kaggle, que também está armazenado na pasta data do nosso repositório.

Em todos os exemplos anteriores, interagimos com o agente base: antigravity-preview-05-2026. Aqui, vamos primeiro criar um agente usando a função client.agents.create().

Criando um agente

Veja como criar um agente:

agent = client.agents.create(
            id=”data-analyst”,
            base_agent="antigravity-preview-05-2026",
            base_environment={
                "type": "remote",
                "sources": [
                    {
                        "type": "inline", 
                        "target": ".agents/AGENTS.md", 
                        "content": read_text_file(".agents/AGENTS.md")
                    },
                    # Explicitly load the skill
                    {
                        "type": "inline", 
                        "target": ".agents/skills/csv-aggregator/SKILL.md", 
                        "content": read_text_file(".agents/skills/csv-aggregator/SKILL.md")
                    },	
                    {
                        "type": "repository",
                        "source": "https://github.com/fran-aubry/gemini-agents-tutorial",
                        "target": "/workspace/repository"
                    }
                ]
            }

Vamos detalhar cada parâmetro:

• id: define o nome do agente, neste caso data-analyst. Usaremos esse identificador no método client.interactions.create() em vez de antigravity-preview-05-2026, que usamos até agora. 

• base_agent: o agente usado como base. Significa que estamos construindo um agente em cima do agente antigravity-preview-05-2026.

• base_environment: como antes, permite fornecer arquivos ao agente. Fornecemos dois arquivos especiais: .agents/AGENTS.md e .agents/skills/csv-aggregator/SKILL.md. Neles, definimos o comportamento do agente. O arquivo AGENTS.md define o comportamento geral do agente, enquanto o SKILL.md define uma habilidade específica. Também disponibilizamos o repositório para que o agente tenha acesso aos arquivos de dados que queremos analisar.

Entendendo o AGENTS.md

Este arquivo funciona como um system prompt. É o manual principal de instruções do agente. Devemos usá-lo para definir com clareza o papel específico do agente, seus objetivos principais e os limites que ele deve respeitar ao trabalhar. 

Também é o melhor lugar para listar ferramentas ou fontes de dados às quais o agente pode acessar e para fornecer exemplos de como queremos que ele se comunique ou conduza as tarefas. 

Mantendo as instruções simples e bem organizadas nesse arquivo, ajudamos o agente a entender exatamente como se comportar e quais resultados esperamos.

A localização do arquivo no ambiente do agente deve ser .agents/AGENTS.md.

Entendendo o SKILL.md

Os arquivos de skill são usados para equipar o agente com habilidades específicas. Um agente pode ter várias habilidades, e cada uma deve ser descrita em um arquivo SKILL.md localizado em .agents/skills/<skill_name>/SKILL.md, substituindo <skill_name> pelo nome da habilidade.

A estrutura de um arquivo de skill deve ser:

---
name: <skill_name>
description: <description of when to use the skill>
---
<steps on how to perform the task>

Para exemplificar, equipamos o agente data-analyst com uma habilidade chamada csv-aggregator, definida aqui. Essa habilidade é usada quando queremos agrupar linhas de um CSV por alguma coluna enquanto somamos outra coluna. 

No caso do dataset da Netflix, se quisermos saber os gêneros com mais visualizações, agrupamos as linhas por Genre e somamos os valores da coluna Viewership. Este arquivo de skill explica ao agente como realizar essa tarefa.

Carregando o agente

Como os agentes são persistentes, se tentarmos criar o agente duas vezes, receberemos um erro. Por isso, criamos a função load_or_create_agent() no arquivo utils.py. Essa função tenta criar o agente e, se ele já existir, o carrega usando client.agents.load().

Juntando tudo

Agora que temos um agente analista de dados, é hora de testá-lo pedindo que analise os gêneros da Netflix. 

Começamos como antes: importando as bibliotecas, carregando a API key e inicializando o cliente:

from dotenv import load_dotenv
from google import genai
import utils

load_dotenv()
client = genai.Client()

Depois criamos (ou carregamos, se não for a primeira execução do script) o agente data-analyst usando a função utils.load_or_create_agent():

data_analyst = utils.load_or_create_agent(client, "data-analyst")
print(f"Agent '{data_analyst.id}' initialized.")

Em seguida, podemos interagir com o agente da mesma forma que fizemos antes. A única diferença é que, no parâmetro agent, agora fornecemos o nosso agente em vez de antigravity-preview-05-2026.

Começamos pedindo para instalar o pacote matplotlib:

inter1 = client.interactions.create(
    agent=data_analyst.id,
    input="Install the matplotlib package.",
    environment="remote"
)

Observe que, como o ambiente já foi configurado no nível do agente, não precisamos mais fornecer arquivos, então basta passar a string ”remote”.

Depois, pedimos para usar a ferramenta csv-aggregator para analisar os dados da Netflix por gênero e ver quais são os mais assistidos:

inter2 = client.interactions.create(
    agent=data_analyst.id,
    input="Use the csv-aggregator to plot the top 10 genres from /workspace/repository/data/netflix.csv in terms of viewership",
    environment=inter1.environment_id
)

Note que fornecemos o identificador do ambiente da interação anterior para que o agente continue trabalhando em cima dele.

Por fim, pedimos que o agente gere o gráfico executando o script genres.py criado na etapa anterior (o arquivo SKILL.md instrui o agente a criar esse script):

inter3 = client.interactions.create(
    agent=data_analyst.id,
    input="Execute the genres.py script using python.",
    environment=inter2.environment_id
)

Após essa interação, o gráfico deve ter sido criado. Podemos obtê-lo localmente baixando o ambiente:

utils.download_env(inter3.environment_id)

Veja o resultado:

O código completo da interação com o agente está em analyze_netflix_genres.py.

Conclusão

Conseguir criar agentes complexos com uma única chamada de API, sem depender de uma infraestrutura de computação em nuvem complexa para montar um sandbox, é algo muito poderoso. Essa capacidade facilita bastante a criação de agentes robustos sem se preocupar com o ambiente de execução.

Neste tutorial, cobrimos os fundamentos dos Gemini Managed Agents, mas não criamos agentes realmente complexos. Recomendo que você explore mais e continue construindo em cima desta base para afiar suas habilidades.