API Interactions

A API Interactions é a nova primitiva padrão para criar com o Gemini, recomendada para todos os novos projetos. Ele é otimizado para fluxos de trabalho baseados em agentes, gerenciamento de estado do lado do servidor e conversas complexas multimodais e multiturnos. A API generateContent original continua sendo totalmente compatível.

Por que usar a API Interactions?

  • Gerenciamento do histórico do lado do servidor: fluxos de várias etapas 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 tipadas facilitam a depuração de fluxos complexos e a renderização da interface para eventos intermediários (como ideias ou widgets de pesquisa).
  • Criado para fluxos de trabalho agentes: suporte nativo para uso de ferramentas em várias etapas, orquestração e fluxos de raciocínio complexos por etapas de execução tipadas.
  • 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: daqui para frente, novos modelos além da família principal, junto com novos recursos e ferramentas agênticos, serão lançados exclusivamente na API Interactions.

Use a API Interactions se você estiver iniciando um novo projeto, criando aplicativos de agente ou precisar de gerenciamento de conversas do lado do servidor. Use generateContent se você tiver uma integração que atenda às 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 do Gemini Docs 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. Configurar seu agente de programação →
  • Migrar do 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 funcional mínimo no guia de início rápido da API Interactions.

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.
  • Interações combinadas: você pode 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

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

  • 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 é compatível com o MCP remoto, mas isso vai mudar em breve.

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

Alterações importantes

No momento, a API Interactions está em 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, mudanças interruptivas podem ocorrer.

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 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 possíveis podem incluir mudanças em esquemas de entrada e saída, assinaturas de métodos e estruturas de objetos do SDK, comportamentos específicos de recursos.

Para cargas de trabalho de produção, continue usando a API padrão generateContent. Ele continua sendo o caminho recomendado para implantações estáveis, e vamos continuar desenvolvendo e mantendo o SDK 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 da IA do Google.

A seguir