Visão geral da API Interactions

A API Interactions oferece uma interface unificada e com estado para criar aplicativos de IA generativa e fluxos de trabalho agênticos usando modelos e agentes do Gemini hospedados na Gemini Enterprise Agent Platform. Embora haja sobreposição de recursos com a API generateContent atual, ela generateContent continua sendo totalmente compatível.

Por que usar a API Interactions?

A API Interactions oferece várias vantagens importantes para criar aplicativos de IA generativa e fluxos de trabalho agênticos:

  • API única para modelos e agentes: um endpoint e um padrão unificados para chamar modelos padrão do Gemini e agentes especializados diretamente (como o Gemini Deep Research Agent e agentes gerenciados personalizados).
  • Novas funcionalidades prontas para uso: recursos como 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 UI, além de execução em segundo plano para tarefas de longa duração usando background=true.
  • Onde os novos recursos são lançados: a partir de agora, todos os novos modelos, recursos multimodais, ferramentas e recursos de agente serão compatíveis com a API Interactions.

Como a API Interactions funciona

A API Interactions se concentra no recurso Interaction. Um Interaction representa um turno completo em uma conversa ou tarefa e atua como um registro de sessão que contém uma sequência cronológica de execução steps:

  • user_input: as mensagens de entrada, os arquivos multimodais ou os resultados de ferramentas fornecidos para a vez. As interações armazenadas recuperadas com interactions.get incluem etapas user_input para contexto completo, enquanto as respostas interactions.create retornam apenas as etapas geradas durante essa vez.
  • thought: resumos de raciocínio intermediário gerados pelo modelo ou agente enquanto planeja a resposta.
  • Etapas de chamada e resultado da ferramenta: invocações e saídas de ferramentas do lado do cliente ou do lado do servidor (como function_call e function_result).
  • model_output: o texto final, o JSON estruturado ou o conteúdo multimodal produzido pelo modelo ou agente.

Quando você chama interactions.create, o Agent Platform processa sua entrada, executa todas as ferramentas ou loops de agente configurados do lado do servidor e retorna o recurso Interaction resultante. Para exemplos de código em Python, TypeScript/JavaScript e REST, consulte o Guia do desenvolvedor da API Interactions.

Modelos compatíveis

Os seguintes modelos do Gemini são compatíveis com a API Interactions:

Clique para abrir os modelos compatíveis

Além dos modelos listados acima, a API Interactions é compatível com os seguintes modelos especializados de geração de áudio e multimodal:

  • gemini-omni-flash-preview: modelo multimodal de alta performance para geração, edição e controle cinematográfico de vídeos conversacionais.
  • lyria-3-clip-preview e lyria-3-pro-preview: modelos de música generativa para clipes de áudio de alta fidelidade e composição de músicas completas (compatível apenas com interações sem estado com store=false).

Agentes compatíveis

É possível invocar os seguintes agentes pela API Interactions especificando o parâmetro agent em vez de model:

  • antigravity-preview-05-2026: agente autônomo de uso geral projetado para raciocínio em várias etapas, programação, operações com arquivos e uso de ferramentas.
  • deep-research-preview-04-2026: Agente Deep Research do Gemini projetado para pesquisa e síntese autônomas e multifásicas na Web.
  • Agentes gerenciados personalizados implantados na Agent Platform.

Recursos e especificações

As seções a seguir descrevem os principais recursos, as especificações técnicas e as considerações operacionais da API Interactions.

Gerenciamento do estado

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. Para ativar o comportamento sem estado, defina store=false.

Ferramentas e embasamento compatíveis

As seguintes ferramentas integradas, provedores de embasamento e recursos de pesquisa são compatíveis com os modelos do Gemini 3 na API Interactions:

  • Embasamento com a Pesquisa Google e Embasamento na Web para empresas: embasa as respostas do modelo com informações da Web em tempo real da Pesquisa Google ou do Embasamento na Web para empresas.
  • Agent Search e mecanismo RAG na Gemini Enterprise Agent Platform: embasa respostas do modelo em repositórios de dados e documentos corporativos privados usando o Agent Search e o mecanismo RAG.
  • Pesquisa da xAI: conecta modelos à pesquisa social e ao embasamento de conhecimento em tempo real.
  • Pesquisa paralela: embasa as respostas do modelo com dados públicos da Web em tempo real fornecidos pela API de pesquisa da Parallel Web Systems.
  • Execução de código: permite que o modelo gere e execute código Python em um ambiente de sandbox seguro.
  • Chamada de função: permite que os modelos se conectem a ferramentas, APIs e bancos de dados externos retornando argumentos de função estruturados.

A API Interactions é compatível com o embasamento da Web para empresas e o embasamento com a Pesquisa Google. O uso desses recursos também está sujeito aos Termos Específicos de Serviço.

Faturamento

O uso da API Interactions é cobrado com base no consumo de tokens.

O faturamento de solicitações interrompidas ou não atendidas é processado da seguinte maneira:

  • Cancelamentos manuais: se uma interação for cancelada antes da conclusão (por exemplo, enviando uma solicitação de cancelamento), você vai pagar pelos tokens consumidos até o momento do cancelamento.
  • Solicitações com falha: se uma solicitação de interação falhar devido a um erro interno do sistema ou uma falha de back-end, você não vai receber cobranças por ela.

Segurança e compliance

Durante a prévia, a API Interactions tem as seguintes considerações sobre segurança, compliance e residência de dados:

  • Certificações de segurança e compliance: a prévia da API Interactions não é compatível com o FedRAMP nem com chaves de criptografia gerenciadas pelo cliente (CMEK) e não está em conformidade com os requisitos do Nível 5 de impacto (IL5) do Departamento de Defesa (DoD) ou com a Regulamentação sobre Tráfico Internacional de Armas (ITAR).
  • VPC Service Controls: a prévia da API Interactions é compatível com o VPC Service Controls (VPC-SC) para proteger o perímetro da API.
  • Residência de dados: a prévia da API Interactions não oferece suporte à residência de dados e não faz nenhuma promessa para o armazenamento de sessões.
  • Endpoints: a prévia da API Interactions só é compatível com endpoints globais (locations/global).

SDKs compatíveis

É possível acessar a API Interactions usando o SDK de IA generativa do Google unificado ou chamadas REST diretas:

  • Python: versão google-genai 2.3.0 ou mais recente
  • TypeScript / JavaScript: versão @google/genai 2.3.0 ou mais recente
  • Acesse: google.golang.org/genai
  • Java: com.google.genai:google-genai

Os SDKs legados (google-cloud-aiplatform, @google-cloud/vertexai e google-generativeai) não são compatíveis com a API Interactions.

A seguir