Guide du développeur de l'API Interactions

L'API Interactions fournit une interface unifiée avec état pour créer des applications d'IA générative avec des modèles Gemini et des agents autonomes sur Gemini Enterprise Agent Platform. Utilisez l'API Interactions pour gérer le stockage des sessions et les conversations multitours, diffuser des réponses en temps réel, appliquer des sorties structurées, appeler des outils intégrés et l'ancrage, exécuter des appels de fonction et orchestrer des tâches de longue durée en arrière-plan.

Ce guide vous explique comment installer le SDK Google Gen AI, authentifier votre client et implémenter des workflows d'interaction courants. Pour en savoir plus sur le cycle de vie des interactions, consultez la présentation de l'API Interactions.

Avant de commencer

Avant d'envoyer des requêtes à l'API Interactions, configurez votre projet Google Cloudet votre environnement de développement :

  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.

Concepts clés

Consultez les concepts suivants pour comprendre comment l'API Interactions gère l'état et les réponses :

  • Interaction : l'API Interactions s'articule autour d'une ressource principale : un Interaction. Un Interaction représente un tour complet dans une conversation ou une tâche, en suivant la chronologie des pensées du modèle, des appels d'outils et des résultats finaux. Il fournit une enveloppe unifiée pour les interactions prompt-réponse et les workflows agentiques complexes en plusieurs étapes.

  • Conservation avec état : les interactions sont stockées côté serveur par défaut (store=True en Python ou store: true en TypeScript/JavaScript). Les interactions stockées sont conservées pendant sept jours, puis sont automatiquement supprimées. La définition de store=False active le mode sans état, qui désactive la conservation côté serveur et est conforme à la conservation zéro des données (ZDR). Le mode sans état désactive également l'enchaînement previous_interaction_id et l'exécution asynchrone (background=True).

  • Assistants de réponse : la version 2.3.0 et les versions ultérieures du SDK Google Gen AI fournissent des propriétés pratiques sur la réponse d'interaction, y compris interaction.output_text, interaction.output_image et interaction.output_audio. Utilisez interaction.output_text pour lire les réponses textuelles au lieu d'indexer manuellement le tableau d'étapes (par exemple, interaction.steps[-1].content[0].text).

Conditions requises

Avant d'intégrer l'API Interactions, assurez-vous que votre environnement et vos requêtes répondent aux exigences suivantes :

  • Compatibilité avec les versions du SDK : utilisez l'une des bibliothèques du SDK Google Gen AI compatibles.

  • Modèles compatibles : utilisez les modèles Gemini 3 ou version ultérieure compatibles. Les familles de modèles antérieures ne sont pas compatibles avec cette API. Pour obtenir la liste complète des modèles compatibles, consultez Modèles compatibles et Migrer vers les dernières versions de modèles.

  • Paramètres limités au tour : les paramètres de configuration tels que tools, system_instruction et generation_config ne s'appliquent qu'au tour actuel. Transmettez ces paramètres à chaque tour d'interaction suivant si votre workflow les requiert dans une conversation multitour.

  • Décodages longs sur Gemini 4 Argon : pour générer des sorties à un seul tour dépassant 65 536 jetons (jusqu'à 1 048 576 jetons moins les jetons d'entrée) sur gemini-4-argon ou gemini-4-argon-cyber-permissive, utilisez la continuation automatique du SDK Google Gen AI (google-genai >= 2.34.0 pour Python, @google/genai >= 2.32.0 pour TypeScript/JavaScript, Go >= 1.77.0, Java >= 1.80.0), background=True ou continuation_token sur le point de terminaison v1beta1. Pour obtenir des exemples de code et des règles de continuation, consultez Long decodes in the developer's guide to Gemini 4 Argon (Décodages longs dans le guide du développeur pour Gemini 4 Argon).

Installer le SDK Google Gen AI

Installez ou mettez à niveau le SDK Google Gen AI pour le langage de votre choix :

Python

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

TypeScript / JavaScript

npm install "@google/genai>=2.3.0"

Go

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>

Authentifier votre client

Vous pouvez vous connecter à l'API Interactions sur Agent Platform à l'aide de l'une des méthodes d'authentification suivantes :

Se connecter à l'aide d'un projet Google Cloud avec les Identifiants par défaut de l'application (ADC)

Utilisez cette méthode d'authentification pour les charges de travail d'entreprise et les déploiements en production sur Google Cloud. Pour vous authentifier avec les identifiants par défaut de l'application (ADC), initialisez le client avec les propriétés suivantes :

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

Si vous n'avez pas encore configuré d'identifiants locaux, exécutez gcloud auth application-default login.

Dans l'exemple de code suivant, remplacez PROJECT_ID par l'ID de votre projetGoogle 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."
      }]
    }]
  }'

Se connecter en mode express (clé API)

Utilisez cette méthode d'authentification pour le prototypage rapide, les scripts légers ou les environnements qui s'authentifient avec une clé API. Transmettez votre clé API lors de l'initialisation du client ou dans l'en-tête HTTP x-goog-api-key.

Dans l'exemple de code suivant, remplacez API_KEY par votre clé API et PROJECT_ID par l'ID de votre projet 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."
      }]
    }]
  }'

Workflows d'interaction courants

Après avoir configuré votre client, vous pouvez utiliser la méthode interactions.create pour gérer le stockage de session et les conversations multitours, diffuser des jetons de sortie en temps réel, générer du JSON validé par un schéma, appeler des outils intégrés et l'ancrage, appeler des fonctions externes et exécuter des agents autonomes.

Gérer le stockage de session et l'état de la conversation

L'API Interactions est compatible avec le stockage avec état côté serveur (store=True, par défaut) et l'exécution sans état gérée par le client (store=False). Le tableau suivant compare les modes d'interaction avec et sans état :

Fonctionnalité Mode avec état (store=true, par défaut) Mode sans état (store=false)
Persistance côté serveur Stocke les entrées, les étapes intermédiaires et les sorties sur le serveur pendant sept jours. Désactive le stockage des interactions côté serveur pour prendre en charge les workflows de conservation zéro donnée (ZDR).
Contexte multitour Enchaîne les tours en transmettant l'interaction précédente id dans previous_interaction_id. Nécessite de transmettre l'intégralité du tableau de la conversation précédente steps dans input à chaque tour. La transmission de previous_interaction_id renvoie une erreur 400 Bad Request.
Exécution en arrière-plan (background=true) Compatible avec les interactions de longue durée entre les modèles et les agents. Non compatible L'exécution asynchrone en arrière-plan nécessite la persistance de l'état côté serveur.
Méthodes de cycle de vie de la session Permet de récupérer (get), de lister (list), d'annuler (cancel) et de supprimer (delete) des interactions. Non récupérable une fois la réponse synchrone ou en streaming terminée.
Chiffrement au repos Chiffré par défaut avec une Google-owned and Google-managed encryption keyou avec des clés de chiffrement gérées par le client (CMEK) dans les zones multirégionales us et eu. Aucun état d'interaction n'est stocké au repos.

Exécuter des conversations multitours avec état

Par défaut, l'API Interactions stocke l'état de la conversation sur le serveur (store=True en Python ou store: true en TypeScript/JavaScript). Pour poursuivre une conversation existante, transmettez l'id de l'interaction précédente au paramètre previous_interaction_id. La plate-forme d'agent récupère le contexte de conversation stocké, ajoute le nouveau tour et réutilise les jetons de préfixe mis en cache.

Lorsque vous enchaînez des interactions entre des points de terminaison, respectez les règles d'emplacement suivantes :

  • Même emplacement : vous pouvez enchaîner les interactions au même emplacement (par exemple, de global à global, de us à us ou de eu à eu).

  • Entre différents emplacements : le chaînage entre différents emplacements de points de terminaison (entre global et us ou eu, ou entre us et eu) n'est pas possible. Chaque point de terminaison stocke l'état d'interaction dans un espace de stockage isolé. Par conséquent, référencer un ID d'interaction créé dans un autre emplacement renvoie une erreur 404 Not Found.

Dans l'exemple suivant, remplacez PROJECT_ID par l'ID de votre projet 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?"
  }'

Exécuter des conversations multitours sans état

Si votre charge de travail nécessite la conservation zéro des données (ZDR), définissez explicitement store=False (store: false en TypeScript/JavaScript ou "store": false en REST) sur chaque requête.

En mode sans état, vous gérez l'historique des conversations sur le client en conservant une liste d'objets Step (user_input, thought, function_call, function_result et model_output) et en envoyant le tableau steps accumulé dans input à chaque tour :

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?"}]
      }
    ]
  }'

Conservation et cycle de vie des sessions

Les interactions stockées (store=True) suivent les règles de conservation et de branchement suivantes :

  • Valeur TTL (Time To Live) de sept jours : chaque interaction stockée est conservée pendant sept jours à compter de son code temporel created et est automatiquement supprimée à l'expiration de la valeur TTL de sept jours.

  • Stockage parent et enfant indépendant : lorsque vous enchaînez un nouveau tour à l'aide de previous_interaction_id, Agent Platform copie l'historique de la conversation ancêtre dans le nouvel enregistrement d'interaction. Étant donné que chaque tour stocke sa propre copie de l'historique des conversations, l'expiration ou la suppression d'un tour précédent a les effets suivants :

    • La poursuite à partir d'un tour ultérieur réussit : si le tour 1 (interaction_1) expire ou est supprimé après la création du tour 2 (interaction_2), vous pouvez toujours créer le tour 3 à l'aide de previous_interaction_id=interaction_2.id jusqu'à ce que interaction_2 expire ou soit supprimé.

    • Échec de la création d'une branche à partir d'un tour expiré ou supprimé : toute tentative de création d'une interaction référençant directement un ID d'interaction expiré ou supprimé dans previous_interaction_id renvoie une erreur 400 Bad Request (Previous Interaction ID not found).

Récupérer, lister, annuler et supprimer des interactions stockées

Vous pouvez inspecter et gérer les interactions stockées tout au long de leur cycle de vie à l'aide des méthodes suivantes :

  • Récupérer une interaction (interactions.get) : récupère la ressource Interaction complète par id, y compris les étapes user_input, les étapes intermédiaires thought et d'outil, et les étapes model_output. Définissez stream=True (et éventuellement last_event_id) pour diffuser ou reprendre une interaction en cours.

  • Lister les interactions (interactions.list) : interroge les ID d'interaction stockés dans votre projet via REST à l'aide de page_size (10 par défaut, 500 au maximum) et de page_token. Renvoie une liste de ressources InteractionMetadata.

  • Annuler une interaction en cours (interactions.cancel) : interrompt une interaction asynchrone en arrière-plan (background=True) qui est à l'état in_progress ou requires_action, et fait passer son état à cancelled. Les jetons générés avant la résiliation vous seront facturés.

  • Supprimer une interaction stockée (interactions.delete) : supprime définitivement une interaction stockée avant l'expiration de son TTL de 7 jours. Seules les interactions dans un état terminal (completed, failed ou cancelled) peuvent être supprimées. Si une interaction est toujours en cours d'exécution en arrière-plan, annulez-la avant de la supprimer.

Dans l'exemple suivant, remplacez PROJECT_ID par l'ID de votre projet Google Cloudet INTERACTION_ID par l'ID d'interaction cible :

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)"

Quotas et limites du stockage avec état

En plus des limites de jetons de modèle et de taux de requêtes, les interactions avec état (store=True) sont soumises aux limites de stockage et de simultanéité suivantes au niveau du projet :

Quota ou limite du système Limite par défaut (par projet) Description
Débit de création d'interactions avec état par jour 240 GiB par jour Volume total maximal de données d'interaction écrites dans l'espace de stockage côté serveur par jour pour les requêtes interactions.create avec store=true.
Débit de récupération des interactions avec état par jour 480 GiB par jour Volume total maximal de données d'interaction stockées lues par jour pour les requêtes interactions.get et les requêtes multitours qui chargent les tours précédents à l'aide de previous_interaction_id.
Interactions simultanées avec état 500 interactions simultanées Nombre maximal d'interactions avec état actives s'exécutant simultanément dans un projet.

Pour en savoir plus sur l'affichage et la gestion des quotas sur Agent Platform, consultez Quotas et limites du système.

Diffuser les réponses en temps réel

Pour réduire la latence perçue pour les applications interactives, vous pouvez diffuser les réponses du modèle à mesure qu'elles sont générées. Définissez stream=True (stream: true en TypeScript/JavaScript) lorsque vous appelez interactions.create pour recevoir un flux itérable d'événements envoyés par le serveur. Filtrez les événements step.delta pour afficher les fragments de texte incrémentiels à mesure qu'ils arrivent :

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();

Générer une sortie structurée

Lorsque votre application nécessite des réponses dans un format prévisible et lisible par machine, vous pouvez contraindre la sortie du modèle pour qu'elle corresponde à un schéma JSON spécifique. Transmettez votre schéma cible (par exemple, un schéma JSON de modèle Pydantic en Python ou un objet de schéma Type en TypeScript/JavaScript) directement au paramètre polymorphe 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);

Utiliser l'appel de fonction (utilisation d'outils)

L'appel de fonction permet à un modèle de demander l'exécution de fonctions personnalisées ou d'API externes pour collecter des informations avant de formuler une réponse finale. Dans un workflow d'interaction avec état, l'appel de fonction suit un modèle en deux tours :

  1. Déclarer et transmettre des outils : fournissez vos déclarations de fonction dans le paramètre tools de la requête initiale.

  2. Exécuter et renvoyer les résultats : inspectez les étapes de la réponse (interaction.steps) pour les étapes function_call, exécutez votre fonction locale à l'aide de l'élément arguments fourni par le modèle, puis envoyez une interaction de suivi contenant un élément function_result associé par call_id et 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);
    }
}

Utiliser des outils intégrés

En plus de l'appel de fonction côté client, l'API Interactions est compatible avec les outils intégrés côté serveur pour les modèles Gemini 3. Lorsque vous activez un outil intégré dans le paramètre tools, Agent Platform exécute l'outil sur le serveur lors d'un seul appel interactions.create et enregistre les étapes d'appel de l'outil (*_call) et de sortie (*_result) dans interaction.steps.

L'API Interactions est compatible avec les outils intégrés suivants :

  • Exécution de code ({"type": "code_execution"}) : génère et exécute du code Python dans un environnement de bac à sable pour effectuer des calculs, analyser des données et raisonner à partir du code. Pour en savoir plus sur les bibliothèques compatibles, la facturation et les limites, consultez Exécution de code.

  • Contexte d'URL ({"type": "url_context"}) : récupère et analyse le contenu des URL Web publiques incluses dans votre requête. Pour en savoir plus sur le cache d'index, les récupérations en direct et la combinaison du contexte de l'URL avec la recherche, consultez Contexte de l'URL.

  • Ancrage avec la recherche Google ({"type": "google_search"}) : ancre les réponses du modèle dans des informations Web en temps réel et renvoie des citations intégrées. Consultez Ancrer des réponses avec la recherche Google.

  • Utilisation de l'ordinateur ({"type": "computer_use"}) : active les workflows d'automatisation du navigateur et de l'interface utilisateur. Pour en savoir plus sur la configuration et les contrôles de sécurité, consultez Utilisation de l'ordinateur.

Exécuter du code Python

Pour activer l'exécution de code, incluez {"type": "code_execution"} dans la liste tools. Le tableau interaction.steps renvoyé contient les étapes code_execution_call (avec arguments.code et arguments.language), les étapes code_execution_result (avec result et is_error) et l'étape finale model_output.

Dans l'exemple suivant, remplacez PROJECT_ID par l'ID de votre projet 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"}]
  }'

Récupérer le contenu d'une page Web avec le contexte de l'URL

Pour permettre au modèle de récupérer et d'analyser les pages Web référencées dans votre requête, incluez {"type": "url_context"} dans la liste tools. L'API enregistre les URL récupérées aux étapes url_context_call et url_context_result, et associe des annotations url_citation au texte généré à l'étape model_output.

Dans l'exemple suivant, remplacez PROJECT_ID par l'ID de votre projet Google Cloud, et YOUR_URL_1 et YOUR_URL_2 par les URL publiques à comparer :

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"}]
  }'

Ancrer les réponses avec la recherche Google

L'ancrage connecte les modèles Gemini à des sources externes vérifiables pour réduire les hallucinations et fournir des réponses à jour avec des citations. Pour une présentation des options d'ancrage sur Agent Platform, consultez la présentation de l'ancrage, Ancrage avec la recherche Google et Ancrage Web pour Enterprise.

Lorsque vous activez l'ancrage avec la recherche Google en transmettant {"type": "google_search"} dans la liste tools, l'API Interactions renvoie les données de recherche et d'attribution directement dans la chronologie interaction.steps :

  • google_search_call : contient les requêtes de recherche émises par le modèle (step.arguments.queries).

  • google_search_result : contient des suggestions de recherche (result[].search_suggestions), un extrait HTML/CSS utilisé pour afficher les suggestions de recherche dans les interfaces utilisateur. Les ressources Web avec des URL sources et des titres sont fournies sous forme d'annotations url_citation intégrées dans les blocs de texte model_output.

  • Annotations url_citation intégrées : chaque bloc de contenu text (TextContent) d'une étape model_output peut inclure un tableau annotations. Chaque annotation url_citation identifie la plage de caractères ou d'octets (start_index et end_index) dans le texte de la réponse, ainsi que la source title et url.

Dans l'exemple suivant, remplacez PROJECT_ID par l'ID de votre projet 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 réponse inclut les étapes google_search_call, google_search_result et model_output avec des annotations url_citation intégrées :

{
  "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"
            }
          ]
        }
      ]
    }
  ]
}

Exécuter des agents et des tâches longues en arrière-plan

En plus des modèles de fondation, l'API Interactions vous permet d'appeler des agents autonomes spécialisés à l'aide du paramètre agent :

  • antigravity-preview-05-2026 : agent géré à usage général avec exécution de code, gestion de fichiers et navigateur Web dans un environnement Linux sécurisé en bac à sable. Pour en savoir plus, consultez Interagir avec les agents.
  • deep-research-preview-04-2026 : l'agent Gemini Deep Research, qui planifie et exécute des tâches de recherche Web en plusieurs étapes, et synthétise les résultats de plusieurs sources dans des rapports complets. Pour en savoir plus, consultez Utiliser l'agent Gemini Deep Research.
  • Agents personnalisés : ressources d'agent personnalisées configurées et provisionnées avec client.agents.create().

Comme les workflows d'agent prennent souvent plusieurs minutes, exécutez-les de manière asynchrone en arrière-plan en définissant background=True. L'API renvoie immédiatement un objet Interaction avec un id que vous pouvez interroger à l'aide de client.interactions.get() jusqu'à ce que interaction.status passe à completed :

Avant d'essayer cet exemple, remplacez PROJECT_ID par l'ID de votre projetGoogle 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)

Accéder aux fichiers Cloud Storage importés

Vous pouvez utiliser l'API Interactions pour accéder aux fichiers Cloud Storage importés. Dans l'exemple suivant, remplacez PROJECT_ID par l'ID de votre projetGoogle 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)

Lorsque vous transmettez des URI Cloud Storage (par exemple, gs://bucket-name/path/to/file) à l'API Interactions, les requêtes vérifient l'accès en lecture à l'aide des identifiants de l'appelant avant que l'agent de service Agent Platform du projet appelant (service-PROJECT_NUMBER@gcp-sa-aiplatform.) ne récupère l'objet depuis Cloud Storage.

Pour transmettre des fichiers Cloud Storage dans une requête d'interaction, le compte principal appelant (compte utilisateur, compte de service ou identité fédérée) doit disposer de l'autorisation storage.objects.get pour tous les objets référencés. Pour les buckets Cloud Storage multiprojets ou les buckets Cloud Storage avec des stratégies IAM personnalisées, accordez un accès en lecture au compte principal appelant et à l'agent de service du projet appelant.

Chaque requête d'interaction de modèle Gemini standard accepte jusqu'à 100 URI Cloud Storage (gs://) distincts (jusqu'à 2 Gio moins 500 Kio par fichier). Lorsque vous enchaînez des tours avec état à l'aide de previous_interaction_id, Agent Platform comptabilise les URI gs:// distincts de manière cumulative dans l'historique de la conversation et le tour actuel. Les interactions avec les agents gérés (requêtes qui définissent agent au lieu de model), les modèles Gemini Omni et les modèles Lyria 3 sont exclus de cette limite de 100 URI.

Configurer des rôles IAM pour accéder aux fichiers Cloud Storage

Attribuez l'un des rôles prédéfinis standards incluant l'autorisation storage.objects.get :

  • Lecteur des objets Storage (roles/storage.objectViewer) : accès en lecture aux objets (recommandé).

  • Utilisateur d'objets Storage (roles/storage.objectUser) : accès en lecture et en écriture aux objets.

Pour accorder l'accès à un compte utilisateur à l'aide de la Google Cloud CLI, utilisez la commande suivante :

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

Pour accorder l'accès à un compte de service appelant spécifique, utilisez la commande suivante :

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

Résoudre les problèmes d'accès aux fichiers Cloud Storage

Si le compte principal appelant ne dispose pas des autorisations suffisantes, l'API Interactions renvoie une erreur 403 Forbidden semblable à celle-ci :

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

Pour résoudre ce problème, attribuez le rôle Lecteur des objets Storage (roles/storage.objectViewer) sur le bucket ou l'objet Cloud Storage à l'appelant authentifié (et à l'agent de service Agent Platform du projet appelant pour les buckets Cloud Storage inter-projets ou IAM personnalisés).

Si l'objet spécifié n'existe pas ou si les autorisations du bucket empêchent l'appelant de voir si l'objet existe, l'API Interactions renvoie une erreur 404 Not Found semblable à celle-ci :

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

Pour résoudre ce problème, vérifiez que l'URI Cloud Storage est correct et que l'appelant authentifié dispose d'un accès en lecture au bucket.

Si une requête d'interaction de modèle fait référence à plus de 100 URI Cloud Storage distincts dans le tour actuel et l'historique previous_interaction_id associé, l'API Interactions renvoie une erreur 400 Bad Request semblable à celle-ci :

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

Pour résoudre ce problème, effectuez l'une des opérations suivantes :

  • Démarrez une nouvelle interaction sans previous_interaction_id lorsque les fichiers des tours précédents ne sont plus nécessaires.
  • Combinez des documents plus petits ou transmettez des fichiers supplémentaires de manière intégrée dans la limite de la charge utile de la requête (256 Mio compressés pour les requêtes synchrones ou de streaming, ou 9,75 Mio non compressés lorsque service_tier est défini sur deferred avec background et store définis sur true).
  • Utilisez generateContent pour les requêtes qui référencent des URI gs:// jusqu'aux limites d'éléments de modèle par modalité (3 000 images et PDF combinés, 1 000 fichiers audio et 10 vidéos, ou jusqu'à 6 500 fichiers lorsque vous incluez des fichiers en texte brut).

Chiffrer les données d'interaction avec des CMEK

Les interactions avec état (store=True en Python ou store: true en TypeScript/JavaScript) stockent les données d'interaction au repos pendant sept jours maximum. Pour protéger ces données avec votre propre clé de chiffrement au lieu d'une cléGoogle-owned and Google-managed encryption key, utilisez un profil de diffusion. Un profil de diffusion associe une clé Cloud Key Management Service à un projet, un emplacement et un champ d'application d'API. Tant qu'un profil de diffusion existe, Agent Platform chiffre automatiquement les données d'interaction stockées. Le format de votre requête d'interaction ne change pas.

La CMEK du profil de diffusion pour l'API Interactions est compatible avec les emplacements multirégionaux us et eu. La région global n'est pas disponible.

Pour configurer une CMEK pour l'API Interactions, procédez comme suit :

  1. Activez l'API Cloud KMS et l'API Agent Platform sur votre projet. Consultez la section Avant de commencer.
  2. Créez une clé Cloud KMS dans l'emplacement multirégional us ou eu. Consultez Créer un trousseau de clés et une clé.
  3. Attribuez à l'agent de service Gemini Enterprise Agent Platform le rôle roles/cloudkms.cryptoKeyEncrypterDecrypter sur la clé. Consultez Accorder des autorisations Agent Platform.

  4. Créez un profil de diffusion dans le même emplacement multirégional (us ou eu) qui définit scope sur INTERACTIONS_API et cmekConfig.encryptionSpec.kmsKeyName sur votre clé :

    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"
      }
    }
  }'

    Attendez que l'opération de création de longue durée se termine ("done": true). Pour en savoir plus sur la gestion, la mise à jour ou la suppression des profils de diffusion, consultez Créer un profil de diffusion.

  5. Envoyez vos requêtes d'interaction au même emplacement multirégional us ou eu que votre profil de diffusion. La clé CMEK du profil de diffusion n'est pas disponible sur le point de terminaison global.

    • SDK Google Gen AI : initialisez le client avec location="us" ou location="eu" (location: "us" ou location: "eu" en TypeScript/JavaScript).
    • REST : envoyez des requêtes au point de terminaison multirégional https://aiplatform.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/interactions, où LOCATION correspond à us ou eu.

    Si vous désactivez la clé ou révoquez l'accès de l'agent de service, les requêtes qui créent ou lisent des interactions stockées échouent avec une erreur FAILED_PRECONDITION.

Workflows REST avancés

Pour l'automatisation basée sur un shell, les pipelines CI/CD ou les environnements sans environnement d'exécution Python ou TypeScript/JavaScript, vous pouvez appeler l'API Interactions directement via HTTP à l'aide de curl.

Point de terminaison REST

Envoyez des requêtes POST au point de terminaison suivant de l'API Interactions :

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

Remplacez les variables suivantes dans vos requêtes :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : défini sur global (ou us ou eu avec l'hôte multirégional https://aiplatform.LOCATION.rep.googleapis.com pour la résidence des données ou les CMEK).

Définir les variables d'environnement et l'authentification

Avant d'exécuter les exemples curl des sections suivantes, exportez l'ID de votre projet, l'ID du modèle ou de l'agent cible, ainsi qu'un jeton d'accès OAuth 2.0 généré à partir des Identifiants par défaut de l'application :

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

Format de réponse synchrone

Une requête POST synchrone renvoie un objet JSON interaction qui inclut les métadonnées uniques d'interaction id, d'exécution status, de conversation steps et de jeton 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"
}

Poursuivre une interaction multitour avec état

Pour poursuivre une conversation stockée via REST, transmettez le id d'une réponse précédente dans le champ previous_interaction_id du corps de la requête JSON.

Avant d'essayer cet exemple, remplacez PREVIOUS_INTERACTION_ID par le id renvoyé par une interaction précédente.

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?"
      }]
    }]
  }'

Diffuser la sortie avec des événements envoyés par le serveur

Pour diffuser des mises à jour incrémentielles via REST, incluez "stream": true dans le corps de la requête 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."
      }]
    }]
  }'

Lorsque "stream": true est défini, le serveur répond avec Transfer-Encoding: chunked et Content-Type: text/event-stream (événements envoyés par le serveur). Chaque événement du flux inclut un préfixe data: contenant une charge utile JSON avec le contenu event_type et le delta de l'étape. curl maintient automatiquement la connexion HTTP ouverte et écrit les fragments entrants dans stdout en temps réel jusqu'à la fin de l'interaction.

Exécuter un agent géré en arrière-plan

Pour démarrer une tâche d'agent géré de longue durée de manière asynchrone via REST, spécifiez la cible agent, définissez "background": true et configurez "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."
      }]
    }]
  }'

Étapes suivantes

Consultez les ressources suivantes pour en savoir plus sur l'API Interactions, les outils intégrés et l'ancrage :