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

• Configura il tuo agente di programmazione: connettiti all'MCP di Gemini Docs e installa l'gemini-api-dev skill per dare all'assistente l'accesso diretto alle ultime best practice e documentazione per sviluppatori. Per la procedura dettagliata, consulta la guida alla configurazione dell'agente di codifica.
• Esegui la migrazione da generateContent: se hai un'integrazione esistente, segui la guida alla migrazione per eseguire la transizione all'API Interactions.
• Inizia: segui i passaggi della 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 Flex
• 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:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'

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:

from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}

# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID"
  }'

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 di 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

• Percentuale di successi della cache: la memorizzazione implicita nella cache è 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

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.
• Su Go, questo è il pacchetto google.golang.org/genai.
• In Java, questo è il pacchetto com.google.genai:google-genai.

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:

• API batch
• Chiamata di funzione automatica (Python)
• Memorizzazione esplicita nella cache: tieni presente che la memorizzazione implicita nella cache 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 Google AI Developer.

Passaggi successivi

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