Interactions API: Nossa interface principal para modelos e agentes Gemini

Hoje anunciamos que a Interactions API atingiu a disponibilidade geral e agora é nossa principal API para interagir com modelos e agentes Gemini. Lançamos sua versão beta pública em dezembro de 2025, e rapidamente se tornou a forma favorita dos desenvolvedores de criar aplicações com Gemini.

Com esta versão GA, a API agora possui um esquema estável e também adicionamos novas capacidades importantes solicitadas por desenvolvedores, incluindo Managed Agents, execução em segundo plano, Gemini Omni (em breve) e muito mais. Toda a nossa documentação agora usa a Interactions API como padrão e estamos trabalhando com parceiros do ecossistema para torná-la a interface padrão em SDKs e bibliotecas de terceiros.

A forma mais simples de construir com Gemini

Quer você esteja chamando um modelo ou executando um agente, a Interactions API permite fazer isso com poucas linhas de código. Passe um ID de modelo para inferência ou um ID de agente para tarefas autônomas e defina background=True para tarefas de longa duração.

1from google import genai
2
3client = genai.Client()
4
5# Talk to a model
6interaction = client.interactions.create(
7    model="gemini-3.5-flash",
8    input="Explain quantum entanglement simply.",
9)
10
11# Run an agent
12interaction = client.interactions.create(
13    agent="antigravity-preview-05-2026",
14    input="Plot the growth of solar energy generation globally and make some slides in HTML.",
15    environment="remote",
16)

Principais atualizações desde dezembro

• Managed Agents: Uma única chamada de API provisiona um sandbox Linux remoto onde um agente pode raciocinar, executar código, navegar na web e gerenciar arquivos. O agente Antigravity vem como padrão, e você pode definir seus próprios agentes personalizados com instruções, habilidades e fontes de dados.
• Execução em segundo plano: Defina background=True em qualquer chamada. O servidor executa a interação de forma assíncrona.
• Melhorias nas ferramentas: Combine ferramentas integradas, como Google Search, Google Maps com suas próprias funções em uma única requisição. Os resultados das ferramentas agora podem retornar imagens junto com texto.
• Deep Research aprimorado: Duas novas versões do agente (velocidade vs. profundidade), planejamento colaborativo, gráficos e infográficos nativos, e fundamentação multimodal com imagens, PDFs e áudio.
• Geração de mídia: Geração de imagens com Nano Banana 2 e fundamentação no Google Image Search, música com Lyria 3, e fala expressiva com TTS multiusuário.
• De Roles para Steps: Esquema simplificado onde cada ação (user_input, thought, function_call, model_output, etc.) é sua própria etapa tipada, substituindo a estrutura antiga de papéis.
• Otimizações de custo e para desenvolvedores: Os níveis Flex e Priority permitem otimizar custo ou latência (Flex oferece 50% de redução de custo). Os erros agora apontam o campo exato. Interações passadas podem ser recuperadas com retenção de 55 dias no plano pago.

O novo padrão para desenvolvimento

A Interactions API agora é o padrão no Google AI Studio, na API Gemini e em toda a nossa documentação, que inclui um botão para alternar os snippets de volta para o formato legado. Recomendamos o uso da Interactions API para todos os novos projetos e aplicações.

Embora a API legada generateContent permaneça totalmente compatível e continue a receber novos modelos Gemini da linha principal no futuro previsível, esperamos que capacidades de ponta para modelos de longa duração e agentes sejam cada vez mais disponibilizadas exclusivamente na Interactions API. Isso porque ela foi projetada desde o início para fluxos de trabalho com estado e agentes. Publicamos um guia de migração para ajudar você a fazer a transição no seu próprio ritmo.

Um ecossistema orientado a agentes

A maioria dos desenvolvedores agora está usando agentes de codificação (como o Antigravity) para construir aplicações. Para facilitar que os agentes se mantenham atualizados com os padrões mais recentes da API, criamos a gemini-interactions-api Skill. Ela injeta padrões de boas práticas para o desenvolvimento com a Interactions API no contexto do seu agente (streaming, chamada de função, saída estruturada, Deep Research e muito mais).

1npx skills add google-gemini/gemini-skills --skill gemini-interactions-api

Primeiros passos

A Interactions API está disponível através dos SDKs Python e JavaScript. Se você já está desenvolvendo com um de nossos parceiros compatíveis, LiteLLM, Eigent ou Agno, você pode começar a usar as integrações com a Interactions API deles hoje mesmo.

Pegue sua chave de API no Google AI Studio e siga a documentação da Interactions API para começar. Se você estiver migrando do generateContent, nosso guia de migração mapeia cada campo para o novo esquema. Você também pode ver a especificação OpenAPI completa.

A Interactions API foi construída com base no feedback dos desenvolvedores, e esse foco não mudará com a disponibilidade geral. Conte-nos o que você precisa no fórum para desenvolvedores.