API Interactions

L'API Interactions è la nuova primitiva standard per la creazione con Gemini, consigliata per tutti i nuovi progetti. È ottimizzato per i workflow agentici, la gestione dello stato lato server e le conversazioni multimodali e multi-turno complesse. L'API generateContent originale rimane completamente supportata.

Perché utilizzare l'API Interactions?

  • Gestione della cronologia lato server: flussi multi-turn semplificati tramite previous_interaction_id. Il server abilita lo stato per impostazione predefinita (store=true), ma puoi attivare il comportamento senza stato impostando store=false.
  • Passaggi di esecuzione osservabili: i passaggi digitati semplificano il debug di flussi complessi e il rendering dell'interfaccia utente per eventi intermedi (come pensieri o widget di ricerca).
  • Creato per i flussi di lavoro agentici: supporto nativo per l'utilizzo di strumenti multi-step, l'orchestrazione e flussi di ragionamento complessi tramite passaggi di esecuzione digitati.
  • Attività in background e a lunga esecuzione: supporta l'offload di operazioni che richiedono molto tempo, come Deep Think e Deep Research, a processi in background utilizzando background=true.
  • Accesso a nuovi modelli e capacità: in futuro, i nuovi modelli al di fuori della famiglia principale, insieme a nuovi strumenti e capacità agentiche, verranno lanciati esclusivamente sull'API Interactions.

Utilizza l'API Interactions se stai avviando un nuovo progetto, creando applicazioni con agenti o hai bisogno della gestione delle conversazioni lato server. Utilizza generateContent se hai un'integrazione esistente che soddisfa le tue esigenze o se hai bisogno di una funzionalità non ancora disponibile nell'API Interactions, come l'API batch o la memorizzazione esplicita nella cache.

Inizia

  • Configura l'agente di programmazione: connettiti a Gemini Docs MCP e installa l'gemini-interactions-api skill per dare all'assistente l'accesso diretto alla documentazione per gli sviluppatori e alle best practice più recenti. Configurare l'agente di programmazione →
  • Esegui la migrazione da generateContent: se hai un'integrazione esistente, segui la guida alla migrazione per eseguire la transizione all'API Interactions.
  • Prova la guida rapida: inizia con un esempio di funzionamento minimo nella guida rapida all'API Interactions.

Guide alle funzionalità

Esplora le funzionalità specifiche dell'API Interactions tramite queste guide. Puoi utilizzare il pulsante di attivazione/disattivazione in queste pagine per passare dall'API generateContent all'API Interactions:

Come funziona l'API Interactions

L'API Interactions si concentra su una risorsa principale: Interaction. Un Interaction rappresenta un turno completo in una conversazione o un'attività. Funge da record di sessione, contenente l'intera cronologia di un'interazione come sequenza cronologica di passaggi di esecuzione. Questi passaggi includono i pensieri del modello, le chiamate e i risultati degli strumenti lato server o lato client (come function_call e function_result) e la model_output finale. La risorsa archiviata (recuperata tramite interactions.get) include anche i passaggi user_input per il contesto completo, anche se la risposta interactions.create restituisce solo i passaggi generati dal modello.

Quando effettui una chiamata a interactions.create, stai creando una nuova risorsa Interaction.

Gestione dello stato lato server

Puoi utilizzare id di un'interazione completata in una chiamata successiva utilizzando il parametro previous_interaction_id per continuare la conversazione. Il server utilizza questo ID per recuperare la cronologia della conversazione, evitando di dover inviare nuovamente l'intera cronologia chat.

Il parametro previous_interaction_id conserva solo la cronologia della conversazione (input e output) utilizzando previous_interaction_id. Gli altri parametri sono ambito interazione e si applicano solo all'interazione specifica che stai generando:

  • tools
  • system_instruction
  • generation_config (inclusi thinking_level, temperature e così via)

Ciò significa che devi specificare nuovamente questi parametri in ogni nuova interazione se vuoi che vengano applicati. La gestione dello stato lato server è facoltativa. Puoi anche operare in modalità stateless inviando la cronologia completa della conversazione in ogni richiesta.

Archiviazione e conservazione dei dati

Per impostazione predefinita, l'API memorizza tutti gli oggetti Interaction (store=true) per semplificare l'utilizzo delle funzionalità di gestione dello stato lato server (con previous_interaction_id), l'esecuzione in background (utilizzando background=true) e per scopi di osservabilità.

  • Livello a pagamento: il sistema conserva le interazioni per 55 giorni.
  • Livello senza costi: il sistema conserva le interazioni per 1 giorno.

Se non vuoi che questo accada, puoi impostare store=false nella tua richiesta. Questo controllo è separato dalla gestione dello stato; puoi disattivare l'archiviazione per qualsiasi interazione. Tuttavia, tieni presente che store=false non è compatibile con background=true e impedisce l'utilizzo di previous_interaction_id per le svolte successive.

Puoi eliminare le interazioni memorizzate in qualsiasi momento utilizzando il metodo di eliminazione disponibile nella guida di riferimento API. Puoi eliminare le interazioni solo se conosci l'ID interazione.

Al termine del periodo di conservazione, i dati verranno eliminati automaticamente.

Il sistema elabora gli oggetti Interaction in base ai termini.

Best practice

  • Percentuale di successi della cache: l'utilizzo di previous_interaction_id per continuare le conversazioni consente al sistema di utilizzare più facilmente la memorizzazione nella cache implicita per la cronologia delle conversazioni, il che migliora le prestazioni e riduce i costi.
  • Interazioni di mix: hai la flessibilità di combinare le interazioni di Agente e Modello all'interno di una conversazione. Ad esempio, puoi utilizzare un agente specializzato, come l'agente Deep Research, per la raccolta iniziale dei dati e poi utilizzare un modello Gemini standard per le attività di follow-up, come il riepilogo o la riformattazione, collegando questi passaggi con previous_interaction_id.

Modelli e agenti supportati

Nome modello Tipo ID modello
Gemini 3.1 Flash-Lite Modello gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite (anteprima) Modello gemini-3.1-flash-lite-preview
Gemini 3.1 Pro (anteprima) Modello gemini-3.1-pro-preview
Gemini 3 Flash (anteprima) Modello gemini-3-flash-preview
Gemini 2.5 Pro Modello gemini-2.5-pro
Gemini 2.5 Flash Modello gemini-2.5-flash
Gemini 2.5 Flash-lite Modello gemini-2.5-flash-lite
Anteprima clip di Lyria 3 Modello lyria-3-clip-preview
Anteprima di Lyria 3 Pro Modello lyria-3-pro-preview
Anteprima di Deep Research Agente deep-research-pro-preview-12-2025
Anteprima di Deep Research Agente deep-research-preview-04-2026
Anteprima di Deep Research Agente deep-research-max-preview-04-2026

SDK

Puoi utilizzare l'ultima versione degli SDK Google GenAI per accedere all'API Interactions.

  • In Python, questo è il pacchetto google-genai dalla versione 1.55.0 in poi.
  • In JavaScript, questo è il pacchetto @google/genai dalla versione 1.33.0 in poi.

Puoi scoprire di più su come installare gli SDK nella pagina Librerie.

Limitazioni

  • Stato beta: l'API Interactions è in versione beta/anteprima. Funzionalità e schemi possono cambiare.
  • MCP remoto: Gemini 3 non supporta l'MCP remoto, ma sarà disponibile a breve.

Le seguenti funzionalità sono supportate dall'API generateContent, ma non sono ancora disponibili nell'API Interactions:

Modifiche che provocano un errore

L'API Interactions è attualmente in fase beta preliminare. Stiamo sviluppando e perfezionando attivamente le funzionalità dell'API, gli schemi delle risorse e le interfacce SDK in base all'utilizzo reale e al feedback degli sviluppatori.

Di conseguenza, potrebbero verificarsi modifiche che causano interruzioni. Gli aggiornamenti possono includere modifiche a:

  • Schemi per input e output.
  • Firme dei metodi SDK e strutture degli oggetti.
  • Comportamenti specifici delle funzionalità.

Per i workload di produzione, devi continuare a utilizzare l'API generateContent standard. Continua a essere il percorso consigliato per le implementazioni stabili e continueremo a svilupparlo e gestirlo attivamente.

Feedback

Il tuo feedback è fondamentale per lo sviluppo dell'API Interactions. Condividi le tue opinioni, segnala bug o richiedi funzionalità nel nostro forum della community di Google AI Developer.

Passaggi successivi