Panoramica dell'API Interactions

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

Perché utilizzare l'API Interactions?

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

  • API singola per modelli e agenti: un endpoint e un pattern unificati per chiamare direttamente i modelli Gemini standard e gli agenti specializzati (come l'agente Gemini Deep Research e gli agenti gestiti personalizzati).
  • Nuove funzionalità pronte all'uso: funzionalità come lo stato della conversazione lato server facoltativo utilizzando previous_interaction_id, passaggi di esecuzione osservabili per il debug e il rendering della UI ed esecuzione in background per attività a lunga esecuzione utilizzando background=true.
  • Lancio di 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 si basa sulla risorsa Interaction. Un Interaction rappresenta un turno completo in una conversazione o un'attività e funge da record della sessione contenente una sequenza cronologica di esecuzione steps:

  • user_input: i messaggi di input, i file multimodali o i risultati dello strumento forniti per il turno. Le interazioni archiviate recuperate con interactions.get includono user_input passaggi per il contesto completo, mentre le risposte di interactions.create restituiscono solo i passaggi generati durante quel turno.
  • thought: riepiloghi dei ragionamenti intermedi generati dal modello o dall'agente durante la pianificazione della risposta.
  • Passaggi di chiamata e risultato dello strumento: chiamate e output degli strumenti lato client o lato server (come 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 gli strumenti lato server o i loop dell'agente 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 conversazionali, l'editing e il controllo cinematografico.
  • lyria-3-clip-preview e lyria-3-pro-preview: modelli di musica generativa per clip audio ad alta fedeltà e composizione di brani completi (supportati in interazioni stateless solo 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 di strumenti.
  • deep-research-preview-04-2026: Gemini Deep Research Agent progettato per la ricerca e la sintesi web autonome e 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 aziende: basa le risposte del modello su informazioni web in tempo reale provenienti dalla Ricerca Google o dal Grounding web per aziende.
  • 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 social in tempo reale e al grounding della conoscenza.
  • Ricerca parallela: 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 funzione: consente ai modelli di connettersi a strumenti, API e database esterni restituendo argomenti di funzione strutturati.

L'API Interactions supporta il grounding web per Enterprise e il grounding con la Ricerca Google. L'utilizzo di queste funzionalità è inoltre soggetto ai relativi Termini specifici dei servizi.

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 come segue:

  • 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 va a buon fine a causa di un errore di sistema interno o di un errore del backend, non ti verrà addebitato alcun costo per la richiesta non riuscita.

Sicurezza e conformità

Durante l'anteprima, l'API Interactions presenta le seguenti considerazioni su 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 Department of Defense (DoD) Impact Level 5 (IL5) o dell'International Traffic in Arms Regulations (ITAR).
  • Chiavi di crittografia gestite dal cliente (CMEK): l'API Interactions supporta le CMEK per i dati di interazione archiviati tramite i profili di pubblicazione (con scope impostato su INTERACTIONS_API) nelle multi-regioni us e eu.
  • Controlli di servizio VPC: l'anteprima dell'API Interactions supporta i Controlli di servizio VPC per proteggere il perimetro dell'API.
  • Residenza dei dati: l'anteprima dell'API Interactions non supporta la residenza dei dati e non si assume alcun impegno per l'archiviazione delle sessioni.
  • Endpoint: l'anteprima dell'API Interactions supporta l'endpoint globale (locations/global) e gli endpoint multiregionali us e eu (locations/us e locations/eu) quando utilizzi CMEK.

SDK supportati

Puoi accedere all'API Interactions utilizzando l'SDK Google Gen AI unificato o 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