API Interactions

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

Perché utilizzare l'API Interactions?

  • Interfaccia universale per tutte le applicazioni: progettata come interfaccia standard per ogni caso d'uso, tra cui la generazione di testo a un solo turno, la comprensione multimodale, gli output strutturati, l'orchestrazione degli strumenti e i flussi di lavoro degli agenti.
  • API singola per modelli e agenti: un unico endpoint e pattern per chiamare direttamente i modelli Gemini standard e gli agenti specializzati (come Deep Research e gli agenti gestiti personalizzati).
  • Nuove funzionalità pronte all'uso: funzionalità come lo stato della conversazione lato server opzionale utilizzando previous_interaction_id, passaggi di esecuzione osservabili per il debug e il rendering della UI ed esecuzione in background per le attività di lunga durata utilizzando background=true.
  • Costo inferiore con tassi di successo della cache più elevati: quando utilizzi 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 nell'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

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: 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 l'esecuzione in background e impedisce l'utilizzo di previous_interaction_id per i turni successivi.

Per i progetti del livello 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 dall'archiviazione del progetto, in AI Studio.

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

Gli oggetti delle interazioni 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 nel livello a pagamento. Puoi visualizzarli direttamente dalla pagina Log in Google AI Studio. Per saperne di più, consulta la Guida ai 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 (con stato) 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

Nome modello Tipo ID modello
Gemini 3.5 Flash Modello gemini-3.5-flash
Gemini 3.1 Pro (anteprima) Modello gemini-3.1-pro-preview
Gemini 3.1 Flash-Lite Modello gemini-3.1-flash-lite
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
Gemini 3 Pro Image Modello gemini-3-pro-image
Gemini 3.1 Flash Image Modello gemini-3.1-flash-image
Gemini 3.1 Flash TTS (anteprima) Modello gemini-3.1-flash-tts-preview
Gemma 4 31B IT Modello gemma-4-31b-it
Gemma 4 26B MoE IT Modello gemma-4-26b-a4b-it
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-preview-04-2026
Anteprima di Deep Research Agente deep-research-max-preview-04-2026
Anteprima di Antigravity Agente antigravity-preview-05-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 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.
  • Compatibilità del modello multi-turn: quando si combinano modelli diversi in una conversazione (con stato o senza stato), 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'API generateContent, ma non sono ancora disponibili 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 Google AI Developer.

Passaggi successivi