Visão geral da API Interactions

A API Interactions oferece uma interface unificada e com estado para criar aplicativos de IA generativa e Agentic Workflows usando modelos do Gemini e agentes hospedados na Gemini Enterprise Agent Platform. A API generateContent continua totalmente compatível com a API Interactions.

Por que usar a API Interactions?

A API Interactions oferece várias vantagens importantes para a criação de aplicativos de IA generativa e Agentic Workflows:

  • API única para modelos e agentes: um endpoint e um padrão unificados para chamar diretamente modelos do Gemini padrão e agentes especializados (como o Deep Research do Gemini e Agentes Gerenciados personalizados).
  • Novos recursos prontos 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 UI e execução em segundo plano para tarefas de longa duração usando background=true.

Como a API Interactions funciona

A API Interactions se concentra no recurso Interaction. Um Interaction representa uma rodada completa 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 da ferramenta fornecidos para a vez. As interações armazenadas recuperadas com interactions.get incluem etapas de user_input para o contexto completo, enquanto as respostas de interactions.create retornam apenas as etapas geradas durante essa vez.
  • thought: resumos de raciocínio intermediários gerados pelo modelo ou agente ao planejar a resposta.
  • Etapas de chamada de ferramenta e resultado: 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, a Agent Platform processa sua entrada, executa as ferramentas do lado do servidor ou os loops do agente configurados e retorna o recurso Interaction resultante. Para exemplos de código em Python, TypeScript/JavaScript e REST, consulte o guia para desenvolvedores 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 do Gemini na lista anterior, a API Interactions é compatível com os seguintes modelos de música generativa: * 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íveis com interações sem estado apenas 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 de arquivo e uso de ferramentas.
  • deep-research-preview-04-2026: Agente Deep Research do Gemini, projetado para pesquisa e síntese autônomas e em várias etapas 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 interações no servidor (store=true) por 7 dias para que você possa encadear conversas de vários turnos com previous_interaction_id e executar tarefas em segundo plano assíncronas (background=true). Para ativar a execução sem estado e oferecer suporte a fluxos de trabalho de retenção de dados zero (ZDR), defina store=false. Para mais detalhes, consulte Gerenciar o armazenamento de sessões e o estado da conversa.

Limites de solicitações e multimodais

A API Interactions aplica os seguintes limites de payload de solicitação e entrada multimodal:

  • Limites de payload de solicitação: o payload de solicitação HTTP compactado não pode exceder 256 MiB para solicitações interactions.create síncronas e de streaming. Quando service_tier é definido como deferred (o que exige que background e store sejam true), a solicitação descompactada não pode exceder 9,75 MiB.
  • Limite de URI para arquivos do Cloud Storage: as solicitações de interação do modelo padrão do Gemini aceitam até 100 URIs distintos do Cloud Storage (gs://) por solicitação, incluindo URIs transferidos de turnos de conversa anteriores por meio de previous_interaction_id. As interações de agentes gerenciados, os modelos Gemini Omni e os modelos Lyria 3 estão excluídos desse limite de 100 URIs. Para permissões e processamento de URI multiturno, consulte Acessar arquivos do Cloud Storage enviados.
  • Limites de itens e tokens multimodais: os modelos padrão do Gemini aceitam as mesmas contagens de itens por modalidade que o generateContent (até 3.000 imagens e PDFs combinados, 1.000 arquivos de áudio, 10 vídeos e até 6.500 arquivos multimodais combinados ao incluir arquivos de texto simples), limitados pela janela de contexto de 1.048.576 tokens do modelo. Os arquivos individuais do Cloud Storage não podem exceder 2 GiB menos 500 KiB, e os URLs HTTP ou HTTPS públicos não podem exceder 15 MiB. Para enviar mais de 100 arquivos em uma única solicitação, transmita anexos adicionais inline dentro do limite de payload da solicitação ou chame generateContent.

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.
  • Pesquisa de agentes e mecanismo RAG na Gemini Enterprise Agent Platform: embasa as respostas do modelo em repositórios de documentos e repositórios de dados corporativos privados usando a Pesquisa de agentes e o mecanismo RAG.
  • Pesquisa na Web do Exa: embasa as respostas do modelo com resultados da pesquisa na Web da API de pesquisa do Exa.
  • Pesquisa na Web em paralelo: embasa as respostas do modelo com dados públicos da Web em tempo real fornecidos pela API de pesquisa da Parallel Web Systems.
  • Contexto de URL: recupera e analisa o conteúdo de URLs públicos da Web incluídos no comando.
  • Execução de código: permite que o modelo gere e execute código Python em um ambiente de sandbox seguro.
  • Uso do computador: permite fluxos de trabalho de automação de navegador e interface do usuário.
  • 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 com 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 é faturado 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, ao enviar uma solicitação de cancelamento), você vai receber uma cobrança 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 do back-end, você não vai receber cobranças por ela.

Segurança e compliance

A API Interactions é compatível com os seguintes controles de segurança, certificações de conformidade e configurações de endpoint:

  • Endpoints: a API Interactions é compatível com o endpoint global (locations/global em aiplatform.googleapis.com) e os endpoints multirregionais us e eu (locations/us em aiplatform.us.rep.googleapis.com e locations/eu em aiplatform.eu.rep.googleapis.com). Endpoints de região única (como us-central1 ou europe-west1) não são compatíveis.
  • Residência de dados: a API Interactions oferece suporte à residência de dados para processamento de ML (em uso) e dados de interação armazenados em repouso (store=true) quando você usa os endpoints multirregionais us e eu (locations/us e locations/eu). As solicitações enviadas ao endpoint global não oferecem garantias de residência de dados.
  • Chaves de criptografia gerenciadas pelo cliente (CMEK): a API Interactions é compatível com CMEK para dados de interação armazenados usando perfis de veiculação (com scope definido como INTERACTIONS_API) nas multirregiões us e eu. O endpoint global não é compatível com CMEK.
  • VPC Service Controls (VPC-SC): a API Interactions é compatível com o VPC-SC para ajudar a proteger o perímetro da API e reduzir os riscos de exfiltração de dados.
  • Transparência no acesso (AXT): a API Interactions é compatível com registros de AXT para visibilidade quase em tempo real quando a equipe do Google acessa o conteúdo de interação armazenado.
  • Certificações de segurança e compliance: a API Interactions atende aos requisitos do FedRAMP High no limite de autorização do Google Cloud FedRAMP High. A API Interactions não está em conformidade com os requisitos do nível de impacto 5 (IL5) do Departamento de Defesa (DoD) ou da Regulamentação sobre Tráfico Internacional de Armas (ITAR).

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 do 2.3.0 ou mais recente
  • Ir: 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