API Interactions

L'API Interactions è il modo migliore per creare con i modelli e gli agenti Gemini. A partire da giugno 2026, è disponibile a livello generale ed è consigliata per tutti i nuovi progetti. Sebbene ora sia considerata legacy, l'API originale generateContent rimane completamente supportata.

Perché utilizzare l'API Interactions?

• Interfaccia universale per tutte le applicazioni: progettata come interfaccia standard per ogni caso d'uso, inclusi la generazione di testo a turno singolo, la comprensione multimodale, gli output strutturati, l'orchestrazione degli strumenti e i flussi di lavoro agentici.
• Singola API per modelli e agenti: un endpoint e un pattern unificati per chiamare direttamente i modelli Gemini standard e gli agenti specializzati (come Deep Research e gli agenti gestiti personalizzati).
• Nuove funzionalità predefinite: funzionalità come lo 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: quando si utilizzano conversazioni multi-turno, la gestione dello stato lato server facoltativa consente una memorizzazione nella cache del contesto più efficiente tra i turni, riducendo i costi dei token.
• Dove vengono lanciate le nuove funzionalità: in futuro, tutti i nuovi modelli, le funzionalità multimodali , gli strumenti e le funzionalità agentiche 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 stateless impostando store=false. Per maggiori dettagli, consulta la sezione sulla conservazione dei dati.

Inizia

• Configura l'agente di programmazione: connettiti a Gemini Docs MCP e installa la skill gemini-api-dev per consentire all'assistente di accedere direttamente a documentazione per gli sviluppatori e best practice più recenti. Per la procedura dettagliata, consulta la guida Configurare l'agente di programmazione
• Esegui la migrazione da generateContent: se hai un'integrazione esistente, segui la Guida alla migrazione per passare all'API Interactions.
• Inizia: segui i passaggi descritti nella guida introduttiva all'API Interactions.

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 Flex
• 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à stateless 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à.

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

Se non vuoi che ciò 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.

Per i progetti con piano a pagamento, puoi configurare la finestra di conservazione in AI Studio per contrassegnare automaticamente i log per l'eliminazione dallo spazio di archiviazione del progetto dopo 7, 14, 28 o 55 giorni. Un periodo di conservazione più breve potrebbe influire sul recupero delle conversazioni passate.

Puoi eliminare le interazioni memorizzate in qualsiasi momento utilizzando il metodo delete a livello di programmazione, che richiede l'ID interazione. Puoi anche visualizzare e gestire i log delle interazioni memorizzate, inclusa l'eliminazione dallo spazio di archiviazione del progetto, in AI Studio.

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

Gli oggetti Interactions vengono elaborati in base ai termini.

Visualizzare le interazioni in AI Studio

L'API memorizza le richieste dell'API Interactions eseguite con store=true per i progetti con piano a pagamento. Puoi visualizzarli direttamente dalla pagina Log in Google AI Studio. Per saperne di più, consulta la guida Log.

Best practice

• Tasso di successo della cache: la memorizzazione nella cache implicita è supportata sia in modalità stateful che stateless (vedi Guida rapida). L'utilizzo di previous_interaction_id (stateful) 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.
• 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 MCP remoto, ma questa funzionalità sarà disponibile a breve.
• Compatibilità dei modelli a più turni: quando si combinano modelli diversi in una conversazione (stateful o stateless), i modelli successivi devono supportare le modalità di output dei modelli precedenti come input. Ad esempio, se generi un'immagine utilizzando gemini-3.1-flash-image, non puoi continuare la conversazione con un modello che non accetta input di immagini (ad esempio un modello solo di testo o un modello di generazione di musica come Lyria).

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

• 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.
• Impostazioni di sicurezza: le impostazioni di sicurezza personalizzate non sono supportate nell'API Interactions.

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.