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 modelli Gemini e agenti ospitati su Gemini Enterprise Agent Platform. Sebbene ci 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 flussi di lavoro agentici:

  • Unica API per modelli e agenti: un unico endpoint e pattern per chiamare direttamente modelli Gemini standard e 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 opzionale utilizzando previous_interaction_id, passaggi di esecuzione osservabili per il debug e il rendering della UI ed esecuzione in background per attività di lunga durata 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 dall'API Interactions.

Come funziona l'API Interactions

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

  • user_input: I messaggi di input, i file multimodali o i risultati degli strumenti forniti per il turno. Le interazioni memorizzate recuperate con interactions.get includono i passaggi user_input per il contesto completo, mentre le risposte interactions.create restituiscono solo i passaggi generati durante il 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 e output dello strumento lato client o lato server (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 eventuali strumenti o cicli dell'agente configurati lato server e restituisce la risorsa Interaction risultante.

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, l'editing e il controllo cinematografico di video conversazionali.
  • 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 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 ragionamento multi-step, programmazione, operazioni su file e utilizzo di strumenti.
  • deep-research-preview-04-2026: Agente Gemini Deep Research progettato per la ricerca e la sintesi autonome e in più passaggi sul web.
  • 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 memorizza le richieste in modo da poter sfruttare le funzionalità di gestione dello stato lato server utilizzando previous_interaction_id. Puoi attivare il comportamento stateless impostando store=false.

Strumenti supportati e grounding

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

  • Grounding con la Ricerca Google e Grounding web per aziende: Basano le risposte del modello su informazioni web in tempo reale provenienti dalla Ricerca Google o da Grounding web per aziende.
  • Agent Search e RAG Engine su Gemini Enterprise Agent Platform: basano 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 delle conoscenze in tempo reale.
  • Ricerca parallela: basa le risposte del modello su dati web pubblici in tempo reale forniti dall'API di ricerca di Parallel Web Systems.
  • Esecuzione del 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 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 completate 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 in materia di sicurezza, conformità e residenza dei dati:

  • Certificazioni di sicurezza e conformità: l'anteprima dell'API Interactions non supporta FedRAMP o le chiavi di crittografia gestite dal cliente (CMEK) e non è conforme ai requisiti del livello di impatto 5 (IL5) del Dipartimento della difesa (DoD) o dell'International Traffic in Arms Regulations (ITAR).
  • 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 solo gli endpoint globali (locations/global).

SDK supportati

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

  • Python: versione google-genai 2.3.0 o successive
  • TypeScript / JavaScript: versione @google/genai 2.3.0 o successive
  • Vai: 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