Panoramica dell'API Interactions

L'API Interactions fornisce un'interfaccia unificata e con stato per la creazione di applicazioni di AI generativa e flussi di lavoro agentici utilizzando i modelli e gli agenti Gemini ospitati su Gemini Enterprise Agent Platform. Sebbene ci sia una sovrapposizione di funzionalità con l'API generateContent esistente, quest'ultima rimane completamente supportata.generateContent

Perché utilizzare l'API Interactions?

L'API Interactions offre diversi vantaggi chiave per la creazione di applicazioni di AI generativa e flussi di lavoro agentici:

  • Una sola API per modelli e agenti: un endpoint e un pattern unificati per chiamare direttamente i modelli Gemini standard e gli agenti specializzati (come l'agente Deep Research di Gemini e gli agenti gestiti personalizzati).
  • Nuove funzionalità predefinite: funzionalità come lo stato della conversazione lato server facoltativo utilizzando previous_interaction_id, passaggi di esecuzione osservabili per il debug e il rendering dell'interfaccia utente ed esecuzione in background per le attività a lunga esecuzione utilizzando background=true.
  • Dove vengono lanciate le nuove funzionalità: in futuro, tutti i nuovi modelli, le funzionalità multimodali gli strumenti e le funzionalità agentiche saranno supportati nell'API Interactions.

Come funziona l'API Interactions

L'API Interactions è incentrata sulla Interaction risorsa. Un' Interaction rappresenta un turno completo in una conversazione o un'attività e funge da record di sessione contenente una sequenza cronologica di steps di esecuzione:

  • user_input: i messaggi di input, i file multimodali o i risultati degli strumenti forniti per il turno. Le interazioni archiviate recuperate con interactions.get includono i passaggi user_input per il contesto completo, mentre le risposte interactions.create restituiscono solo i passaggi generati durante quel turno.
  • thought: riepiloghi del ragionamento intermedio generati dal modello o dall'agente durante la pianificazione della risposta.
  • Passaggi di chiamata e risultato dello strumento: chiamate degli strumenti lato client o lato server e output (ad esempio function_call e function_result).
  • model_output: il testo finale, il JSON strutturato o i contenuti multimodali prodotti dal modello o dall'agente.

Quando chiami interactions.create, Agent Platform elabora l'input, esegue tutti gli strumenti lato server o i loop degli agenti configurati e restituisce la risorsa Interaction risultante. Per esempi di codice in Python, TypeScript/JavaScript e REST, consulta la guida per gli sviluppatori dell'API Interactions.

Modelli supportati

I seguenti modelli Gemini supportano l'API Interactions:

Fai clic per espandere i modelli supportati

Oltre ai modelli elencati sopra, l'API Interactions supporta i seguenti modelli specializzati di generazione multimodale e audio:

  • gemini-omni-flash-preview: modello multimodale ad alte prestazioni per la generazione di video, la modifica e il controllo cinematografico di conversazioni.
  • lyria-3-clip-preview e lyria-3-pro-preview: modelli di musica generativa per audio clip ad alta fedeltà e composizione di brani completi (supportati solo nelle interazioni stateless con store=false).

Agenti supportati

Puoi richiamare i seguenti agenti tramite l'API Interactions specificando il parametro agent anziché model:

  • antigravity-preview-05-2026: agente autonomo per uso generico progettato per il ragionamento multi-step, la programmazione, le operazioni su file e l'utilizzo degli strumenti.
  • deep-research-preview-04-2026: Agente Deep Research di Gemini progettato per la ricerca e la sintesi web autonome in più passaggi.
  • Agenti gestiti personalizzati di cui è stato eseguito il deployment su Agent Platform.

Funzionalità e specifiche

Le sezioni seguenti descrivono le funzionalità principali, le specifiche tecniche e le considerazioni operative per l'API Interactions.

Gestione dello stato

Per impostazione predefinita, l'API Interactions archivia le richieste in modo che tu possa sfruttare le funzionalità di gestione dello stato lato server utilizzando previous_interaction_id. Puoi attivare il comportamento stateless impostando store=false.

Strumenti e grounding supportati

I seguenti strumenti integrati, provider di grounding e funzionalità di ricerca sono supportati per i modelli Gemini 3 nell'API Interactions:

  • Grounding con la Ricerca Google e Grounding web per Enterprise: basa le risposte del modello su informazioni web in tempo reale della Ricerca Google o di Grounding web per Enterprise.
  • Agent Search e RAG Engine su Gemini Enterprise Agent Platform: basa le risposte del modello su datastore aziendali privati e repository di documenti utilizzando Agent Search e RAG Engine.
  • xAI Search: collega i modelli alla ricerca sociale e al grounding della conoscenza in tempo reale.
  • Parallel Search: basa le risposte del modello su dati web pubblici in tempo reale forniti dall'API di ricerca di Parallel Web Systems.
  • Esecuzione di codice: consente al modello di generare ed eseguire codice Python in un ambiente sandbox sicuro.
  • Chiamata di funzioni: consente ai modelli di connettersi a strumenti, API e database esterni restituendo argomenti di funzione strutturati.

L'API Interactions supporta Grounding web per Enterprise e Grounding con la Ricerca Google. L'utilizzo di queste funzionalità è inoltre soggetto ai Termini di servizio specifici.

Fatturazione

L'utilizzo dell'API Interactions viene fatturato in base al consumo di token.

La fatturazione per le richieste interrotte o non soddisfatte viene gestita nel seguente modo:

  • Annullamenti manuali: se un'interazione viene annullata prima del completamento (ad esempio inviando una richiesta di annullamento), ti vengono addebitati i token consumati fino al momento dell'annullamento.
  • Richieste non riuscite: se una richiesta di interazione non riesce a causa di un errore di sistema interno o di un errore di backend, non ti viene addebitato alcun costo per la richiesta non riuscita.

Sicurezza e conformità

Durante l'anteprima, l'API Interactions presenta le seguenti considerazioni relative a sicurezza, conformità e residenza dei dati:

  • Certificazioni di sicurezza e conformità: l'anteprima dell'API Interactions non supporta FedRAMP e non è conforme ai requisiti del livello di impatto 5 (IL5) del Dipartimento della Difesa (DoD) o dell'International Traffic in Arms Regulations (ITAR).
  • Chiavi di crittografia gestite dal cliente (CMEK): l'API Interactions supporta CMEK per i dati di interazione archiviati tramite i profili di pubblicazione (con scope impostato su INTERACTIONS_API) nelle multiregioni us ed eu.
  • Controlli di servizio VPC: l'anteprima dell'API Interactions supporta i Controlli di servizio VPC (VPC-SC) per proteggere il perimetro dell'API.
  • Residenza dei dati: l'anteprima dell'API Interactions non supporta la residenza dei dati e non si impegna per l'archiviazione delle sessioni.
  • Endpoint: l'anteprima dell'API Interactions supporta l'endpoint globale (locations/global) e gli endpoint multiregionali us ed eu (locations/us e locations/eu) quando si utilizza CMEK.

SDK supportati

Puoi accedere all'API Interactions utilizzando l'SDK Google Gen AI unificato o le chiamate REST dirette:

  • Python: google-genai versione 2.3.0 o successive
  • TypeScript / JavaScript: @google/genai versione 2.3.0 o successive
  • Go: google.golang.org/genai
  • Java: com.google.genai:google-genai

Gli SDK legacy (google-cloud-aiplatform, @google-cloud/vertexai e google-generativeai) non supportano l'API Interactions.

Passaggi successivi