API Interactions

A API Interactions é o novo padrão recomendado para criar com o Gemini. Ela é otimizada para fluxos de trabalho de agentes, gerenciamento de estado do lado do servidor e conversas multimodais e multiturnos complexas. 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 com uso intensivo de tempo, como Deep Think e Deep Research, para processos em segundo plano usando background=true.
  • Acesso a novos modelos e recursos: a partir de agora, 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.
  • Confira 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 a 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.

Acessar saídas com propriedades de conveniência do SDK

Embora a API Interactions retorne uma linha do tempo estruturada de etapas de execução (como pensamentos, consultas de pesquisa e chamadas de função), não é necessário percorrer as etapas manualmente para receber a resposta final do modelo.

Os SDKs da IA generativa do Google fornecem propriedades de conveniência diretamente no objeto Interaction retornado para acessar as saídas de diferentes modalidades:

Propriedade de conveniência do SDK Tipo de retorno Descrição
interaction.output_text String Retorna os últimos blocos de texto na resposta do modelo. Se a resposta for dividida em vários blocos TextContent consecutivos, ela será unida automaticamente. Ela não inclui blocos de texto anteriores separados por conteúdo não textual (como pensamentos, imagens, áudio ou chamadas de ferramentas). Para respostas multimodais complexas ou intercaladas, é necessário iterar manualmente em steps.
interaction.output_image ImageContent ou None Retorna o último bloco de imagens gerado pelo modelo na solicitação atual.
interaction.output_audio AudioContent ou None Retorna o último bloco de áudio gerado pelo modelo na solicitação atual.

Para casos de uso avançados, como renderizar processos de pensamento intermediários, inspecionar chamadas de ferramentas passo a passo ou depurar, ainda é possível inspecionar e percorrer a linha do tempo interaction.steps bruta manualmente.

Gerenciamento de estado do lado do servidor

Você pode 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 da conversa, evitando que você precise reenviar todo o histórico do chat.

O parâmetro previous_interaction_id preserva apenas o histórico da conversa (entradas e saídas) usando previous_interaction_id. Os outros parâmetros são com escopo de 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. Esse 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 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, observe que store=false é incompatível com background=true e impede o uso de previous_interaction_id para turnos subsequentes.

Você pode excluir interações armazenadas a qualquer momento usando o método de exclusão encontrado em a 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: 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 da conversa, 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, você pode usar um agente especializado, como o Deep Research Agent, 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 com suporte

Nome do modelo Tipo ID do modelo
Gemini 3.5 Flash Modelo gemini-3.5-flash
Gemini 3.1 Flash-Lite Modelo gemini-3.1-flash-lite
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

Você pode 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 mais sobre como instalar os SDKs na página de bibliotecas.

Limitações

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

Os seguintes recursos 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, 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 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, 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