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 usandobackground=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 cominteractions.getincluem etapas deuser_inputpara o contexto completo, enquanto as respostas deinteractions.createretornam 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_callefunction_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
- Gemini Omni Flash
- Gemini Omni 1.2 Flash
- Gemini Omni 1.1 Flash
- Gemini 4 Hydrogen
- Gemini 4 Carbon para segurança cibernética
- Gemini 4 Carbon
- Gemini 4 Argon Cyber Permissive
- Gemini 4 Argon
- Gemini 3.8 Flash Cyber
- Gemini 3.8 Flash
- Gemini 3.7 Flash
- Gemini 3.6 Flash
- Gemini 3.5 Flash-Lite
- Gemini 3.5 Flash
- Gemini 3.1 Pro
- Gemini 3.1 Flash-Lite
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.createsíncronas e de streaming. Quandoservice_tieré definido comodeferred(o que exige quebackgroundestoresejamtrue), 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 deprevious_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 chamegenerateContent.
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/globalemaiplatform.googleapis.com) e os endpoints multirregionaisuseeu(locations/usemaiplatform.us.rep.googleapis.comelocations/euemaiplatform.eu.rep.googleapis.com). Endpoints de região única (comous-central1oueurope-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 multirregionaisuseeu(locations/uselocations/eu). As solicitações enviadas ao endpointglobalnã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
scopedefinido comoINTERACTIONS_API) nas multirregiõesuseeu. O endpointglobalnã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-genai2.3.0ou mais recente - TypeScript / JavaScript: versão
@google/genaido2.3.0ou 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
- Instale o SDK de IA Generativa do Google e execute sua primeira solicitação no guia para desenvolvedores da API Interactions.
- Teste o notebook de início rápido da API Interactions.
- Confira os métodos e os esquemas de recursos na referência da API Interactions.
- Saiba como interagir com agentes gerenciados e usar o agente Deep Research do Gemini.