Guida per sviluppatori dell'API Interactions

L'API Interactions fornisce un'interfaccia unificata e stateful per la creazione di applicazioni di AI generativa con modelli Gemini e agenti autonomi su Gemini Enterprise Agent Platform. Utilizza l'API Interactions per gestire lo spazio di archiviazione delle sessioni e le conversazioni multi-turn, trasmettere in streaming le risposte in tempo reale, applicare output strutturati, richiamare strumenti integrati e grounding, eseguire chiamate di funzione e orchestrare attività in background a lunga esecuzione.

Questa guida mostra come installare l'SDK Google Gen AI, autenticare il client e implementare workflow di interazione comuni. Per dettagli concettuali sul ciclo di vita delle interazioni, consulta la panoramica dell'API Interactions.

Prima di iniziare

Prima di inviare richieste all'API Interactions, configura il tuo progetto Google Cloud e l'ambiente di sviluppo:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user)

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

Concetti fondamentali

Esamina i seguenti concetti per capire in che modo l'API Interactions gestisce lo stato e le risposte:

  • Interaction: L'API Interactions è incentrata su una risorsa fondamentale: unInteraction. Un Interaction rappresenta un turno completo in una conversazione o un'attività, monitorando la cronologia dei pensieri del modello, delle chiamate allo strumento e degli output finali. Fornisce un involucro unificato per le interazioni prompt-risposta e gli Agentic Workflows complessi in più passaggi.

  • Conservazione stateful: le interazioni vengono archiviate lato server per impostazione predefinita (store=True in Python o store: true in TypeScript/JavaScript). Le interazioni archiviate vengono conservate per 7 giorni e vengono eliminate automaticamente dopo questo periodo. L'impostazione store=False attiva la modalità stateless, che disattiva la conservazione lato server ed è conforme alla conservazione zero dei dati (ZDR, Zero Data Retention). La modalità stateless disattiva anche il concatenamento di previous_interaction_id e l'esecuzione asincrona (background=True).

  • Helper di risposta: l'SDK Google Gen AI versione 2.3.0 e successive fornisce proprietà di convenienza sulla risposta all'interazione, tra cui interaction.output_text, interaction.output_image e interaction.output_audio. Utilizza interaction.output_text per leggere le risposte di testo anziché indicizzare manualmente l'array di passaggi (ad esempio interaction.steps[-1].content[0].text).

Requisiti

Prima di eseguire l'integrazione con l'API Interactions, assicurati che l'ambiente e le richieste soddisfino i seguenti requisiti:

  • Supporto della versione dell'SDK: utilizza una delle librerie dell'SDK Google Gen AI supportate.

  • Modelli supportati: utilizza i modelli Gemini 3 supportati o versioni successive. Le famiglie di modelli precedenti non supportano questa API. Per un elenco completo dei modelli supportati, consulta Modelli supportati ed Esegui la migrazione alle versioni più recenti dei modelli.

  • Parametri con ambito di turno: i parametri di configurazione come tools, system_instruction e generation_config si applicano solo al turno corrente. Passa questi parametri a ogni turno di interazione successivo se il tuo workflow li richiede in una conversazione multi-turno.

  • Decodifiche lunghe su Gemini 4 Argon: per generare output single-turn che superano i 65.536 token (fino a 1.048.576 token meno i token di input) su gemini-4-argon o gemini-4-argon-cyber-permissive, utilizza la continuazione automatica dell'SDK Google Gen AI (google-genai >= 2.34.0 per Python, @google/genai >= 2.32.0 per TypeScript/JavaScript, Go >= 1.77.0, Java >= 1.80.0), background=True o continuation_token sull'endpoint v1beta1. Per esempi di codice e regole di continuazione, consulta Decodifiche lunghe nella guida per gli sviluppatori di Gemini 4 Argon.

Installa l'SDK Google Gen AI

Installa o esegui l'upgrade dell'SDK Google Gen AI per il linguaggio che preferisci:

Python

pip install --upgrade "google-genai>=2.3.0"

TypeScript / JavaScript

npm install "@google/genai>=2.3.0"

Vai

go get google.golang.org/genai

Java

<dependencies>
  <dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>1.78.0</version>
  </dependency>
</dependencies>

Autentica il tuo client

Puoi connetterti all'API Interactions su Agent Platform utilizzando uno dei seguenti metodi di autenticazione:

Connettiti utilizzando un progetto Google Cloud con le Credenziali predefinite dell'applicazione (ADC)

Utilizza questo metodo di autenticazione per i workload aziendali e i deployment di produzione su Google Cloud. Per eseguire l'autenticazione con le credenziali predefinite dell'applicazione (ADC), inizializza il client con le seguenti proprietà:

  • enterprise=True
  • project="PROJECT_ID"
  • location="global"

Se non hai ancora configurato le credenziali locali, esegui gcloud auth application-default login.

Nel seguente esempio di codice, sostituisci PROJECT_ID con l'ID progettoGoogle Cloud .

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

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

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

Connettiti utilizzando la modalità express (chiave API)

Utilizza questo metodo di autenticazione per la prototipazione rapida, gli script leggeri o gli ambienti che si autenticano con una chiave API. Passa la chiave API durante l'inizializzazione del client o nell'intestazione HTTP x-goog-api-key.

Nel seguente esempio di codice, sostituisci API_KEY con la tua chiave API e PROJECT_ID con l'ID progetto Google Cloud .

Python

from google import genai

client = genai.Client(
    enterprise=True,
    api_key="API_KEY",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain serverless computing in one sentence.",
)

print(interaction.output_text)

TypeScript / JavaScript

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

const ai = new GoogleGenAI({
    enterprise: true,
    apiKey: "API_KEY",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain serverless computing in one sentence.",
});

console.log(interaction.output_text);

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "x-goog-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

Workflow di interazione comuni

Dopo aver configurato il client, puoi utilizzare il metodo interactions.create per gestire lo spazio di archiviazione delle sessioni e le conversazioni multi-turn, eseguire lo streaming dei token di output in tempo reale, generare JSON convalidato dallo schema, richiamare strumenti integrati e grounding, chiamare funzioni esterne ed eseguire agenti autonomi.

Gestisci lo spazio di archiviazione della sessione e lo stato della conversazione

L'API Interactions supporta sia l'archiviazione stateful lato server (store=True, predefinita) sia l'esecuzione stateless gestita dal client (store=False). La tabella seguente mette a confronto le modalità di interazione stateful e stateless:

Funzionalità Modalità stateful (store=true, predefinita) Modalità stateless (store=false)
Persistenza lato server Memorizza input, passaggi intermedi e output sul server per 7 giorni. Disabilita l'archiviazione delle interazioni lato server per supportare i flussi di lavoro di conservazione zero dei dati (ZDR).
Contesto multi-turn Concatena i turni passando l'interazione precedente id in previous_interaction_id. Richiede il passaggio dell'intero array della conversazione precedente steps in input a ogni turno. Se passi previous_interaction_id, viene restituito un errore 400 Bad Request.
Esecuzione in background (background=true) Supportato per interazioni con modelli e agenti a lunga esecuzione. Non supportati. L'esecuzione asincrona in background richiede la persistenza dello stato lato server.
Metodi del ciclo di vita delle sessioni Supporta il recupero (get), l'elenco (list), l'annullamento (cancel) e l'eliminazione (delete) delle interazioni. Non recuperabile dopo il completamento della risposta sincrona o in streaming.
Crittografia at-rest Crittografato per impostazione predefinita con un Google-owned and Google-managed encryption keyo con chiavi di crittografia gestite dal cliente (CMEK) nelle multi-regioni us e eu. Nessuno stato di interazione viene archiviato at-rest.

Esegui conversazioni a più turni con stato

Per impostazione predefinita, l'API Interactions archivia lo stato della conversazione sul server (store=True in Python o store: true in TypeScript/JavaScript). Per continuare una conversazione esistente, passa il id dell'interazione precedente al parametro previous_interaction_id. La piattaforma dell'agente recupera il contesto della conversazione archiviato, aggiunge il nuovo turno e riutilizza i token di prefisso memorizzati nella cache.

Quando concateni le interazioni tra gli endpoint, osserva le seguenti regole di località:

  • Stessa località: puoi concatenare le interazioni all'interno della stessa località (ad esempio da global a global, da us a us o da eu a eu).

  • In località diverse: il concatenamento tra località di endpoint diverse (tra global e us o eu o tra us e eu) non è supportato. Ogni endpoint archivia lo stato dell'interazione in uno spazio di archiviazione isolato, pertanto il riferimento a un ID interazione creato in un'altra località restituisce un errore 404 Not Found.

Nell'esempio seguente, sostituisci PROJECT_ID con il tuo ID progetto Google Cloud:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Turn 1: Start a stateful conversation (store=True by default)
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi! My name is John. I am working on AI agents.",
    store=True,
)
print(f"Turn 1: {turn1.output_text}")

# Turn 2: Reference the stored conversation state using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id,
)
print(f"Turn 2: {turn2.output_text}")

TypeScript / JavaScript

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

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

// Turn 1: Start a stateful conversation (store: true by default)
const turn1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Hi! My name is John. I am working on AI agents.",
    store: true,
});
console.log(`Turn 1: ${turn1.output_text}`);

// Turn 2: Reference the stored conversation state using previous_interaction_id
const turn2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is my name?",
    previous_interaction_id: turn1.id,
});
console.log(`Turn 2: ${turn2.output_text}`);

Java

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 =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

// Turn 1: Start a stateful conversation (store is true by default)
CreateModelInteraction req1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Hi! My name is John. I am working on AI agents."))
        .store(true)
        .build();

Interaction turn1 =
    client.interactions.create(CreateInteractionRequestBody.of(req1)).interaction().orElseThrow();
System.out.println("Turn 1: " + turn1.outputText().orElse(""));

// Turn 2: Reference the stored conversation state using previousInteractionId
CreateModelInteraction req2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .previousInteractionId(turn1.id().orElseThrow())
        .input(InteractionsInput.of("What is my name?"))
        .build();

Interaction turn2 =
    client.interactions.create(CreateInteractionRequestBody.of(req2)).interaction().orElseThrow();
System.out.println("Turn 2: " + turn2.outputText().orElse(""));

REST

# Turn 1: Start a stateful conversation
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "store": true,
    "input": "Hi! My name is John. I am working on AI agents."
  }'

# Turn 2: Pass the interaction ID from Turn 1 in previous_interaction_id
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "input": "What is my name?"
  }'

Esegui conversazioni a più turni stateless

Se il tuo workload richiede la conservazione zero dei dati (ZDR), imposta esplicitamente store=False (store: false in TypeScript/JavaScript o "store": false in REST) su ogni richiesta.

In modalità stateless, gestisci la cronologia delle conversazioni sul client mantenendo un elenco di oggetti Step (user_input, thought, function_call, function_result e model_output) e inviando l'array steps accumulato in input a ogni turno:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

history = [
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "Hi! My name is John."}],
    }
]

# Turn 1: Stateless request (store=False)
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input=history,
    store=False,
)
print(f"Turn 1: {turn1.output_text}")

# Append the model's generated steps and the next user turn to local history
history.extend(turn1.steps)
history.append(
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "What is my name?"}],
    }
)

# Turn 2: Send the full step history with store=False
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input=history,
    store=False,
)
print(f"Turn 2: {turn2.output_text}")

TypeScript / JavaScript

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

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const history: Step[] = [
    {
        type: "user_input",
        content: [{ type: "text", text: "Hi! My name is John." }],
    },
];

// Turn 1: Stateless request (store: false)
const turn1 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: history,
    store: false,
});
console.log(`Turn 1: ${turn1.output_text}`);

// Append the model's generated steps and the next user turn to local history
if (turn1.steps) {
    history.push(...turn1.steps);
}
history.push({
    type: "user_input",
    content: [{ type: "text", text: "What is my name?" }],
});

// Turn 2: Send the full step history with store: false
const turn2 = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: history,
    store: false,
});
console.log(`Turn 2: ${turn2.output_text}`);

Java

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.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.UserInputContent;
import com.google.genai.gaos.models.interactions.UserInputStep;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.ArrayList;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

List<Step> history = new ArrayList<>();
history.add(
    Step.of(
        UserInputStep.builder()
            .content(
                List.of(
                    UserInputContent.of(
                        TextContent.builder().text("Hi! My name is John.").build())))
            .build()));

// Turn 1: Stateless request (store(false))
CreateModelInteraction req1 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofSteps(history))
        .store(false)
        .build();

Interaction turn1 =
    client.interactions.create(CreateInteractionRequestBody.of(req1)).interaction().orElseThrow();
System.out.println("Turn 1: " + turn1.outputText().orElse(""));

// Append the model's generated steps and the next user turn to local history
turn1.steps().ifPresent(history::addAll);
history.add(
    Step.of(
        UserInputStep.builder()
            .content(
                List.of(
                    UserInputContent.of(
                        TextContent.builder().text("What is my name?").build())))
            .build()));

// Turn 2: Send the full step history with store(false)
CreateModelInteraction req2 =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofSteps(history))
        .store(false)
        .build();

Interaction turn2 =
    client.interactions.create(CreateInteractionRequestBody.of(req2)).interaction().orElseThrow();
System.out.println("Turn 2: " + turn2.outputText().orElse(""));

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "store": false,
    "input": [
      {
        "type": "user_input",
        "content": [{"type": "text", "text": "Hi! My name is John."}]
      },
      {
        "type": "model_output",
        "content": [{"type": "text", "text": "Hello John! How can I help you today?"}]
      },
      {
        "type": "user_input",
        "content": [{"type": "text", "text": "What is my name?"}]
      }
    ]
  }'

Conservazione e ciclo di vita della sessione

Le interazioni archiviate (store=True) seguono queste regole di conservazione e ramificazione:

  • Durata (TTL) di 7 giorni: ogni interazione archiviata viene conservata per 7 giorni dal timestamp created e viene eliminata automaticamente alla scadenza del TTL di 7 giorni.

  • Archiviazione indipendente di elementi principali e secondari: quando concateni un nuovo turno utilizzando previous_interaction_id, Agent Platform copia la cronologia delle conversazioni precedenti nel nuovo record di interazione. Poiché ogni turno memorizza la propria copia della cronologia delle conversazioni, la scadenza o l'eliminazione di un turno precedente ha i seguenti effetti:

    • La continuazione da un turno successivo va a buon fine: se il Turno 1 (interaction_1) scade o viene eliminato dopo che il Turno 2 (interaction_2) è già stato creato, puoi comunque creare il Turno 3 utilizzando previous_interaction_id=interaction_2.id fino alla scadenza o all'eliminazione di interaction_2.

    • La ramificazione da un turno scaduto o eliminato non va a buon fine: il tentativo di creare una nuova interazione che fa riferimento direttamente a un ID interazione scaduto o eliminato in previous_interaction_id restituisce un errore 400 Bad Request (Previous Interaction ID not found).

Recuperare, elencare, annullare ed eliminare le interazioni archiviate

Puoi ispezionare e gestire le interazioni memorizzate durante il loro ciclo di vita utilizzando i seguenti metodi:

  • Recupera un'interazione (interactions.get): recupera la risorsa Interaction completa per id, inclusi i passaggi user_input, i passaggi intermedi thought e dello strumento e i passaggi model_output. Imposta stream=True (e l'opzione facoltativa last_event_id) per trasmettere in streaming o riprendere un'interazione in corso.

  • Elenca interazioni (interactions.list): esegue query sugli ID interazione archiviati nel progetto tramite REST utilizzando page_size (valore predefinito 10, massimo 500) e page_token. Restituisce un elenco di risorse InteractionMetadata.

  • Annulla un'interazione in corso (interactions.cancel): interrompe un'interazione asincrona in background (background=True) che si trova nello stato in_progress o requires_action e ne modifica lo stato in cancelled. Ti verranno addebitati i token generati prima dell'annullamento.

  • Elimina un'interazione archiviata (interactions.delete): rimuove definitivamente un'interazione archiviata prima della scadenza del TTL di 7 giorni. Solo le interazioni in uno stato terminale (completed, failed o cancelled) possono essere eliminate; se un'interazione è ancora in esecuzione in background, annullala prima di eliminarla.

Nell'esempio seguente, sostituisci PROJECT_ID con il tuo ID progetto Google Cloud e INTERACTION_ID con l'ID interazione target:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Retrieve a stored interaction by ID
interaction = client.interactions.get(id="INTERACTION_ID")
print(f"Status: {interaction.status}")

# Cancel an in-progress background interaction
cancelled = client.interactions.cancel(id="INTERACTION_ID")
print(f"After cancel: {cancelled.status}")

# Delete a completed, failed, or cancelled interaction before its 7-day TTL
client.interactions.delete(id="INTERACTION_ID")
print("Interaction deleted.")

TypeScript / JavaScript

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

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

// Retrieve a stored interaction by ID
const interaction = await ai.interactions.get("INTERACTION_ID");
console.log(`Status: ${interaction.status}`);

// Cancel an in-progress background interaction
const cancelled = await ai.interactions.cancel("INTERACTION_ID");
console.log(`After cancel: ${cancelled.status}`);

// Delete a completed, failed, or cancelled interaction before its 7-day TTL
await ai.interactions.delete("INTERACTION_ID");
console.log("Interaction deleted.");

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionStatus;
import com.google.genai.gaos.models.operations.CancelInteractionByIdResponse;
import com.google.genai.gaos.models.operations.GetInteractionByIdRequest;
import com.google.genai.gaos.models.operations.GetInteractionByIdResponse;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

String interactionId = "INTERACTION_ID";

// Retrieve a stored interaction by ID
GetInteractionByIdResponse getResponse =
    client.interactions.get(new GetInteractionByIdRequest(interactionId));
Interaction interaction = getResponse.interaction().orElseThrow();
System.out.println("Status: " + interaction.status().map(InteractionStatus::value).orElse(""));

// Cancel an in-progress background interaction
CancelInteractionByIdResponse cancelResponse = client.interactions.cancel(interactionId);
Interaction cancelled = cancelResponse.interaction().orElseThrow();
System.out.println("After cancel: " + cancelled.status().map(InteractionStatus::value).orElse(""));

// Delete a completed, failed, or cancelled interaction before its 7-day TTL
client.interactions.delete(interactionId);
System.out.println("Interaction deleted.");

REST

# Retrieve a stored interaction by ID
curl -X GET "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# List stored interactions (up to 500 per page)
curl -X GET "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions?page_size=10" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# Cancel an in-progress background interaction
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# Delete a completed, failed, or cancelled interaction
curl -X DELETE "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

Quote e limiti dello spazio di archiviazione stateful

Oltre ai limiti di token del modello e di tasso di richieste, le interazioni stateful (store=True) sono soggette ai seguenti limiti di archiviazione e contemporaneità a livello di progetto:

Quota o limite di sistema Limite predefinito (per progetto) Descrizione
Velocità effettiva di creazione delle interazioni stateful al giorno 240 GiB al giorno Volume totale massimo di dati di interazione scritti nello spazio di archiviazione lato server al giorno per interactions.create richieste con store=true.
Velocità effettiva di recupero delle interazioni stateful al giorno 480 GiB al giorno Volume totale massimo di dati di interazione archiviati letti al giorno per le richieste interactions.get e le richieste multi-turn che caricano i turni precedenti utilizzando previous_interaction_id.
Interazioni stateful simultanee 500 interazioni simultanee Numero massimo di interazioni stateful attive eseguite contemporaneamente in un progetto.

Per ulteriori informazioni sulla visualizzazione e sulla gestione delle quote su Agent Platform, consulta Quote e limiti di sistema.

Streaming delle risposte in tempo reale

Per ridurre la latenza percepita per le applicazioni interattive, puoi trasmettere in streaming le risposte del modello man mano che vengono generate. Imposta stream=True (stream: true in TypeScript/JavaScript) quando chiami interactions.create per ricevere uno stream iterabile di eventi inviati dal server. Filtra gli eventi step.delta per eseguire il rendering di blocchi di testo incrementali man mano che arrivano:

Python

response = client.interactions.create(
    model="gemini-3.8-flash",
    input="Write a short poem about debugging.",
    stream=True,
)

for event in response:
    if event.event_type == "step.delta" and hasattr(event.delta, "text"):
        print(event.delta.text, end="", flush=True)
print()

TypeScript / JavaScript

const responseStream = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Write a short poem about debugging.",
    stream: true,
});

for await (const event of responseStream) {
    if (event.event_type === "step.delta" && event.delta && "text" in event.delta) {
        process.stdout.write(event.delta.text);
    }
}
console.log();

Genera output strutturato

Quando la tua applicazione richiede risposte in un formato prevedibile e leggibile da macchina, puoi limitare l'output del modello in modo che corrisponda a uno schema JSON specifico. Passa lo schema di destinazione, ad esempio uno schema JSON del modello Pydantic in Python o un oggetto schema Type in TypeScript/JavaScript, direttamente al parametro polimorfico response_format:

Python

from pydantic import BaseModel, Field

class Book(BaseModel):
    title: str = Field(description="The title of the book")
    author: str = Field(description="The book's author")
    year_published: int

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Recommend one famous sci-fi book.",
    response_format=Book.model_json_schema(),
)

# The output text is valid JSON matching the Book schema
print(interaction.output_text)

TypeScript / JavaScript

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

const BookSchema = {
    type: Type.OBJECT,
    properties: {
        title: { type: Type.STRING, description: "The title of the book" },
        author: { type: Type.STRING, description: "The book's author" },
        yearPublished: { type: Type.INTEGER },
    },
    required: ["title", "author", "yearPublished"],
};

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Recommend one famous sci-fi book.",
    response_format: BookSchema,
});

console.log(interaction.output_text);

Utilizza la chiamata di funzione (utilizzo degli strumenti)

La chiamata di funzione consente a un modello di richiedere l'esecuzione di funzioni personalizzate o API esterne per raccogliere informazioni prima di formulare una risposta finale. In un workflow di interazione stateful, la chiamata di funzione segue un pattern a due turni:

  1. Dichiara e passa gli strumenti: fornisci le dichiarazioni delle funzioni nel parametro tools nella richiesta iniziale.

  2. Esegui e restituisci i risultati: esamina i passaggi della risposta (interaction.steps) per i passaggi function_call, esegui la funzione locale utilizzando il arguments fornito dal modello e invia un'interazione di follow-up contenente un elemento function_result collegato da call_id e previous_interaction_id.

Python

# Define a declarative function tool schema
stock_tool = {
    "type": "function",
    "name": "get_stock_price",
    "description": "Gets the stock price for a given ticker symbol.",
    "parameters": {
        "type": "object",
        "properties": {
            "ticker": {"type": "string", "description": "The stock ticker symbol"}
        },
        "required": ["ticker"],
    },
}

def get_stock_price(ticker: str) -> float:
    """Executes the local tool function."""
    if ticker.upper() == "GOOG":
        return 175.50
    return 100.0

# Turn 1: Pass the tool declaration to the model
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is the stock price of GOOG?",
    tools=[stock_tool],
)

# Inspect the interaction steps for function call requests
for step in interaction.steps:
    if step.type == "function_call" and step.name == "get_stock_price":
        ticker_arg = step.arguments.get("ticker")
        price = get_stock_price(ticker_arg)

        # Turn 2: Submit the function execution result to the conversation
        final_turn = client.interactions.create(
            model="gemini-3.8-flash",
            input=[{
                "type": "function_result",
                "call_id": step.id,
                "result": {"price": price},
            }],
            previous_interaction_id=interaction.id,
        )
        print(final_turn.output_text)

TypeScript / JavaScript

// Define a declarative function tool schema
const stockTool = {
    type: "function",
    name: "getStockPrice",
    description: "Gets the stock price for a given ticker symbol.",
    parameters: {
        type: "object",
        properties: {
            ticker: { type: "string", description: "The stock ticker symbol" },
        },
        required: ["ticker"],
    },
};

function getStockPrice({ ticker }: { ticker: string }): number {
    if (ticker.toUpperCase() === "GOOG") return 175.50;
    return 100.00;
}

// Turn 1: Pass the tool declaration to the model
const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "What is the stock price of GOOG?",
    tools: [stockTool],
});

// Inspect the interaction steps for function call requests
for (const step of interaction.steps ?? []) {
    if (step.type === "function_call" && step.name === "getStockPrice") {
        const tickerArg = step.arguments.ticker as string;
        const price = getStockPrice({ ticker: tickerArg });

        // Turn 2: Submit the function execution result to the conversation
        const finalTurn = await ai.interactions.create({
            model: "gemini-3.8-flash",
            input: [{
                type: "function_result",
                call_id: step.id,
                result: { price },
            }],
            previous_interaction_id: interaction.id,
        });
        console.log(finalTurn.output_text);
    }
}

Utilizza gli strumenti integrati

Oltre alla chiamata di funzione lato client, l'API Interactions supporta strumenti integrati lato server per i modelli Gemini 3. Quando attivi uno strumento integrato nel parametro tools, Agent Platform esegue lo strumento sul server durante una singola chiamata interactions.create e registra i passaggi di chiamata (*_call) e output (*_result) dello strumento in interaction.steps.

L'API Interactions supporta i seguenti strumenti integrati:

  • Esecuzione di codice ({"type": "code_execution"}): genera ed esegue codice Python in un ambiente sandbox per eseguire calcoli, analisi dei dati e ragionamenti basati sul codice. Per le librerie supportate, la fatturazione e le limitazioni, consulta Esecuzione di codice.

  • Contesto dell'URL ({"type": "url_context"}): recupera e analizza i contenuti degli URL web pubblici inclusi nel prompt. Per maggiori dettagli sulla memorizzazione nella cache degli indici, sui recuperi in tempo reale e sulla combinazione del contesto URL con la ricerca, consulta Contesto URL.

  • Grounding con la Ricerca Google ({"type": "google_search"}): basa le risposte del modello su informazioni web in tempo reale e restituisce citazioni incorporate. Consulta Fonda le risposte sulla Ricerca Google.

  • Utilizzo del computer ({"type": "computer_use"}): consente i workflow di automazione del browser e dell'interfaccia utente. Per i controlli di configurazione e sicurezza, consulta Utilizzo del computer.

Esegui codice Python

Per abilitare l'esecuzione del codice, includi {"type": "code_execution"} nell'elenco tools. L'array interaction.steps restituito contiene i passaggi code_execution_call (con arguments.code e arguments.language), i passaggi code_execution_result (con result e is_error) e il passaggio finale model_output.

Nell'esempio seguente, sostituisci PROJECT_ID con il tuo ID progetto Google Cloud:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Calculate the 50th Fibonacci number and find its closest prime.",
    tools=[{"type": "code_execution"}],
)

for step in interaction.steps:
    if step.type == "code_execution_call":
        print(f"Generated code:\n{step.arguments.code}")
    elif step.type == "code_execution_result":
        print(f"Execution result:\n{step.result}")
    elif step.type == "model_output":
        for content in step.content:
            if content.type == "text":
                print(content.text)

TypeScript / JavaScript

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

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Calculate the 50th Fibonacci number and find its closest prime.",
    tools: [{ type: "code_execution" }],
});

for (const step of interaction.steps ?? []) {
    if (step.type === "code_execution_call") {
        console.log(`Generated code:\n${step.arguments?.code}`);
    } else if (step.type === "code_execution_result") {
        console.log(`Execution result:\n${step.result}`);
    } else if (step.type === "model_output") {
        for (const content of step.content ?? []) {
            if (content.type === "text") {
                console.log(content.text);
            }
        }
    }
}

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;
import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;
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.interactions.Step;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Calculate the 50th Fibonacci number and find its closest prime."))
        .tools(List.of(CodeExecution.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().orElseThrow();

for (Step step : interaction.steps().orElse(List.of())) {
    if (step instanceof CodeExecutionCallStep callStep) {
        callStep
            .arguments()
            .flatMap(args -> args.code())
            .ifPresent(code -> System.out.println("Generated code:\n" + code));
    } else if (step instanceof CodeExecutionResultStep resultStep) {
        resultStep
            .result()
            .ifPresent(res -> System.out.println("Execution result:\n" + res));
    }
}
System.out.println(interaction.outputText().orElse(""));

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Calculate the 50th Fibonacci number and find its closest prime.",
    "tools": [{"type": "code_execution"}]
  }'

Recupera i contenuti delle pagine web con il contesto URL

Per consentire al modello di recuperare e analizzare le pagine web a cui viene fatto riferimento nel prompt, includi {"type": "url_context"} nell'elenco tools. L'API registra gli URL recuperati nei passaggi url_context_call e url_context_result e allega annotazioni url_citation al testo generato in model_output.

Nell'esempio seguente, sostituisci PROJECT_ID con il tuo ID progetto Google Cloud e YOUR_URL_1 e YOUR_URL_2 con gli URL pubblici da confrontare:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Compare the key findings from YOUR_URL_1 and YOUR_URL_2.",
    tools=[{"type": "url_context"}],
)

print(interaction.output_text)

TypeScript / JavaScript

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

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Compare the key findings from YOUR_URL_1 and YOUR_URL_2.",
    tools: [{ type: "url_context" }],
});

console.log(interaction.output_text);

Java

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.interactions.URLContext;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(
            InteractionsInput.of(
                "Compare the key findings from YOUR_URL_1 and YOUR_URL_2."))
        .tools(List.of(URLContext.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().orElseThrow();

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

REST

curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Compare the key findings from YOUR_URL_1 and YOUR_URL_2.",
    "tools": [{"type": "url_context"}]
  }'

Fonda le risposte sulla Ricerca Google

Il grounding collega i modelli Gemini a fonti esterne verificabili per ridurre le allucinazioni e fornire risposte aggiornate con citazioni. Per una panoramica delle opzioni di grounding su Agent Platform, consultare Panoramica sul grounding, Grounding con la Ricerca Google e Grounding Web per Enterprise.

Quando attivi il grounding con la Ricerca Google passando {"type": "google_search"} nell'elenco tools, l'API Interactions restituisce i dati di ricerca e attribuzione direttamente nella sequenza temporale interaction.steps:

  • google_search_call: contiene le query di ricerca eseguite dal modello (step.arguments.queries).

  • google_search_result: contiene i suggerimenti di ricerca (result[].search_suggestions), uno snippet HTML/CSS utilizzato per il rendering dei suggerimenti di ricerca nelle interfacce utente. Le risorse web con URL e titoli di origine vengono fornite come annotazioni url_citation in linea sui blocchi di testo model_output.

  • Annotazioni url_citation incorporate: ogni blocco di contenuti text (TextContent) all'interno di un passaggio model_output può includere un array annotations. Ogni annotazione url_citation identifica l'intervallo di caratteri o byte (start_index e end_index) nel testo della risposta insieme alla fonte title e url.

Nell'esempio seguente, sostituisci PROJECT_ID con il tuo ID progetto Google Cloud:

Python

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Who won the 2026 Super Bowl?",
    tools=[{"type": "google_search"}],
)

print(interaction.output_text)

# Parse inline url_citation annotations from model_output steps
print("\nSources:")
for step in interaction.steps:
    if step.type == "model_output" and step.content:
        for content in step.content:
            if content.type == "text" and getattr(content, "annotations", None):
                for annotation in content.annotations:
                    if annotation.type == "url_citation":
                        span = content.text[annotation.start_index:annotation.end_index]
                        print(f"- [{annotation.title}]({annotation.url}) (cited text: {span!r})")

TypeScript / JavaScript

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

const ai = new GoogleGenAI({
    enterprise: true,
    project: "PROJECT_ID",
    location: "global",
});

const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Who won the 2026 Super Bowl?",
    tools: [{ type: "google_search" }],
});

console.log(interaction.output_text);

// Parse inline url_citation annotations from model_output steps
console.log("\nSources:");
for (const step of interaction.steps ?? []) {
    if (step.type === "model_output") {
        for (const content of step.content ?? []) {
            if (content.type === "text" && content.annotations) {
                for (const annotation of content.annotations) {
                    if (annotation.type === "url_citation") {
                        const span = content.text.slice(
                            annotation.start_index,
                            annotation.end_index,
                        );
                        console.log(
                            `- [${annotation.title}](${annotation.url}) (cited text: "${span}")`,
                        );
                    }
                }
            }
        }
    }
}

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
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.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.URLCitation;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client =
    Client.builder()
        .enterprise(true)
        .project("PROJECT_ID")
        .location("global")
        .build();

CreateModelInteraction request =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Who won the 2026 Super Bowl?"))
        .tools(List.of(GoogleSearch.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(request)).interaction().orElseThrow();

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

// Parse inline URLCitation annotations from ModelOutputStep blocks
System.out.println("\nSources:");
for (Step step : interaction.steps().orElse(List.of())) {
    if (step instanceof ModelOutputStep outputStep) {
        for (Content content : outputStep.content().orElse(List.of())) {
            if (content instanceof TextContent textContent) {
                for (Annotation annotation : textContent.annotations().orElse(List.of())) {
                    if (annotation instanceof URLCitation citation) {
                        System.out.printf(
                            "- %s: %s (span: %d..%d)%n",
                            citation.title().orElse(""),
                            citation.url().orElse(""),
                            citation.startIndex().orElse(0L),
                            citation.endIndex().orElse(0L));
                    }
                }
            }
        }
    }
}

REST

# Request
curl -X POST "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Who won the 2026 Super Bowl?",
    "tools": [{"type": "google_search"}]
  }'

La risposta include i passaggi google_search_call, google_search_result e model_output con annotazioni url_citation in linea:

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROA",
  "model": "gemini-3.8-flash",
  "status": "completed",
  "steps": [
    {
      "type": "google_search_call",
      "id": "search_call_1",
      "arguments": {
        "queries": ["2026 Super Bowl winner"]
      }
    },
    {
      "type": "google_search_result",
      "call_id": "search_call_1",
      "result": [
        {
          "search_suggestions": "<!-- HTML and CSS for search suggestions -->"
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The Seattle Seahawks won Super Bowl LX on February 8, 2026.",
          "annotations": [
            {
              "type": "url_citation",
              "start_index": 0,
              "end_index": 59,
              "title": "Super Bowl LX",
              "url": "https://example.com/super-bowl-lx"
            }
          ]
        }
      ]
    }
  ]
}

Esegui agenti e attività in background di lunga durata

Oltre ai foundation model, l'API Interactions ti consente di richiamare agenti autonomi specializzati utilizzando il parametro agent:

  • antigravity-preview-05-2026: agente gestito per uso generico con esecuzione di codice, gestione dei file e browser web in un ambiente Linux sicuro in modalità sandbox. Per saperne di più, consulta Interagisci con gli agenti.
  • deep-research-preview-04-2026: l'agente Gemini Deep Research, che pianifica ed esegue attività di ricerca web in più passaggi e sintetizza i risultati di più fonti in report completi. Per saperne di più, consulta Utilizza l'agente Gemini Deep Research.
  • Agenti personalizzati: risorse degli agenti personalizzati configurate e di cui è stato eseguito il provisioning con client.agents.create().

Poiché i workflow degli agenti spesso richiedono diversi minuti per essere completati, eseguili in modo asincrono in background impostando background=True. L'API restituisce immediatamente un oggetto Interaction con un id di cui puoi eseguire il polling utilizzando client.interactions.get() finché interaction.status non passa a completed:

Prima di provare questo esempio, sostituisci PROJECT_ID con l'ID progettoGoogle Cloud .

import time
from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    input="Analyze competitive positioning for solar energy providers.",
    agent="deep-research-preview-04-2026",
    background=True,
)

print(f"Research started: {interaction.id}")

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.output_text)
        break
    elif interaction.status in ("failed", "cancelled"):
        print(f"Research ended with status: {interaction.status}")
        break
    time.sleep(10)

Accedi ai file Cloud Storage caricati

Puoi utilizzare l'API Interactions per accedere ai file Cloud Storage caricati. Nell'esempio seguente, sostituisci PROJECT_ID con l'ID progettoGoogle Cloud :

from google import genai

# Credentials must belong to an identity with storage.objects.get permissions
client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "user_input",
            "content": [
                {"type": "text", "text": "Summarize the attached document:"},
                {
                    "type": "document",
                    "uri": "gs://my-secure-bucket/quarterly_report.pdf",
                    "mime_type": "application/pdf",
                },
            ],
        }
    ],
)

print(interaction.output_text)

Quando passi gli URI Cloud Storage (ad esempio gs://bucket-name/path/to/file) all'API Interactions, le richieste verificano l'accesso in lettura utilizzando le credenziali del chiamante prima che l'agente di servizio della piattaforma agente del progetto chiamante (service-PROJECT_NUMBER@gcp-sa-aiplatform.) recuperi l'oggetto da Cloud Storage.

Per passare i file di Cloud Storage in una richiesta di interazione, l'entità chiamante (account utente, account di servizio o identità federata) deve disporre dell'autorizzazione storage.objects.get per tutti gli oggetti di riferimento. Per i bucket Cloud Storage tra progetti o i bucket Cloud Storage con policy IAM personalizzate, concedi l'accesso in lettura sia all'entità chiamante sia all'agente di servizio del progetto chiamante.

Ogni richiesta di interazione con il modello Gemini standard supporta fino a 100 URI Cloud Storage (gs://) distinti (fino a 2 GiB meno 500 KiB per file). Quando concateni turni stateful utilizzando previous_interaction_id, Agent Platform conteggia gli URI gs:// distinti in modo cumulativo nella cronologia della conversazione e nel turno corrente. Le interazioni con gli agenti gestiti (richieste che impostano agent anziché model), i modelli Gemini Omni e i modelli Lyria 3 sono esclusi da questo limite di 100 URI.

Configura i ruoli IAM per l'accesso ai file di Cloud Storage

Concedi uno dei ruoli predefiniti standard che includono l'autorizzazione storage.objects.get:

  • Storage Object Viewer (roles/storage.objectViewer): accesso in lettura agli oggetti (consigliato).

  • Storage Object User (roles/storage.objectUser): accesso in lettura e scrittura agli oggetti.

Per concedere l'accesso a un account utente utilizzando Google Cloud CLI, utilizza il seguente comando:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="user:user-email@example.com" \
    --role="roles/storage.objectViewer"

Per concedere l'accesso a un account di servizio chiamante specifico, utilizza il seguente comando:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="serviceAccount:sa-name@PROJECT_ID." \
    --role="roles/storage.objectViewer"

Risolvi i problemi di accesso ai file di Cloud Storage

Se l'entità chiamante non dispone di autorizzazioni sufficienti, l'API Interactions restituisce un errore 403 Forbidden simile al seguente:

Access error:
PERMISSION_DENIED - 403 Forbidden: Calling principal lacks
storage.objects.get on one or more Cloud Storage URIs.

Per risolvere il problema, concedi il ruolo Storage Object Viewer (roles/storage.objectViewer) sul bucket o sull'oggetto Cloud Storage al chiamante autenticato (e all'agente di servizio della piattaforma dell'agente del progetto chiamante per i bucket Cloud Storage tra progetti o IAM personalizzati).

Se l'oggetto specificato non esiste o se le autorizzazioni del bucket impediscono al chiamante di vedere se l'oggetto esiste, l'API Interactions restituisce un errore 404 Not Found simile al seguente:

Access error:
NOT_FOUND - 404 Not Found: The object does not exist, or bucket
permissions prevent revealing object existence.

Per risolvere il problema, verifica che l'URI Cloud Storage sia corretto e conferma che il chiamante autenticato abbia accesso in lettura al bucket.

Se una richiesta di interazione con il modello fa riferimento a più di 100 URI Cloud Storage distinti nel turno corrente e nella cronologia previous_interaction_id collegata, l'API Interactions restituisce un errore 400 Bad Request simile al seguente:

INVALID_ARGUMENT - 400 Bad Request: Request references 101 distinct gs:// URIs, which exceeds the maximum of 100.

Per risolvere questo problema, procedi in uno dei seguenti modi:

  • Avvia una nuova interazione senza previous_interaction_id quando i file dei turni precedenti non sono più necessari.
  • Combina documenti più piccoli o passa file aggiuntivi in linea entro il limite del payload della richiesta (256 MiB compressi per richieste sincrone o in streaming o 9, 75 MiB non compressi quando service_tier è impostato su deferred con background e store impostati su true).
  • Utilizza generateContent per le richieste che fanno riferimento agli URI gs:// fino ai limiti degli elementi del modello per modalità (3000 immagini e PDF combinati, 1000 file audio e 10 video o fino a 6500 file se includi file di testo normale).

Cripta i dati di interazione con CMEK

Le interazioni stateful (store=True in Python o store: true in TypeScript/JavaScript) archiviano i dati delle interazioni at-rest per un massimo di 7 giorni. Per proteggere i dati con la tua chiave di crittografia anziché con unaGoogle-owned and Google-managed encryption key, utilizza un profilo di pubblicazione. Un profilo di pubblicazione collega una chiave Cloud Key Management Service a un progetto, una località e un ambito API. Finché esiste un profilo di pubblicazione, Agent Platform cripta automaticamente i dati delle interazioni archiviati. Il formato della richiesta di interazione non cambia.

Il profilo di pubblicazione CMEK per l'API Interactions è supportato nelle multiregioni us e eu. La regione global non è supportata.

Per configurare CMEK per l'API Interactions, segui questi passaggi:

  1. Abilita l'API Cloud KMS e l'API Agent Platform nel tuo progetto. Vedi Prima di iniziare.
  2. Crea una chiave Cloud KMS nella multiregione us o eu. Consulta Crea chiavi automatizzate e una chiave.
  3. Concedi all'agente di servizio Gemini Enterprise Agent Platform il ruolo roles/cloudkms.cryptoKeyEncrypterDecrypter sulla chiave. Vedi Concedi le autorizzazioni di Agent Platform.

  4. Crea un profilo di pubblicazione nella stessa multi-regione (us o eu) che imposta scope su INTERACTIONS_API e cmekConfig.encryptionSpec.kmsKeyName sulla tua chiave:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/servingProfiles?servingProfileId=SERVING_PROFILE_ID" \
  -d '{
    "displayName": "Interactions API CMEK profile",
    "description": "CMEK for Interactions API",
    "scope": "INTERACTIONS_API",
    "cmekConfig": {
      "encryptionSpec": {
        "kmsKeyName": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME"
      }
    }
  }'

    Attendi il completamento dell'operazione di creazione a lunga esecuzione ("done": true). Per maggiori dettagli sulla gestione, l'aggiornamento o l'eliminazione dei profili di pubblicazione, consulta Crea un profilo di pubblicazione.

  5. Invia le richieste di interazione alla stessa località multiregionale us o eu del tuo profilo di pubblicazione. La CMEK del profilo di pubblicazione non è disponibile sull'endpoint global.

    • SDK Google Gen AI: inizializza il client con location="us" o location="eu" (location: "us" o location: "eu" in TypeScript/JavaScript).
    • REST: invia richieste all'endpoint multiregionale https://aiplatform.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/interactions, dove LOCATION è us o eu.

    Se disattivi la chiave o revochi l'accesso dell'agente di servizio, le richieste che creano o leggono le interazioni archiviate non vanno a buon fine e viene generato un errore FAILED_PRECONDITION.

Workflow REST avanzati

Per l'automazione basata su shell, le pipeline CI/CD o gli ambienti senza un runtime Python o TypeScript/JavaScript, puoi chiamare l'API Interactions direttamente tramite HTTP utilizzando curl.

Endpoint REST

Invia richieste POST al seguente endpoint API Interactions:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/interactions

Sostituisci le seguenti variabili nelle tue richieste:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: impostato su global (o us o eu con l'host multiregionale https://aiplatform.LOCATION.rep.googleapis.com per la residenza dei dati o CMEK CMEK).

Imposta le variabili di ambiente e l'autenticazione

Prima di eseguire gli esempi di curl nelle sezioni seguenti, esporta l'ID progetto, l'ID agente o modello di destinazione e un token di accesso OAuth 2.0 generato dalle Credenziali predefinite dell'applicazione:

PROJECT_ID="PROJECT_ID"
MODEL_ID="gemini-3.8-flash"
AGENT_ID="deep-research-preview-04-2026"
ACCESS_TOKEN=$(gcloud auth print-access-token)

Formato della risposta sincrona

Una richiesta POST sincrona restituisce un oggetto JSON interaction che include i metadati univoci di interazione id, esecuzione status, conversazione steps e token usage:

{
  "id": "your-interaction-id",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Serverless computing is a cloud execution model where the cloud provider dynamically manages the allocation and provisioning of servers, charging customers based on actual usage rather than pre-purchased capacity."
        }
      ]
    }
  ],
  "usage": {
    "total_tokens": 24751,
    "total_input_tokens": 23894,
    "total_output_tokens": 857
  },
  "created": "2026-05-08T10:44:43Z",
  "updated": "2026-05-08T10:44:43Z",
  "environment_id": "your-environment-id",
  "object": "interaction"
}

Continua un'interazione stateful a più turni

Per continuare una conversazione archiviata su REST, passa il valore id di una risposta precedente nel campo previous_interaction_id del corpo della richiesta JSON.

Prima di provare questo esempio, sostituisci PREVIOUS_INTERACTION_ID con il valore id restituito da un'interazione precedente.

curl -X POST "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "store": true,
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Can you elaborate on that?"
      }]
    }]
  }'

Output in streaming con eventi inviati dal server

Per trasmettere aggiornamenti incrementali tramite REST, includi "stream": true nel corpo della richiesta JSON:

curl -X POST "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Write a long story about space travel."
      }]
    }]
  }'

Quando "stream": true è impostato, il server risponde con Transfer-Encoding: chunked e Content-Type: text/event-stream (Server-Sent Events). Ogni evento nello stream include un prefisso data: contenente un payload JSON con i contenuti di event_type e del delta del passaggio. curl mantiene automaticamente aperta la connessione HTTP e scrive i chunk in entrata in stdout in tempo reale fino al completamento dell'interazione.

Esegui un agente gestito in background

Per avviare un'attività dell'agente gestito a lunga esecuzione in modo asincrono su REST, specifica il target agent, imposta "background": true e configura "environment": "remote":

curl -X POST "https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "'"${AGENT_ID}"'",
    "environment": "remote",
    "background": true,
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Analyze competitive positioning for commercial solar energy providers."
      }]
    }]
  }'

Passaggi successivi

Esplora le seguenti risorse per scoprire di più sull'API Interactions, sugli strumenti integrati e sul grounding: