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. L'API generateContent rimane completamente supportata insieme all'API Interactions.

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.

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 i passaggi di user_input per il contesto completo, mentre le risposte di 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 allo strumento e risultati: 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 Gemini nell'elenco precedente, l'API Interactions supporta i seguenti modelli di musica generativa: * 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 nelle 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 interazioni sul server (store=true) per 7 giorni, in modo da poter concatenare conversazioni multi-turn con previous_interaction_id ed eseguire attività in background asincrone (background=true). Per attivare l'esecuzione stateless e supportare i flussi di lavoro di conservazione dei dati pari a zero (ZDR), imposta store=false. Per maggiori dettagli, consulta Gestisci lo spazio di archiviazione della sessione e lo stato della conversazione.

Limiti di richieste e multimodali

L'API Interactions applica i seguenti limiti per il payload della richiesta e l'input multimodale:

  • Limiti del payload della richiesta: il payload della richiesta HTTP compressa non può superare i 256 MiB per le richieste interactions.create sincrone e di streaming. Quando service_tier è impostato su deferred (che richiede che sia background sia store siano true), la richiesta non compressa non può superare i 9,75 MiB.
  • Limite di URI per i file Cloud Storage: le richieste di interazione con il modello Gemini standard supportano fino a 100 URI Cloud Storage (gs://) distinti per richiesta, inclusi gli URI riportati dai turni di conversazione precedenti tramite previous_interaction_id. Le interazioni con gli agenti gestiti, i modelli Gemini Omni e i modelli Lyria 3 sono esclusi da questo limite di 100 URI. Per le autorizzazioni e la gestione degli URI multi-turn, consulta Accedi ai file Cloud Storage caricati.
  • Limiti di token ed elementi multimodali: i modelli Gemini standard accettano lo stesso numero di elementi per modalità di generateContent (fino a 3000 immagini e PDF combinati, 1000 file audio, 10 video e fino a 6500 file multimodali combinati se sono inclusi file di testo normale), limitati dalla finestra di contesto di 1.048.576 token del modello. I singoli file di Cloud Storage non possono superare i 2 GiB meno 500 KiB e gli URL HTTP o HTTPS pubblici non possono superare i 15 MiB. Per inviare più di 100 file in una singola richiesta, passa allegati aggiuntivi in linea entro il limite del payload della richiesta o chiama generateContent.

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 da 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.
  • Exa Web Search: basa le risposte del modello sui risultati di ricerca web dell'API di ricerca di Exa.
  • Ricerca web Parallel: basa le risposte del modello su dati web pubblici in tempo reale forniti dall'API di ricerca di Parallel Web Systems.
  • Contesto dell'URL: recupera e analizza i contenuti degli URL web pubblici inclusi nel prompt.
  • Esecuzione di codice: consente al modello di generare ed eseguire codice Python in un ambiente sandbox sicuro.
  • Utilizzo del computer: abilita i flussi di lavoro di automazione del browser e dell'interfaccia utente.
  • 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à

L'API Interactions supporta i seguenti controlli di sicurezza, certificazioni di conformità e configurazioni degli endpoint:

  • Endpoint: l'API Interactions supporta l'endpoint globale (locations/global su aiplatform.googleapis.com) e gli endpoint multiregionali us e eu (locations/us su aiplatform.us.rep.googleapis.com e locations/eu su aiplatform.eu.rep.googleapis.com). Gli endpoint a regione singola (come us-central1 o europe-west1) non sono supportati.
  • Residenza dei dati: l'API Interactions supporta la residenza dei dati sia per l'elaborazione ML (in uso) sia per i dati di interazione archiviati at-rest (store=true) quando utilizzi gli endpoint multi-regione us e eu (locations/us e locations/eu). Le richieste inviate all'endpoint global non forniscono garanzie di residenza dei dati.
  • 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. L'endpoint global non è supportato per CMEK.
  • Controlli di servizio VPC (VPC-SC): l'API Interactions supporta VPC-SC per contribuire a proteggere il perimetro dell'API e mitigare i rischi di esfiltrazione di dati.
  • Access Transparency (AXT): l'API Interactions supporta i log di AXT per la visibilità quasi in tempo reale quando il personale di Google accede ai contenuti delle interazioni archiviati.
  • Certificazioni di sicurezza e conformità: l'API Interactions soddisfa i requisiti FedRAMP High all'interno del confine di autorizzazione FedRAMP High di Google Cloud . L'API Interactions non è conforme ai requisiti del livello di impatto 5 (IL5) del Dipartimento della Difesa (DoD) o dell'International Traffic in Arms Regulations (ITAR).

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
  • 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