API Interactions

A API Interactions é nossa nova interface e a maneira mais simples de criar com modelos e agentes do Gemini. Desde junho de 2026, ela está disponível de forma geral e é a interface recomendada para todos os novos projetos.

Embora agora seja considerada legada, a API generateContent original continua sendo totalmente compatível.

Por que usar a API Interactions?

  • Novas funcionalidades prontas para uso: estado de conversa opcional do lado do servidor usando previous_interaction_id, etapas de execução observáveis para depuração e renderização da interface, além de execução em segundo plano para tarefas de longa duração usando background=true.
  • Menor custo com taxas de ocorrência em cache mais altas: o gerenciamento de estado do lado do servidor permite um cache de contexto mais eficiente em várias rodadas, reduzindo os custos de token para conversas multiturno.
  • Criado para modelos e agentes de ponta: desenvolvido para modelos de pensamento, uso de ferramentas em várias etapas e fluxos de raciocínio complexos, simplificando o processo de criação, depuração e organização de aplicativos de agentes.
  • API única para modelos e agentes: uma interface unificada para chamar modelos e agentes do Gemini diretamente, como o Deep Research e agentes gerenciados personalizados. Não há endpoints ou padrões separados para aprender.
  • Onde as novidades são lançadas: daqui para frente, novos modelos e recursos além da família principal, além de novas ferramentas e recursos de agente, serão lançados na API Interactions.

Por padrão, a API Interactions armazena solicitações para que você possa aproveitar os recursos de gerenciamento de estado do lado do servidor usando previous_interaction_id. É possível ativar o comportamento sem estado definindo store=false. Consulte a seção retenção de dados para mais detalhes.

Primeiros passos

Guias de recursos

Confira estes guias para conhecer os recursos específicos da API Interactions. Use a chave nessas páginas para alternar entre a API generateContent e a API Interactions:

Como a API Interactions funciona

A API Interactions se concentra em um recurso principal: o Interaction. Um Interaction representa uma rodada completa em uma conversa ou tarefa. Ele 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 reflexões do modelo, chamadas de ferramentas e resultados do lado do servidor ou do lado do cliente (como function_call e function_result) e o 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

Você pode usar o id de uma interação concluída em uma chamada subsequente usando o parâmetro previous_interaction_id para continuar a conversa. O servidor usa esse ID para recuperar o histórico da conversa, evitando que você precise reenviar todo o histórico do 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 são no escopo da interação e se aplicam apenas à interação específica que você está gerando:

  • 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. O gerenciamento de estado do lado do servidor é opcional. Você também pode 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 as interações por 55 dias.
  • Nível sem custo financeiro: o sistema retém as interações por 1 dia.

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

É possível excluir as interações armazenadas a qualquer momento usando o método de exclusão encontrado 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ência em cache: usar 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.
  • Misturar interações: você tem a flexibilidade de misturar e combinar interações do agente e do modelo em uma conversa. Por exemplo, você pode usar um agente especializado, como o Deep Research, para a coleta inicial de dados e, em seguida, usar um modelo padrão do Gemini 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évia de clipe do Lyria 3 Modelo lyria-3-clip-preview
Pré-lançamento do Lyria 3 Pro Modelo lyria-3-pro-preview
Prévia do Deep Research Agente deep-research-pro-preview-12-2025
Prévia do Deep Research Agente deep-research-preview-04-2026
Prévia do Deep Research Agente deep-research-max-preview-04-2026
Prévia do Antigravity Agente antigravity-preview-05-2026

SDKs

Use a versão mais recente dos SDKs da IA generativa do Google para acessar a API Interactions.

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

Saiba mais sobre como instalar os SDKs na página Bibliotecas.

Limitações

  • MCP remoto: o Gemini 3 não é compatível com MCP remoto. Essa funcionalidade será lançada em breve.

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

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 da IA do Google.

A seguir