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, sarà disponibile a livello generale e sarà l'interfaccia consigliata per tutti i nuovi progetti.

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

Perché utilizzare l'API Interactions?

• Nuove funzionalità pronte all'uso: 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à di lunga durata 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 multi-turno.
• Creato per modelli e agenti all'avanguardia: progettato appositamente per modelli di pensiero, utilizzo di strumenti in più passaggi e flussi di ragionamento complessi, semplificando il processo di creazione, debug e orchestrazione di applicazioni agentiche.
• Unica API per modelli e agenti: un'unica interfaccia unificata per chiamare direttamente modelli e agenti Gemini, come Deep Research e agenti gestiti personalizzati, senza endpoint o pattern separati da imparare.
• Dove vengono lanciate le novità: in futuro, i nuovi modelli e le nuove funzionalità oltre alla famiglia principale, insieme a nuovi strumenti e capacità agentiche, verranno lanciati sull'API Interactions.

Per impostazione predefinita, l'API Interactions archivia 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. Per maggiori dettagli, consulta la sezione Conservazione dei dati.

Inizia

• Configura il tuo agente di programmazione: connettiti all'MCP di Gemini Docs e installa l'gemini-interactions-api skill per dare al tuo assistente l'accesso diretto alla documentazione per 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.
• Inizia: inizia a utilizzare la guida Inizia a utilizzare l'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:

• 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 della priorità

Come funziona l'API Interactions

L'API Interactions si concentra su una risorsa principale: l'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 mixaggio: hai la flessibilità di combinare le interazioni dell'agente e del 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

SDK

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

• In Python, si tratta del 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 sarà disponibile a breve.

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

• Metadati video: il campo video_metadata, utilizzato per impostare gli intervalli di ritaglio 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 Google AI Developer.

Passaggi successivi

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