API Interactions

L'API Interactions è la nostra nuova interfaccia e il modo più semplice per creare con i modelli e gli agenti Gemini. A partire da giugno 2026, è disponibile a livello generale ed è l'interfaccia consigliata per tutti i nuovi progetti.

Sebbene sia ora considerata legacy, l'API originale generateContent rimane completamente supportata.

Perché utilizzare l'API Interactions?

• Nuove funzionalità predefinite: 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.
• Costo inferiore con tassi di successo della cache più elevati: la gestione dello stato lato server consente una memorizzazione nella cache del contesto più efficiente tra i turni, riducendo i costi dei token per le conversazioni in più turni.
• Progettata per modelli e agenti di frontiera: appositamente progettata per i modelli di pensiero, l'utilizzo di strumenti in più passaggi e i flussi di ragionamento complessi, semplificando il processo di creazione, debug e orchestrazione delle applicazioni agentiche.
• Singola API per modelli e agenti: un'interfaccia unificata per chiamare direttamente i modelli e gli agenti Gemini, come Deep Research e gli agenti gestiti personalizzati, senza dover imparare endpoint o pattern separati.
• Dove vengono lanciate le novità: in futuro, i nuovi modelli e le nuove funzionalità oltre alla famiglia principale, insieme a nuove capacità agentiche e strumenti, verranno lanciati sull'API Interactions.

Per impostazione predefinita, l'API Interactions memorizza le richieste in modo che tu possa sfruttare le funzionalità di gestione dello stato lato server utilizzando previous_interaction_id. Puoi attivare il comportamento senza stato impostando store=false. Per i dettagli, consulta la sezione sulla conservazione dei dati.

Inizia

• Configura l'agente di codifica: connettiti all'MCP di Gemini Docs e installa la competenza gemini-interactions-api per consentire all'assistente di accedere direttamente a la documentazione per gli sviluppatori e alle best practice più recenti. Configura l'agente di codifica →
• Esegui la migrazione da generateContent: se hai un'integrazione esistente, segui la Guida alla migrazione per passare all'API Interactions.
• Inizia: consulta la Guida introduttiva all'API Interactions guide.

Guide alle funzionalità

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

• Generazione di testo
• Generazione di immagini
• Comprensione delle immagini
• Comprensione dell'audio
• Comprensione dei video
• Elaborazione dei documenti
• Chiamata di funzione
• Output strutturato
• Agente Deep Research
• Inferenza flessibile
• Inferenza prioritaria

Come funziona l'API Interactions

L'API Interactions è incentrata 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 l'model_output finale. La risorsa memorizzata (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 il id di un'interazione completata in una chiamata successiva utilizzando il previous_interaction_id parametro per continuare la conversazione. Il server utilizza questo ID per recuperare la cronologia delle conversazioni, evitando di dover inviare di nuovo l'intera cronologia chat.

Il parametro previous_interaction_id conserva solo la cronologia delle conversazioni (input e output) utilizzando previous_interaction_id. Gli altri parametri sono con ambito di 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 di nuovo questi parametri in ogni nuova interazione se vuoi che vengano applicati. Questa gestione dello stato lato server è facoltativa; puoi anche operare in modalità senza stato inviando la cronologia completa delle conversazioni 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 richiesta. Questo controllo è separato dalla gestione dello stato; puoi disattivare l'archiviazione per qualsiasi interazione. Tuttavia, tieni presente che store=false non è compatibile con l'esecuzione in background e impedisce l'utilizzo di previous_interaction_id per i turni successivi.

Puoi eliminare le interazioni memorizzate in qualsiasi momento utilizzando il metodo delete disponibile in Documentazione di riferimento dell'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

• Tasso di successo 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 il rendimento e riduce i costi.
• Combinazione di interazioni: hai la flessibilità di combinare le interazioni di agenti e modelli 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

SDK

Puoi utilizzare la versione più recente degli SDK Google GenAI per accedere all'API Interactions.

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

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

Limitazioni

• MCP remoto: Gemini 3 non supporta l'MCP remoto, ma questa funzionalità sarà disponibile a breve.

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

• Metadati video: il campo video_metadata, utilizzato per impostare gli intervalli di clipping e i frame rate personalizzati per la comprensione dei video.
• API batch
• Chiamata di funzione automatica (Python)
• Memorizzazione nella cache esplicita: tieni presente che la memorizzazione nella cache implicita lato server è disponibile nell'API Interactions tramite previous_interaction_id.

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 sviluppatori di Google AI.

Passaggi successivi

• Prova il notebook di avvio rapido dell'API Interactions.
• Scopri di più sull'agente Deep Research di Gemini.