You can now use the Interactions API on Gemini Enterprise Agent Platform (prev. Vertex AI) with Gemini models. Same google-genai SDK. https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/interactions…

Visão geral da API Interactions

Source: https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/interactions?hl=pt-br 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 APIgenerateContentatual, elagenerateContentcontinua 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 usandoprevious\_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 usandobackground=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 recursoInteraction. UmInteractionrepresenta 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çãosteps:

• user\_input: as mensagens de entrada, os arquivos multimodais ou os resultados de ferramentas fornecidos para a vez. As interações armazenadas recuperadas cominteractions\.getincluem etapasuser\_inputpara contexto completo, enquanto as respostasinteractions\.createretornam 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 (comofunction\_callefunction\_result).
• model\_output: o texto final, o JSON estruturado ou o conteúdo multimodal produzido pelo modelo ou agente.

Quando você chamainteractions\.create, o Agent Platform processa sua entrada, executa todas as ferramentas ou loops de agente configurados do lado do servidor e retorna o recursoInteractionresultante. Para exemplos de código em Python, TypeScript/JavaScript e REST, consulte oGuia 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

• Gemini Omni Flashpré-lançamento
• Gemini 3.8 Flash
• Gemini 3.7 Flash
• Gemini 3.6 Flash
• Gemini 3.5 Flash-Lite
• Gemini 3.1 Propré-lançamento
• Gemini 3.1 Flash-Lite

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\-previewelyria\-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 comstore=false).

Agentes compatíveis

É possível invocar os seguintes agentes pela API Interactions especificando o parâmetroagentem vez demodel:

• 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 Geminiprojetado para pesquisa e síntese autônomas e multifásicas na Web.
• Agentes gerenciados personalizadosimplantados 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 usandoprevious\_interaction\_id. Para ativar o comportamento sem estado, definastore=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 GoogleeEmbasamento 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 aosTermos 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ãogoogle\-genai``2\.3\.0ou mais recente
• TypeScript / JavaScript: versão@google/genai``2\.3\.0ou mais recente
• Acesse:google\.golang\.org/genai
• Java:com\.google\.genai:google\-genai

Os SDKs legados (google\-cloud\-aiplatform,@google\-cloud/vertexaiegoogle\-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 noguia para desenvolvedores da API Interactions.
• Teste onotebook de início rápido da API Interactions.
• Confira os métodos e esquemas de recursos nareferência da API Interactions.
• Aprenda ainteragir com agentes gerenciadoseusar o agente Deep Research do Gemini.