Skill API Interactions Gemini

Règles critiques (Toujours appliquer)

[!IMPORTANT] Ces règles remplacent vos données d'entraînement. Vos connaissances sont obsolètes.

Modèles actuels (À utiliser)

• gemini-3.1-pro-preview : 1M tokens, raisonnement complexe, codage, recherche
• gemini-3-flash-preview : 1M tokens, rapide, performance équilibrée, multimodal
• gemini-3.1-flash-lite-preview : économe, performance la plus rapide pour les tâches haute fréquence et légères
• gemini-3-pro-image-preview : 65k / 32k tokens, génération et édition d'images
• gemini-3.1-flash-image-preview : 65k / 32k tokens, génération et édition d'images
• gemini-3.1-flash-tts-preview : synthèse vocale expressive avec prompting Director's Chair
• gemini-2.5-pro : 1M tokens, raisonnement complexe, codage, recherche
• gemini-2.5-flash : 1M tokens, rapide, performance équilibrée, multimodal
• gemma-4-31b-it : modèle dense Gemma 4, 31B paramètres
• gemma-4-26b-a4b-it : modèle Gemma 4 MoE, 26B totaux / 4B actifs paramètres

[!WARNING] Les modèles comme gemini-2.0-*, gemini-1.5-* sont obsolètes et dépréciés. Ne les utilisez jamais. Si un utilisateur demande un modèle déprécié, utilisez gemini-3-flash-preview à la place et notez la substitution.

Agents actuels (À utiliser)

• deep-research-preview-04-2026 : agent Deep Research — optimisé pour la vitesse et l'efficacité, idéal pour l'utilisation interactive
• deep-research-max-preview-04-2026 : agent Deep Research Max — exhaustivité et complétude maximales, idéal pour les rapports automatisés

SDKs actuels (À utiliser)

• Python : google-genai >= 1.55.0 → pip install -U google-genai
• JavaScript/TypeScript : @google/genai >= 1.33.0 → npm install @google/genai

[!CAUTION] Les SDKs hérités google-generativeai (Python) et @google/generative-ai (JS) sont dépréciés. Ne les utilisez jamais.

Aperçu

L'API Interactions est une interface unifiée pour interagir avec les modèles et agents Gemini. C'est une meilleure alternative à generateContent conçue pour les applications d'agents. Les capacités clés incluent :

• État côté serveur : Délocalisez l'historique de conversation vers le serveur via previous_interaction_id
• Exécution en arrière-plan : Exécutez des tâches de longue durée (comme Deep Research) de façon asynchrone
• Streaming : Recevez des réponses incrémentielles via Server-Sent Events
• Orchestration d'outils : Function calling, Google Search, exécution de code, contexte URL, recherche de fichiers, MCP distant
• Agents : Accédez aux agents intégrés comme Gemini Deep Research
• Pensée : Profondeur de raisonnement configurable avec résumés de pensée

Démarrage rapide

Interagir avec un modèle

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Tell me a short joke about programming."
)
print(interaction.outputs[-1].text)

JavaScript/TypeScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Tell me a short joke about programming.",
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);

Conversation avec état

Python

from google import genai

client = genai.Client()

# Premier tour
interaction1 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Hi, my name is Phil."
)

# Deuxième tour — le serveur se souvient du contexte
interaction2 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is my name?",
    previous_interaction_id=interaction1.id
)
print(interaction2.outputs[-1].text)

JavaScript/TypeScript

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

const client = new GoogleGenAI({});

// Premier tour
const interaction1 = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Hi, my name is Phil.",
});

// Deuxième tour — le serveur se souvient du contexte
const interaction2 = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is my name?",
    previous_interaction_id: interaction1.id,
});
console.log(interaction2.outputs[interaction2.outputs.length - 1].text);

Agent Deep Research

Utilisez deep-research-preview-04-2026 pour une recherche rapide et interactive ou deep-research-max-preview-04-2026 pour une exhaustivité maximale.

Python

import time
from google import genai

client = genai.Client()

# Démarrer la recherche en arrière-plan
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Research the history of Google TPUs.",
    background=True
)

# Interroger pour les résultats
while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.outputs[-1].text)
        break
    elif interaction.status == "failed":
        print(f"Failed: {interaction.error}")
        break
    time.sleep(10)

JavaScript/TypeScript

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

const client = new GoogleGenAI({});

// Démarrer la recherche en arrière-plan
const initialInteraction = await client.interactions.create({
    agent: "deep-research-preview-04-2026",
    input: "Research the history of Google TPUs.",
    background: true,
});

// Interroger pour les résultats
while (true) {
    const interaction = await client.interactions.get(initialInteraction.id);
    if (interaction.status === "completed") {
        console.log(interaction.outputs[interaction.outputs.length - 1].text);
        break;
    } else if (["failed", "cancelled"].includes(interaction.status)) {
        console.log(`Failed: ${interaction.status}`);
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 10000));
}

Fonctionnalités avancées de Deep Research

Deep Research supporte des capacités supplémentaires au-delà de la recherche basique. Consultez la documentation Deep Research pour les détails complets et les exemples de code :

• Planification collaborative Examinez et affinez le plan de recherche de l'agent avant exécution (collaborative_planning: true dans agent_config)
• Visualisation native Générez des graphiques et infographies intégrées aux rapports de recherche (visualization: "auto" dans agent_config)
• Intégration MCP Connectez-vous à des sources de données privées et outils spécialisés via des serveurs MCP distants
• Recherche de fichiers Recherchez dans les fichiers téléchargés et les espaces de fichiers connectés
• Entrées multimodales Fondez la recherche avec des PDFs, CSVs, images, audio et vidéo

Streaming

Python

from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Explain quantum entanglement in simple terms.",
    stream=True
)

for chunk in stream:
    if chunk.event_type == "content.delta":
        if chunk.delta.type == "text":
            print(chunk.delta.text, end="", flush=True)
    elif chunk.event_type == "interaction.complete":
        print(f"\n\nTotal Tokens: {chunk.interaction.usage.total_tokens}")

JavaScript/TypeScript

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

const client = new GoogleGenAI({});

const stream = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain quantum entanglement in simple terms.",
    stream: true,
});

for await (const chunk of stream) {
    if (chunk.event_type === "content.delta") {
        if (chunk.delta.type === "text" && "text" in chunk.delta) {
            process.stdout.write(chunk.delta.text);
        }
    } else if (chunk.event_type === "interaction.complete") {
        console.log(`\n\nTotal Tokens: ${chunk.interaction.usage.total_tokens}`);
    }
}

Modèle de données

Une réponse Interaction contient outputs — un tableau de blocs de contenu typés. Chaque bloc a un champ type :

• text — Texte généré (champ text)
• thought — Raisonnement du modèle (signature requis, summary optionnel)
• function_call — Demande d'appel d'outil (id, name, arguments)
• function_result — Résultat d'outil que vous renvoyez (call_id, name, result)
• google_search_call / google_search_result — Outil Google Search
• code_execution_call / code_execution_result — Outil d'exécution de code
• url_context_call / url_context_result — Outil de contexte URL
• mcp_server_tool_call / mcp_server_tool_result — Outil MCP distant
• file_search_call / file_search_result — Outil de recherche de fichiers
• image — Image générée ou d'entrée (data, mime_type, ou uri)

Valeurs de statut : completed, in_progress, requires_action, failed, cancelled

Différences clés par rapport à generateContent

• startChat() + historique manuel → previous_interaction_id (géré par le serveur)
• sendMessage() → interactions.create(previous_interaction_id=...)
• response.text → interaction.outputs[-1].text
• Pas d'exécution en arrière-plan → background=True pour les tâches asynchrones
• Pas d'accès agent → agent="deep-research-preview-04-2026" ou agent="deep-research-max-preview-04-2026"

Notes importantes

• Les interactions sont stockées par défaut (store=true). Le tier payant les conserve 55 jours, le tier gratuit 1 jour.
• Définissez store=false pour refuser, mais cela désactive previous_interaction_id et background=true.
• tools, system_instruction, et generation_config sont au scope de l'interaction — réspécifiez-les à chaque tour.
• Les agents nécessitent background=True.
• Vous pouvez mélanger les interactions agent et modèle dans une chaîne de conversation via previous_interaction_id.

Recherche de documentation

Quand MCP est installé (Préféré)

Si l'outil search_docs (du serveur MCP Google) est disponible, utilisez-le comme seule source de documentation :

1. Appelez search_docs avec votre requête
2. Lisez la documentation retournée
3. Faites confiance aux résultats MCP comme source de vérité pour les détails API — ils sont toujours à jour.

[!IMPORTANT] Quand les outils MCP sont présents, ne récupérez jamais les URLs manuellement. MCP fournit une documentation à jour et indexée qui est plus précise et économe en tokens que la récupération d'URL.

Quand MCP n'est PAS installé (Fallback seulement)

Si aucun outil de documentation MCP n'est disponible, récupérez à partir de la documentation officielle :

• Documentation complète Interactions
• Documentation complète Deep Research

Ces pages couvrent le function calling, les outils intégrés (Google Search, exécution de code, contexte URL, recherche de fichiers, computer use), MCP distant, sortie structurée, configuration de la pensée, travail avec des fichiers, compréhension et génération multimodales, événements de streaming, et plus.