Gemini API — guia completo de agentes gerenciados: background tasks, MCP remoto e funções customizadas em 2026

A Gemini Interactions API chegou em 2025 com uma proposta diferente das outras plataformas de agentes: em vez de o desenvolvedor montar a infraestrutura de raciocínio, memória e ferramentas, o Google gerencia tudo isso em um sandbox isolado na nuvem. Em julho de 2026, o Google expandiu essa plataforma com quatro novos recursos que fecham as lacunas que impediam o uso em produção real. Este guia explica cada um deles com exemplos de código e casos de uso práticos.

O que são Managed Agents na Gemini API — e por que importam

Managed Agents são agentes de IA onde a infraestrutura é gerenciada pelo Google. O desenvolvedor chama um único endpoint da Gemini Interactions API com uma instrução de alto nível — "analise este relatório e identifique as anomalias" — e o Gemini cuida de:

A diferença em relação a frameworks como LangChain, CrewAI ou n8n é que não há infraestrutura para montar: sem orquestração manual de ferramentas, sem gestão de memória, sem configuração de ambiente. O tradeoff é menor controle sobre o comportamento interno — o que é aceitável para a maioria dos casos de uso de negócio.

Arquitetura: como o sandbox isolado funciona

Cada sessão de Managed Agent roda em um ambiente isolado na infraestrutura do Google. Esse ambiente tem um identificador único — o environment_id — que persiste entre chamadas consecutivas. Isso significa que o agente "lembra" do que fez antes: arquivos criados em uma chamada continuam disponíveis na próxima, pacotes instalados permanecem ativos, e repositórios clonados permanecem no sistema de arquivos.

A chamada básica tem três componentes obrigatórios: o modelo (qual versão do Gemini usar), as ferramentas (quais capacidades o agente pode usar) e o prompt (a instrução de alto nível). O resultado chega como um stream de eventos que registra o raciocínio e as ações do agente em tempo real.

const response = await ai.interactions.create({
  model: "gemini-2.5-pro",
  tools: [{ googleSearch: {} }, { codeExecution: {} }],
  prompt: "Analise o arquivo vendas_junho.csv e gere um relatório
           com as 5 anomalias mais relevantes"
});

Background execution — agentes que não travam sua aplicação

Este é o recurso mais importante para uso em produção. Sem background execution, um agente que precisa de 10 minutos para processar um arquivo grande mantém uma conexão HTTP aberta por todo esse tempo. Qualquer instabilidade de rede derruba a execução. Em ambientes serverless (Vercel, Cloudflare Workers), o timeout máximo geralmente é de 30 segundos — insuficiente para tarefas complexas.

Com background: true, o fluxo muda completamente:

// 1. Dispara a tarefa — retorna ID imediatamente
const job = await ai.interactions.create({
  model: "gemini-2.5-pro",
  tools: [{ codeExecution: {} }],
  background: true,
  prompt: "Processe os 50.000 registros do arquivo e gere
           relatório de inadimplência por região"
});

const jobId = job.id; // salve esse ID

// 2. Verifique o status quando quiser
const status = await ai.interactions.get(jobId);
// status.state: "running" | "completed" | "failed"

// 3. Quando completed, pegue o resultado
if (status.state === "completed") {
  console.log(status.result);
}

Casos de uso ideais para background execution

Qualquer tarefa que leve mais de 30 segundos é candidata: análise de planilhas grandes (10k+ linhas), geração de relatórios consolidados, processamento de lotes de documentos PDF, comparativos de dados históricos, ou qualquer pipeline de dados que envolva múltiplas etapas de transformação.

MCP remoto — conectando o agente aos seus sistemas internos

MCP (Model Context Protocol) é um padrão aberto para expor ferramentas e dados para modelos de IA. Em vez de escrever um adaptador customizado para cada sistema interno — banco de dados, CRM, ERP, API proprietária — você expõe essas capacidades via um servidor MCP e o agente as acessa diretamente.

Com o MCP remoto na Gemini API, o agente se conecta ao seu servidor MCP a partir do sandbox seguro do Google — sem que você precise abrir sua rede para tráfego externo de forma irrestrita:

const response = await ai.interactions.create({
  model: "gemini-2.5-pro",
  tools: [
    { googleSearch: {} },
    {
      mcp_server: {
        url: "https://meu-servidor-mcp.empresa.com/sse",
        headers: { "Authorization": `Bearer ${token}` }
      }
    }
  ],
  prompt: "Consulte o histórico de compras do cliente ID 4521
           e identifique oportunidades de upsell"
});

Funções customizadas — lógica de negócio dentro do agente

Enquanto o MCP remoto conecta o agente a sistemas externos, as funções customizadas permitem adicionar lógica de negócio local que roda no cliente — não no sandbox do Google. O agente decide quando chamar a função, mas a execução acontece no seu servidor, com acesso ao seu contexto local.

O mecanismo usa o estado requires_action: quando o agente decide que precisa de uma função customizada, ele pausa e sinaliza para o cliente executar a lógica e retornar o resultado:

// Define a função que o agente pode chamar
const tools = [
  { codeExecution: {} },
  {
    functionDeclarations: [{
      name: "buscar_preco_atual",
      description: "Busca o preço atual de um produto no ERP",
      parameters: {
        type: "object",
        properties: {
          produto_id: { type: "string" }
        }
      }
    }]
  }
];

let interaction = await ai.interactions.create({
  model: "gemini-2.5-pro",
  tools,
  prompt: "Compare o preço atual dos produtos A, B e C com o
           relatório de mercado e sugira ajustes"
});

// Se o agente precisar da função, ele pausa aqui
if (interaction.state === "requires_action") {
  const funcCall = interaction.required_action.function_call;

  // Execute a lógica local
  const resultado = await buscarPrecoNoERP(funcCall.args.produto_id);

  // Retorne o resultado para o agente continuar
  interaction = await ai.interactions.submit_tool_output({
    interaction_id: interaction.id,
    tool_output: JSON.stringify(resultado)
  });
}

Refresh de credenciais — tokens que expiram sem derrubar o agente

Tokens de acesso expiram. Chaves de API são rotacionadas. Em agentes de longa duração — especialmente os que rodam em background por horas — isso é um problema real: a tarefa inicia com credenciais válidas, mas quando tenta acessar um recurso protegido no meio da execução, o token já expirou.

O refresh de credenciais resolve isso passando novas configurações de rede para o mesmo environment_id — sem perder o estado do sandbox:

// O token expirou durante uma tarefa longa
// Renove sem criar um novo ambiente

const novoToken = await renovarToken();

await ai.interactions.update_environment({
  environment_id: "env_abc123", // mesmo ID
  network: {
    egress: {
      allowed_domains: ["api.minha-empresa.com"],
      auth: { bearer_token: novoToken } // novo token
    }
  }
});

// O sandbox mantém: filesystem, pacotes instalados,
// repositórios clonados e histórico da sessão

Quando usar Gemini vs Claude vs OpenAI para agentes

Os três players oferecem agentes autônomos em 2026, mas com perfis distintos:

Quando os Managed Agents não são a escolha certa

Os Managed Agents são poderosos — mas não são a solução para todos os casos:

Quando você precisa de controle total sobre o raciocínio. O sandbox gerenciado do Google é uma caixa preta: você vê o resultado e o log de ações, mas não controla passo a passo como o agente decide o que fazer. Para casos de uso com compliance rígido — auditoria financeira, decisões médicas, processos jurídicos — onde cada etapa precisa ser auditável e justificável, frameworks como LangChain com rastreamento completo são mais adequados.

Quando a tarefa é simples o suficiente para uma chamada direta. Se você só precisa resumir um texto, classificar um e-mail ou responder uma pergunta sobre um documento, uma chamada direta ao modelo (sem agente) é mais rápida, mais barata e mais previsível. Agentes têm overhead — use quando a tarefa genuinamente exige múltiplos passos autônomos.

Quando você está no começo da adoção de IA. Os Managed Agents pressupõem familiaridade com APIs, tokens, sandboxes e conceitos de agentes. Se sua empresa está nos primeiros passos com IA, ferramentas com interface visual — como o ChatGPT Trabalho ou o Claude Cowork — têm curva de aprendizado muito menor e entregam resultado mais rápido sem exigir desenvolvimento.