API Interactions

A API Interactions é a nova primitiva padrão para criar com o Gemini, recomendada para todos os novos projetos. Ela é otimizada para fluxos de trabalho de agentes, gerenciamento de estado do lado do servidor e conversas complexas multimodais e multiturnos. A API generateContent original continua com suporte total.

Por que usar a API Interactions?

  • Gerenciamento de histórico do lado do servidor: fluxos multiturnos simplificados via previous_interaction_id. O servidor ativa o estado por padrão (store=true), mas você pode ativar o comportamento sem estado definindo store=false.
  • Etapas de execução observáveis: as etapas digitadas facilitam a depuração de fluxos complexos e a renderização da interface para eventos intermediários (como pensamentos ou widgets de pesquisa).
  • Criada para fluxos de trabalho de agentes: suporte nativo para uso de ferramentas de várias etapas, orquestração e fluxos de raciocínio complexos por etapas de execução digitadas.
  • Tarefas longas e em segundo plano: oferece suporte ao descarregamento de operações demoradas, como Deep Think e Deep Research, para processos em segundo plano usando background=true.
  • Acesso a novos modelos e recursos: no futuro, novos modelos além da família principal, além de novos recursos e ferramentas de agentes, serão lançados exclusivamente na API Interactions.

Use a API Interactions se você estiver iniciando um novo projeto, criando aplicativos de agentes ou precisar do gerenciamento de conversas do lado do servidor. Use generateContent se você tiver uma integração que funcione para suas necessidades ou se precisar de um recurso que ainda não esteja disponível na API Interactions, como a API Batch ou o armazenamento em cache explícito.

Primeiros passos

  • Configure seu agente de programação: conecte-se ao MCP dos documentos do Gemini e instale a habilidade gemini-interactions-api para dar ao seu assistente acesso direto aos documentos mais recentes para desenvolvedores e às práticas recomendadas. Configure seu agente de programação →
  • Migre de generateContent: se você tiver uma integração, siga o guia de migração para fazer a transição para a API Interactions.
  • Teste o guia de início rápido: comece com um exemplo de trabalho mínimo no guia de início rápido da API Interactions.

Guias de recursos

Conheça os recursos específicos da API Interactions nestes guias. Você pode usar o botão de alternância nessas páginas para alternar entre a API generateContent e a API Interactions:

Como a API Interactions funciona

A API Interactions é centrada em um recurso principal: o Interaction. Uma Interaction representa um turno completo em uma conversa ou tarefa. Ela funciona como um registro de sessão, contendo todo o histórico de uma interação como uma sequência cronológica de etapas de execução. Essas etapas incluem pensamentos do modelo, chamadas e resultados de ferramentas do lado do servidor ou do lado do cliente (como function_call e function_result) e a model_output final. O recurso armazenado (recuperado via interactions.get) também inclui etapas user_input para contexto completo, embora a resposta interactions.create retorne apenas etapas geradas pelo modelo.

Ao fazer uma chamada para interactions.create, você está criando um novo recurso Interaction.

Gerenciamento de estado do lado do servidor

É possível usar o id de uma interação concluída em uma chamada subsequente usando o previous_interaction_id parâmetro para continuar a conversa. O servidor usa esse ID para recuperar o histórico de conversas, evitando que você precise reenviar todo o histórico de chat.

O parâmetro previous_interaction_id preserva apenas o histórico de conversas (entradas e saídas) usando previous_interaction_id. Os outros parâmetros têm escopo de interação e se aplicam apenas à interação específica que você está gerando no momento:

  • tools
  • system_instruction
  • generation_config (incluindo thinking_level, temperature etc.)

Isso significa que você precisa especificar esses parâmetros novamente em cada nova interação se quiser que eles sejam aplicados. Esse gerenciamento de estado do lado do servidor é opcional. Também é possível operar no modo sem estado enviando o histórico completo da conversa em cada solicitação.

Armazenamento e retenção de dados

Por padrão, a API armazena todos os objetos de interação (store=true) para simplificar o uso de recursos de gerenciamento de estado do lado do servidor (com previous_interaction_id), execução em segundo plano (usando background=true) e fins de observabilidade.

  • Nível pago: o sistema retém interações por 55 dias.
  • Nível sem custo financeiro: o sistema retém interações por 1 dia.

Se você não quiser isso, defina store=false na sua solicitação. Esse controle é separado do gerenciamento de estado. Você pode desativar o armazenamento de qualquer interação. No entanto, store=false é incompatível com background=true e impede o uso de previous_interaction_id para turnos subsequentes.

É possível excluir interações armazenadas a qualquer momento usando o método de exclusão encontrado em na referência da API. Só é possível excluir interações se você souber o ID delas.

Após o período de armazenamento expirar, seus dados serão excluídos automaticamente.

O sistema processa objetos de interação de acordo com os termos.

Práticas recomendadas

  • Taxa de ocorrências em cache: o uso de previous_interaction_id para continuar conversas permite que o sistema utilize mais facilmente o armazenamento em cache implícito para o histórico de conversas, o que melhora o desempenho e reduz os custos.
  • Interações de mixagem: você tem a flexibilidade de misturar e combinar interações de agentes e modelos em uma conversa. Por exemplo, é possível usar um agente especializado, como o Deep Research Agent, para a coleta inicial de dados e, em seguida, usar um modelo do Gemini padrão para tarefas de acompanhamento, como resumir ou reformatar, vinculando essas etapas ao previous_interaction_id.

Modelos e agentes compatíveis

Nome do modelo Tipo ID do modelo
Gemini 3.1 Flash-Lite Modelo gemini-3.1-flash-lite
Pré-lançamento do Gemini 3.1 Flash-Lite Modelo gemini-3.1-flash-lite-preview
Pré-lançamento do Gemini 3.1 Pro Modelo gemini-3.1-pro-preview
Pré-lançamento do Gemini 3 Flash Modelo gemini-3-flash-preview
Gemini 2.5 Pro Modelo gemini-2.5-pro
Gemini 2.5 Flash Modelo gemini-2.5-flash
Gemini 2.5 Flash-lite Modelo gemini-2.5-flash-lite
Pré-lançamento do Lyria 3 Clip Modelo lyria-3-clip-preview
Pré-lançamento do Lyria 3 Pro Modelo lyria-3-pro-preview
Pré-lançamento do Deep Research Agente deep-research-pro-preview-12-2025
Pré-lançamento do Deep Research Agente deep-research-preview-04-2026
Pré-lançamento do Deep Research Agente deep-research-max-preview-04-2026

SDKs

É possível usar a versão mais recente dos SDKs da IA generativa do Google para acessar a API Interactions.

  • No Python, esse é o pacote google-genai da versão 1.55.0 em diante.
  • No JavaScript, esse é o pacote @google/genai da versão 1.33.0 em diante.

Saiba como instalar os SDKs na página de bibliotecas.

Limitações

  • Status Beta: a API Interactions está na versão Beta/prévia. Os recursos e esquemas podem mudar.
  • MCP remoto: o Gemini 3 não oferece suporte ao MCP remoto. Esse recurso será lançado em breve.

Os recursos a seguir são compatíveis com a generateContent API, mas ainda não estão disponíveis na API Interactions:

Alterações importantes

A API Interactions está atualmente em uma fase Beta inicial. Estamos desenvolvendo e refinando ativamente os recursos da API, os esquemas de recursos e as interfaces do SDK com base no uso real e no feedback dos desenvolvedores. Como resultado, podem ocorrer mudanças interruptivas.

Mudanças interruptivas atuais:

  • Esquema de etapas: uma nova matriz de etapas substitui a matriz de saídas, fornecendo uma linha do tempo estruturada de cada turno de interação.

Para saber mais sobre a mudança interruptiva mais recente e entender como migrar, consulte o guia de migração de mudanças interruptivas (maio de 2026).

Outras atualizações em potencial podem incluir mudanças nos esquemas de entrada e saída, assinaturas de métodos e estruturas de objetos do SDK e comportamentos de recursos específicos.

Para cargas de trabalho de produção, continue usando a API padrão generateContent. Ela continua sendo o caminho recomendado para implantações estáveis, e vamos continuar desenvolvendo e mantendo ativamente.

Feedback

Seu feedback é fundamental para o desenvolvimento da API Interactions. Compartilhe suas ideias, informe bugs ou solicite recursos no fórum da comunidade de desenvolvedores de IA do Google.

A seguir