Agent Gemini Deep Research

L'agent Gemini Deep Research planifie, exécute et synthétise de manière autonome des tâches de recherche en plusieurs étapes. Basé sur Gemini 3 Pro, il explore des ensembles d'informations complexes à l'aide de la recherche sur le Web et de vos propres données pour produire des rapports détaillés et sourcés.

Les tâches de recherche impliquent des recherches et des lectures itératives, et peuvent prendre plusieurs minutes. Vous devez utiliser l'exécution en arrière-plan (définir background=true) pour exécuter l'agent de manière asynchrone et interroger les résultats. Pour en savoir plus, consultez Gérer les tâches de longue durée.

L'exemple suivant montre comment démarrer une tâche de recherche en arrière-plan et interroger les résultats.

Python

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    input="Research the history of Google TPUs.",
    agent='deep-research-pro-preview-12-2025',
    background=True
)

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

while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.outputs[-1].text)
        break
    elif interaction.status == "failed":
        print(f"Research failed: {interaction.error}")
        break
    time.sleep(10)

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    input: 'Research the history of Google TPUs.',
    agent: 'deep-research-pro-preview-12-2025',
    background: true
});

console.log(`Research started: ${interaction.id}`);

while (true) {
    const result = await client.interactions.get(interaction.id);
    if (result.status === 'completed') {
        console.log(result.outputs[result.outputs.length - 1].text);
        break;
    } else if (result.status === 'failed') {
        console.log(`Research failed: ${result.error}`);
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 10000));
}

REST

# 1. Start the research task
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Research the history of Google TPUs.",
    "agent": "deep-research-pro-preview-12-2025",
    "background": true
}'

# 2. Poll for results (Replace INTERACTION_ID)
# curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID" \
# -H "x-goog-api-key: $GEMINI_API_KEY"

Faire des recherches avec vos propres données

Deep Research a accès à différents outils. Par défaut, l'agent a accès aux informations sur l'Internet public à l'aide des outils google_search et url_context. Vous n'avez pas besoin de spécifier ces outils par défaut. Toutefois, si vous souhaitez également donner à l'agent l'accès à vos propres données à l'aide de l'outil Recherche de fichiers, vous devrez l'ajouter comme indiqué dans l'exemple suivant.

Python

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    input="Compare our 2025 fiscal year report against current public web news.",
    agent="deep-research-pro-preview-12-2025",
    background=True,
    tools=[
        {
            "type": "file_search",
            "file_search_store_names": ['fileSearchStores/my-store-name']
        }
    ]
)

JavaScript

const interaction = await client.interactions.create({
    input: 'Compare our 2025 fiscal year report against current public web news.',
    agent: 'deep-research-pro-preview-12-2025',
    background: true,
    tools: [
        { type: 'file_search', file_search_store_names: ['fileSearchStores/my-store-name'] },
    ]
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Compare our 2025 fiscal year report against current public web news.",
    "agent": "deep-research-pro-preview-12-2025",
    "background": true,
    "tools": [
        {"type": "file_search", "file_search_store_names": ["fileSearchStores/my-store-name"]},
    ]
}'

Orientation et mise en forme

Vous pouvez orienter la sortie de l'agent en fournissant des instructions de mise en forme spécifiques dans votre requête. Cela vous permet de structurer les rapports en sections et sous-sections spécifiques, d'inclure des tableaux de données ou d'adapter le ton pour différentes audiences (par exemple, "technical", "executive", "casual").

Définissez explicitement le format de sortie souhaité dans votre texte d'entrée.

Python

prompt = """
Research the competitive landscape of EV batteries.

Format the output as a technical report with the following structure:
1. Executive Summary
2. Key Players (Must include a data table comparing capacity and chemistry)
3. Supply Chain Risks
"""

interaction = client.interactions.create(
    input=prompt,
    agent="deep-research-pro-preview-12-2025",
    background=True
)

JavaScript

const prompt = `
Research the competitive landscape of EV batteries.

Format the output as a technical report with the following structure:
1. Executive Summary
2. Key Players (Must include a data table comparing capacity and chemistry)
3. Supply Chain Risks
`;

const interaction = await client.interactions.create({
    input: prompt,
    agent: 'deep-research-pro-preview-12-2025',
    background: true,
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Research the competitive landscape of EV batteries.\n\nFormat the output as a technical report with the following structure: \n1. Executive Summary\n2. Key Players (Must include a data table comparing capacity and chemistry)\n3. Supply Chain Risks",
    "agent": "deep-research-pro-preview-12-2025",
    "background": true
}'

Gérer les tâches de longue durée

Deep Research est un processus en plusieurs étapes qui comprend la planification, la recherche, la lecture et l'écriture. Ce cycle dépasse généralement les limites de délai d'attente standards des appels d'API synchrones.

Les agents sont tenus d'utiliser background=True. L'API renvoie immédiatement un objet Interaction partiel. Vous pouvez utiliser la propriété id pour récupérer une interaction pour le polling. L'état de l'interaction passera de in_progress à completed ou failed.

Streaming

Deep Research est compatible avec le streaming pour recevoir des informations en temps réel sur l'avancement de la recherche. Vous devez définir stream=True et background=True.

L'exemple suivant montre comment démarrer une tâche de recherche et traiter le flux. Plus précisément, il montre comment suivre le interaction_id à partir de l'événement interaction.start. Vous aurez besoin de cet ID pour reprendre le flux en cas d'interruption du réseau. Ce code introduit également une variable event_id qui vous permet de reprendre la lecture à l'endroit précis où vous l'avez interrompue.

Python

stream = client.interactions.create(
    input="Research the history of Google TPUs.",
    agent="deep-research-pro-preview-12-2025",
    background=True,
    stream=True,
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto"
    }
)

interaction_id = None
last_event_id = None

for chunk in stream:
    if chunk.event_type == "interaction.start":
        interaction_id = chunk.interaction.id
        print(f"Interaction started: {interaction_id}")

    if chunk.event_id:
        last_event_id = chunk.event_id

    if chunk.event_type == "content.delta":
        if chunk.delta.type == "text":
            print(chunk.delta.text, end="", flush=True)
        elif chunk.delta.type == "thought_summary":
            print(f"Thought: {chunk.delta.content.text}", flush=True)

    elif chunk.event_type == "interaction.complete":
        print("\nResearch Complete")

JavaScript

const stream = await client.interactions.create({
    input: 'Research the history of Google TPUs.',
    agent: 'deep-research-pro-preview-12-2025',
    background: true,
    stream: true,
    agent_config: {
        type: 'deep-research',
        thinking_summaries: 'auto'
    }
});

let interactionId;
let lastEventId;

for await (const chunk of stream) {
    // 1. Capture Interaction ID
    if (chunk.event_type === 'interaction.start') {
        interactionId = chunk.interaction.id;
        console.log(`Interaction started: ${interactionId}`);
    }

    // 2. Track IDs for potential reconnection
    if (chunk.event_id) lastEventId = chunk.event_id;

    // 3. Handle Content
    if (chunk.event_type === 'content.delta') {
        if (chunk.delta.type === 'text') {
            process.stdout.write(chunk.delta.text);
        } else if (chunk.delta.type === 'thought_summary') {
            console.log(`Thought: ${chunk.delta.content.text}`);
        }
    } else if (chunk.event_type === 'interaction.complete') {
        console.log('\nResearch Complete');
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Research the history of Google TPUs.",
    "agent": "deep-research-pro-preview-12-2025",
    "background": true,
    "stream": true,
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto"
    }
}'
# Note: Look for the 'interaction.start' event to get the interaction ID.

Reconnexion au flux

Des interruptions du réseau peuvent se produire lors de tâches de recherche de longue durée. Pour gérer cela de manière optimale, votre application doit détecter les erreurs de connexion et reprendre le flux à l'aide de client.interactions.get().

Vous devez fournir deux valeurs pour reprendre :

  1. ID d'interaction : obtenu à partir de l'événement interaction.start dans le flux initial.
  2. ID du dernier événement : ID du dernier événement traité avec succès. Cela indique au serveur de reprendre l'envoi d'événements après ce point spécifique. Si vous ne le fournissez pas, vous obtiendrez le début du flux.

Les exemples suivants illustrent un modèle résilient : tentative de diffusion en continu de la requête create initiale et retour à une boucle get si la connexion est interrompue.

Python

import time
from google import genai

client = genai.Client()

# Configuration
agent_name = 'deep-research-pro-preview-12-2025'
prompt = 'Compare golang SDK test frameworks'

# State tracking
last_event_id = None
interaction_id = None
is_complete = False

def process_stream(event_stream):
    """Helper to process events from any stream source."""
    global last_event_id, interaction_id, is_complete
    for event in event_stream:
        # Capture Interaction ID
        if event.event_type == "interaction.start":
            interaction_id = event.interaction.id
            print(f"Interaction started: {interaction_id}")

        # Capture Event ID
        if event.event_id:
            last_event_id = event.event_id

        # Print content
        if event.event_type == "content.delta":
            if event.delta.type == "text":
                print(event.delta.text, end="", flush=True)
            elif event.delta.type == "thought_summary":
                print(f"Thought: {event.delta.content.text}", flush=True)

        # Check completion
        if event.event_type in ['interaction.complete', 'error']:
            is_complete = True

# 1. Attempt initial streaming request
try:
    print("Starting Research...")
    initial_stream = client.interactions.create(
        input=prompt,
        agent=agent_name,
        background=True,
        stream=True,
        agent_config={
            "type": "deep-research",
            "thinking_summaries": "auto"
        }
    )
    process_stream(initial_stream)
except Exception as e:
    print(f"\nInitial connection dropped: {e}")

# 2. Reconnection Loop
# If the code reaches here and is_complete is False, we resume using .get()
while not is_complete and interaction_id:
    print(f"\nConnection lost. Resuming from event {last_event_id}...")
    time.sleep(2) 

    try:
        resume_stream = client.interactions.get(
            id=interaction_id,
            stream=True,
            last_event_id=last_event_id
        )
        process_stream(resume_stream)
    except Exception as e:
        print(f"Reconnection failed, retrying... ({e})")

JavaScript

let lastEventId;
let interactionId;
let isComplete = false;

// Helper to handle the event logic
const handleStream = async (stream) => {
    for await (const chunk of stream) {
        if (chunk.event_type === 'interaction.start') {
            interactionId = chunk.interaction.id;
        }
        if (chunk.event_id) lastEventId = chunk.event_id;

        if (chunk.event_type === 'content.delta') {
            if (chunk.delta.type === 'text') {
                process.stdout.write(chunk.delta.text);
            } else if (chunk.delta.type === 'thought_summary') {
                console.log(`Thought: ${chunk.delta.content.text}`);
            }
        } else if (chunk.event_type === 'interaction.complete') {
            isComplete = true;
        }
    }
};

// 1. Start the task with streaming
try {
    const stream = await client.interactions.create({
        input: 'Compare golang SDK test frameworks',
        agent: 'deep-research-pro-preview-12-2025',
        background: true,
        stream: true,
        agent_config: {
            type: 'deep-research',
            thinking_summaries: 'auto'
        }
    });
    await handleStream(stream);
} catch (e) {
    console.log('\nInitial stream interrupted.');
}

// 2. Reconnect Loop
while (!isComplete && interactionId) {
    console.log(`\nReconnecting to interaction ${interactionId} from event ${lastEventId}...`);
    try {
        const stream = await client.interactions.get(interactionId, {
            stream: true,
            last_event_id: lastEventId
        });
        await handleStream(stream);
    } catch (e) {
        console.log('Reconnection failed, retrying in 2s...');
        await new Promise(resolve => setTimeout(resolve, 2000));
    }
}

REST

# 1. Start the research task (Initial Stream)
# Watch for event: interaction.start to get the INTERACTION_ID
# Watch for "event_id" fields to get the LAST_EVENT_ID
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Compare golang SDK test frameworks",
    "agent": "deep-research-pro-preview-12-2025",
    "background": true,
    "stream": true,
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto"
    }
}'

# ... Connection interrupted ...

# 2. Reconnect (Resume Stream)
# Pass the INTERACTION_ID and the LAST_EVENT_ID you saved.
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID?stream=true&last_event_id=LAST_EVENT_ID&alt=sse" \
-H "x-goog-api-key: $GEMINI_API_KEY"

Questions et interactions complémentaires

Vous pouvez poursuivre la conversation après que l'agent a renvoyé le rapport final en utilisant previous_interaction_id. Cela vous permet de demander des clarifications, des résumés ou des détails sur des sections spécifiques de la recherche sans avoir à redémarrer l'ensemble de la tâche.

Python

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    input="Can you elaborate on the second point in the report?",
    model="gemini-3-pro-preview",
    previous_interaction_id="COMPLETED_INTERACTION_ID"
)

print(interaction.outputs[-1].text)

JavaScript

const interaction = await client.interactions.create({
    input: 'Can you elaborate on the second point in the report?',
    agent: 'deep-research-pro-preview-12-2025',
    previous_interaction_id: 'COMPLETED_INTERACTION_ID'
});
console.log(interaction.outputs[-1].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Can you elaborate on the second point in the report?",
    "agent": "deep-research-pro-preview-12-2025",
    "previous_interaction_id": "COMPLETED_INTERACTION_ID"
}'

Quand utiliser l'agent Gemini Deep Research ?

Deep Research est un agent, et pas seulement un modèle. Elle est particulièrement adaptée aux charges de travail qui nécessitent une approche "analyst-in-a-box" plutôt qu'un chat à faible latence.

Fonctionnalité Modèles Gemini standards Agent Gemini Deep Research
Latence Secondes Minutes (asynchrone/en arrière-plan)
Procédure Générer > Sortie Planifier > Rechercher > Lire > Itérer > Sortie
Résultat Texte conversationnel, code, résumés courts Rapports détaillés, analyses approfondies, tableaux comparatifs
Recommandée pour Chatbots, extraction, écriture créative Étude de marché, due diligence, revues de littérature, analyse de la concurrence

Disponibilité et prix

  • Disponibilité : accessible à l'aide de l'API Interactions dans Google AI Studio et l'API Gemini.
  • Tarifs : consultez la page des tarifs pour connaître les tarifs spécifiques et obtenir plus d'informations.

Considérations de sécurité

Accorder à un agent l'accès au Web et à vos fichiers privés nécessite d'examiner attentivement les risques pour la sécurité.

  • Injection de code dans le prompt à l'aide de fichiers : l'agent lit le contenu des fichiers que vous fournissez. Assurez-vous que les documents importés (PDF, fichiers texte) proviennent de sources fiables. Un fichier malveillant peut contenir du texte caché conçu pour manipuler la sortie de l'agent.
  • Risques liés au contenu Web : l'agent effectue des recherches sur le Web public. Bien que nous mettions en œuvre des filtres de sécurité robustes, il existe un risque que l'agent rencontre et traite des pages Web malveillantes. Nous vous recommandons de consulter les citations fournies dans la réponse pour vérifier les sources.
  • Exfiltration : soyez prudent lorsque vous demandez à l'agent de résumer des données internes sensibles si vous lui permettez également de naviguer sur le Web.

Bonnes pratiques

  • Demander des inconnues : indiquez à l'agent comment gérer les données manquantes. Par exemple, ajoutez "Si des chiffres spécifiques pour 2025 ne sont pas disponibles, indiquez explicitement qu'il s'agit de projections ou qu'ils ne sont pas disponibles au lieu de les estimer" à votre requête.
  • Fournissez du contexte : ancrez la recherche de l'agent en fournissant des informations générales ou des contraintes directement dans la requête d'entrée.
  • Entrées multimodales : l'agent Deep Research est compatible avec les entrées multimodales. Utilisez cette option avec précaution, car elle augmente les coûts et risque de provoquer un dépassement de la fenêtre de contexte.

Limites

  • État bêta : l'API Interactions est en version bêta publique. Les fonctionnalités et les schémas peuvent changer.
  • Outils personnalisés : vous ne pouvez actuellement pas fournir d'outils d'appel de fonction personnalisés ni de serveurs MCP (Model Context Protocol) distants à l'agent Deep Research.
  • Sorties structurées et approbation du plan : l'agent Deep Research ne prend actuellement pas en charge la planification approuvée par un humain ni les sorties structurées.
  • Durée de recherche maximale : l'agent Deep Research dispose d'une durée de recherche maximale de 60 minutes. La plupart des tâches devraient être effectuées en moins de 20 minutes.
  • Exigence du store : l'exécution de l'agent à l'aide de background=True nécessite store=True.
  • Recherche Google : la recherche Google est activée par défaut, et des restrictions spécifiques s'appliquent aux résultats ancrés.
  • Entrées audio : les entrées audio ne sont pas acceptées.

Étape suivante