Guida per sviluppatori dell'API Interactions

Anteprima

Queste funzionalità sono ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini di servizio specifici e ai Termini aggiuntivi per i prodotti in anteprima dell'AI generativa. Puoi trattare i dati personali per questa funzionalità come indicato nell'Addendum per il trattamento dei dati Cloud, fatti salvi gli obblighi e le restrizioni all'interno dell'accordo che regola l'accesso a Google Cloud. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

L'API Interactions fornisce un'interfaccia unificata e stateful per creare applicazioni di AI generativa con modelli Gemini e agenti autonomi su Gemini Enterprise Agent Platform. Utilizza l'API Interactions per eseguire conversazioni multi-turno, trasmettere risposte in tempo reale, applicare output strutturati, eseguire chiamate di funzione e orchestrare attività in background a esecuzione prolungata.

Questa guida mostra come installare l'SDK Google Gen AI, autenticare il client e implementare i workflow di interazione comuni. Per informazioni concettuali sul ciclo di vita dell'interazione, 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:

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.
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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
Go to project selector
Verify that billing is enabled for your Google Cloud project.
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
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 email address for a Google Account.

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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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 email address for a Google Account.

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 principale: un Interaction. Un Interaction rappresenta un turno completo in una conversazione o un'attività, monitorando la cronologia dei pensieri del modello, delle chiamate agli strumenti e degli output finali. Fornisce un envelope unificato per interazioni prompt-risposta e workflow 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 memorizzate vengono conservate per 7 giorni ed eliminate automaticamente dopo questo periodo di tempo. L'impostazione store=False attiva la modalità stateless, che disattiva la conservazione lato server ed è conforme alla conservazione zero dei dati (ZDR). La modalità stateless disattiva anche l'incatenamento di previous_interaction_id e l'esecuzione asincrona (background=True).
• Helper per le risposte: SDK Google Gen AI versione 2.3.0 e successive fornisce proprietà di convenienza nella 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é eseguire l'indicizzazione manuale nell'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 delle versioni dell'SDK: utilizza l'SDK Google Gen AI unificato (>= 2.3.0 per Python o @google/genai >= 2.3.0 per TypeScript e JavaScript).

  • La versione 2.3.0 o successive è necessaria per le proprietà dell'helper per le risposte e le funzionalità dell'agente, mentre la versione 2.0.0 supporta lo schema steps di base.
  • Gli SDK legacy (google-cloud-aiplatform, @google-cloud/vertexai e google-generativeai) non supportano l'API Interactions.

• 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 e Eseguire la migrazione alle versioni più recenti dei modelli.

• Parametri a 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 flusso di lavoro li richiede in una conversazione multi-turno.

Suggerimento :se utilizzi un assistente di codifica AI, puoi installare la skill dell'agente API Interactions dal google/skillsrepository GitHub.

Installare l'SDK Google Gen AI

Installa o esegui l'upgrade dell'SDK Google Gen AI (>= 2.3.0) per la lingua che preferisci:

Python

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

TypeScript / JavaScript

npm install "@google/genai>=2.3.0"

Autenticare il client

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

• Google Cloud progetto con le Credenziali predefinite dell'applicazione
• Modalità express con una chiave API

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

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

• enterprise=True
• project= Google Cloud 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 il tuo ID progettoGoogle Cloud .

Nota :gli esempi di codice utilizzano gemini-3.8-flash come esempio. Per l'identificatore del modello più appropriato per il tuo caso d'uso, consulta Modelli supportati.

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/v1beta1/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": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Explain serverless computing in one sentence."
      }]
    }]
  }'

Suggerimento: puoi anche configurare l'SDK utilizzando le variabili di ambiente in modo che genai.Client() risolva automaticamente le impostazioni del progetto senza argomenti incorporati: export GOOGLE_GENAI_USE_ENTERPRISE=true, export GOOGLE_CLOUD_PROJECT="PROJECT_ID" e export GOOGLE_CLOUD_LOCATION="global".

Connettiti utilizzando la modalità express (chiave API)

Ti consigliamo di utilizzare questo metodo di autenticazione per la prototipazione rapida, script leggeri o ambienti che si autenticano con una chiave API. Trasmetti 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.

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/v1beta1/locations/global/interactions" \
  -H "x-goog-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [{
      "role": "user",
      "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 creare conversazioni multi-turno, trasmettere token di output in tempo reale, generare JSON con convalida dello schema, chiamare funzioni esterne ed eseguire agent autonomi.

Gestire conversazioni stateful a più turni

A differenza delle API di chat stateless che richiedono di inviare nuovamente la cronologia completa dei messaggi con ogni richiesta, l'API Interactions gestisce lo stato della conversazione sul server per impostazione predefinita (store=True in Python o store: true in TypeScript/JavaScript).

Per continuare una conversazione esistente, passa l'id dell'interazione precedente al parametro previous_interaction_id. Agent Platform recupera automaticamente il contesto della conversazione memorizzato e aggiunge il nuovo turno. Se imposti store=False (store: false in TypeScript/JavaScript), la persistenza lato server viene disattivata e non puoi concatenare i turni successivi con previous_interaction_id.

Python

# Turn 1: Start a 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

// Turn 1: Start a 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}`);

Visualizzare le risposte in streaming 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 un flusso iterabile di eventi inviati dal server. Filtra gli eventi step.delta per visualizzare i 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();

Generare output strutturato

Quando la tua applicazione richiede risposte in un formato prevedibile e leggibile dalla macchina, puoi vincolare 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);

Utilizzare la chiamata di funzione (utilizzo dello strumento)

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. Dichiarare e passare gli strumenti: fornisci le dichiarazioni delle funzioni nel parametro tools della richiesta iniziale.
2. Esegui e restituisci i risultati: esamina i passaggi di risposta (interaction.steps) per i passaggi function_call, esegui la funzione locale utilizzando 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);
    }
}

Eseguire agenti e attività in background lunghe

Oltre ai modelli di base, 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 navigazione web in un ambiente Linux sicuro in sandbox. Per saperne di più, vedi Interagire con gli agenti.
• deep-research-preview-04-2026: l'agente Gemini Deep Research, che pianifica ed esegue attività di ricerca sul web in più fasi e sintetizza i risultati di più fonti in report completi. Per saperne di più, consulta Utilizzare l'agente Gemini Deep Research.
• Agenti personalizzati: risorse dell'agente personalizzato configurate e sottoposte a provisioning con client.agents.create().

Nota: gli agenti gestiti vengono eseguiti autonomamente in ambienti di esecuzione cloud sicuri con accesso a strumenti di ricerca, ragionamento ed esecuzione in più passaggi.

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

Prima di provare questo esempio, sostituisci PROJECT_ID con il tuo Google Cloud ID progetto.

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)

Accedere ai file Cloud Storage caricati

Puoi utilizzare l'API Interactions per accedere ai file Cloud Storage caricati. Vedi il seguente esempio:

from google import genai

# Credentials must belong to an identity with storage.objects.get permissions
client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"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 URI Cloud Storage (ad esempio, gs://bucket-name/path/to/file) all'API Interactions, le richieste vengono valutate utilizzando le credenziali dell'utente finale. L'API recupera gli oggetti Cloud Storage utilizzando l'identità del chiamante autenticato anziché un agente di servizio del progetto in background.

Per trasmettere file 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 a cui viene fatto riferimento.

Configura i ruoli IAM per accedere ai file Cloud Storage

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

• Visualizzatore oggetti Storage (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 questo comando:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member="user:[e-mail]" \
    --role="roles/storage.objectViewer"

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

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

Risolvere i problemi di accesso ai file 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 GCS URIs.

Per risolvere il problema, concedi il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer) sul bucket o sull'oggetto al chiamante autenticato.

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.

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/interactions

Sostituisci le seguenti variabili nelle richieste:

• PROJECT_ID: l'ID progetto Google Cloud .
• LOCATION: impostato su global (o una regione personalizzata supportata, se richiesto dalla configurazione).

Imposta le variabili di ambiente e l'autenticazione

Prima di eseguire gli esempi curl nelle sezioni seguenti, esporta l'ID progetto, il modello o l'ID agente 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"
}

Continuare un'interazione stateful multi-turno

Per continuare una conversazione archiviata tramite REST, passa il valore di 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 id restituito da un'interazione precedente.

curl -X POST "https://aiplatform.googleapis.com/v1beta1/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": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Can you elaborate on that?"
      }]
    }]
  }'

Trasmettere l'output in streaming con Server-Sent Events

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

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_ID}"'",
    "stream": true,
    "input": [{
      "role": "user",
      "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 delta di event_type e dei passi. curl mantiene automaticamente aperta la connessione HTTP e scrive i chunk in arrivo in stdout in tempo reale fino al completamento dell'interazione.

Eseguire un agente gestito in background

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

curl -X POST "https://aiplatform.googleapis.com/v1beta1/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": [{
      "role": "user",
      "content": [{
        "type": "text",
        "text": "Analyze competitive positioning for commercial solar energy providers."
      }]
    }]
  }'

Passaggi successivi

• Scopri di più sui concetti chiave nella panoramica dell'API Interactions.
• Esplora gli schemi di richiesta e risposta nel riferimento API Interactions.
• Scopri come interagire con gli agenti gestiti e utilizzare l'agente Gemini Deep Research.