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. Grâce à Gemini, il explore des ensembles d'informations complexes pour produire des rapports détaillés et cités. De nouvelles fonctionnalités vous permettent de planifier des tâches de manière collaborative avec l'agent, de vous connecter à des outils externes à l'aide de serveurs MCP, d'inclure des visualisations (comme des graphiques) et de fournir des documents directement en entrée.

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éfinissez background=true) pour exécuter l'agent de manière asynchrone et interroger les résultats ou diffuser les mises à jour. 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-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.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-preview-04-2026',
    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-preview-04-2026",
    "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"

Versions compatibles

L'agent Deep Research est disponible en deux versions :

  • Deep Research (deep-research-preview-04-2026) : conçu pour la rapidité et l'efficacité, idéal pour être diffusé en streaming vers une UI client.
  • Deep Research Max (deep-research-max-preview-04-2026) : exhaustivité maximale pour la collecte et la synthèse automatisées de contexte.

Planification collaborative

La planification collaborative vous permet de contrôler l'orientation de la recherche avant que l'agent ne commence son travail. Lorsqu'il est activé, l'agent renvoie une proposition de plan de recherche au lieu de l'exécuter immédiatement. Vous pouvez ensuite examiner, modifier ou approuver le plan grâce à des interactions multitours.

Étape 1 : Demandez un forfait

Définissez collaborative_planning=True dans la première interaction. L'agent renvoie un plan de recherche au lieu d'un rapport complet.

Python

from google import genai

client = genai.Client()

# First interaction: request a research plan
plan_interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Do some research on Google TPUs.",
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": True,
    },
    background=True,
)

# Wait for and retrieve the plan
while (result := client.interactions.get(id=plan_interaction.id)).status != "completed":
    time.sleep(5)
print(result.outputs[-1].text)

JavaScript

const planInteraction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Do some research on Google TPUs.',
    agent_config: {
        type: 'deep-research',
        thinking_summaries: 'auto',
        collaborative_planning: true
    },
    background: true
});

let result;
while ((result = await client.interactions.get(planInteraction.id)).status !== 'completed') {
    await new Promise(r => setTimeout(r, 5000));
}
console.log(result.outputs[result.outputs.length - 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 '{
    "agent": "deep-research-preview-04-2026",
    "input": "Do some research on Google TPUs.",
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": true
    },
    "background": true
}'

Étape 2 : Affiner le plan (facultatif)

Utilisez previous_interaction_id pour poursuivre la conversation et itérer sur le plan. Conservez collaborative_planning=True pour rester en mode planification.

Python

# Second interaction: refine the plan
refined_plan = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": True,
    },
    previous_interaction_id=plan_interaction.id,
    background=True,
)

while (result := client.interactions.get(id=refined_plan.id)).status != "completed":
    time.sleep(5)
print(result.outputs[-1].text)

JavaScript

const refinedPlan = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Focus more on the differences between Google TPUs and competitor hardware, and less on the history.',
    agent_config: {
        type: 'deep-research',
        thinking_summaries: 'auto',
        collaborative_planning: true
    },
    previous_interaction_id: planInteraction.id,
    background: true
});

let result;
while ((result = await client.interactions.get(refinedPlan.id)).status !== 'completed') {
    await new Promise(r => setTimeout(r, 5000));
}
console.log(result.outputs[result.outputs.length - 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 '{
    "agent": "deep-research-preview-04-2026",
    "input": "Focus more on the differences between Google TPUs and competitor hardware, and less on the history.",
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": true
    },
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "background": true
}'

Étape 3 : Approuver et exécuter

Définissez collaborative_planning=False (ou omettez-le) pour approuver le plan et lancer la recherche.

Python

# Third interaction: approve the plan and kick off research
final_report = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Plan looks good!",
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": False,
    },
    previous_interaction_id=refined_plan.id,
    background=True,
)

while (result := client.interactions.get(id=final_report.id)).status != "completed":
    time.sleep(5)
print(result.outputs[-1].text)

JavaScript

const finalReport = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Plan looks good!',
    agent_config: {
        type: 'deep-research',
        thinking_summaries: 'auto',
        collaborative_planning: false
    },
    previous_interaction_id: refinedPlan.id,
    background: true
});

let result;
while ((result = await client.interactions.get(finalReport.id)).status !== 'completed') {
    await new Promise(r => setTimeout(r, 5000));
}
console.log(result.outputs[result.outputs.length - 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 '{
    "agent": "deep-research-preview-04-2026",
    "input": "Plan looks good!",
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto",
        "collaborative_planning": false
    },
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID",
    "background": true
}'

Visualisation

Lorsque visualization est défini sur "auto", l'agent peut générer des graphiques et d'autres éléments visuels pour étayer ses résultats de recherche. Les images générées sont incluses dans les résultats de la réponse et diffusées en streaming sous forme de deltas image. Pour de meilleurs résultats, demandez explicitement des éléments visuels dans votre requête. Par exemple, "Inclure des graphiques montrant les tendances au fil du temps" ou "Générer des graphiques comparant les parts de marché". Si vous définissez visualization sur "auto", la fonctionnalité est activée, mais l'agent ne génère des éléments visuels que lorsque la requête le demande.

Python

import base64
from IPython.display import Image, display

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Analyze global semiconductor market trends. Include graphics showing market share changes.",
    agent_config={
        "type": "deep-research",
        "visualization": "auto",
    },
    background=True,
)

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

while (result := client.interactions.get(id=interaction.id)).status != "completed":
    time.sleep(5)

for output in result.outputs:
    if output.type == "text":
        print(output.text)
    elif output.type == "image" and output.data:
        image_bytes = base64.b64decode(output.data)
        print(f"Received image: {len(image_bytes)} bytes")
        # To display in a Jupyter notebook:
        # from IPython.display import display, Image
        # display(Image(data=image_bytes))

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Analyze global semiconductor market trends. Include graphics showing market share changes.',
    agent_config: {
        type: 'deep-research',
        visualization: 'auto'
    },
    background: true
});

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

let result;
while ((result = await client.interactions.get(interaction.id)).status !== 'completed') {
    await new Promise(r => setTimeout(r, 5000));
}

for (const output of result.outputs) {
    if (output.type === 'text') {
        console.log(output.text);
    } else if (output.type === 'image' && output.data) {
        console.log(`[Image Output: ${output.data.substring(0, 20)}...]`);
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "deep-research-preview-04-2026",
    "input": "Analyze global semiconductor market trends. Include graphics showing market share changes.",
    "agent_config": {
        "type": "deep-research",
        "visualization": "auto"
    },
    "background": true
}'

Outils compatibles

Deep Research est compatible avec plusieurs outils intégrés et externes. Par défaut (lorsqu'aucun paramètre tools n'est fourni), l'agent a accès à la recherche Google, au contexte d'URL et à l'exécution de code. Vous pouvez spécifier explicitement des outils pour limiter ou étendre les capacités de l'agent.

Outil Valeur du type Description
Recherche Google google_search Rechercher sur le Web public Cette option est activée par défaut.
Contexte de l'URL url_context lire et résumer le contenu d'une page Web ; Cette option est activée par défaut.
Exécution de code code_execution exécuter du code pour effectuer des calculs et analyser des données ; Cette option est activée par défaut.
Serveur MCP mcp_server Se connecter à des serveurs MCP distants pour accéder à des outils externes
Recherche de fichiers file_search Recherchez dans les corpus de documents que vous avez importés.

Activez explicitement la recherche Google comme seul outil :

Python

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="What are the latest developments in quantum computing?",
    tools=[{"type": "google_search"}],
    background=True,
)

JavaScript

const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'What are the latest developments in quantum computing?',
    tools: [{ type: 'google_search' }],
    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 '{
    "agent": "deep-research-preview-04-2026",
    "input": "What are the latest developments in quantum computing?",
    "tools": [{"type": "google_search"}],
    "background": true
}'

Contexte de l'URL

Donnez à l'agent la possibilité de lire et de résumer des pages Web spécifiques :

Python

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Summarize the content of https://www.wikipedia.org/.",
    tools=[{"type": "url_context"}],
    background=True,
)

JavaScript

const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Summarize the content of https://www.wikipedia.org/.',
    tools: [{ type: 'url_context' }],
    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 '{
    "agent": "deep-research-preview-04-2026",
    "input": "Summarize the content of https://www.wikipedia.org/.",
    "tools": [{"type": "url_context"}],
    "background": true
}'

Exécution de code

Autorisez l'agent à exécuter du code pour les calculs et l'analyse des données :

Python

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Calculate the 50th Fibonacci number.",
    tools=[{"type": "code_execution"}],
    background=True,
)

JavaScript

const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Calculate the 50th Fibonacci number.',
    tools: [{ type: 'code_execution' }],
    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 '{
    "agent": "deep-research-preview-04-2026",
    "input": "Calculate the 50th Fibonacci number.",
    "tools": [{"type": "code_execution"}],
    "background": true
}'

Serveurs MCP

Indiquez les name et url du serveur dans la configuration des outils. Vous pouvez également transmettre des identifiants d'authentification et limiter les outils que l'agent peut appeler.

Champ Type Obligatoire Description
type string Oui doit être "mcp_server"
name string Non Nom à afficher du serveur MCP.
url string Non URL complète du point de terminaison du serveur MCP.
headers object Non Paires clé-valeur envoyées en tant qu'en-têtes HTTP avec chaque requête au serveur (par exemple, les jetons d'authentification).
allowed_tools array Non Limitez les outils du serveur que l'agent peut appeler.

Utilisation de base

Python

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Check the status of my last server deployment.",
    tools=[
        {
            "type": "mcp_server",
            "name": "Deployment Tracker",
            "url": "https://mcp.example.com/mcp",
            "headers": {"Authorization": "Bearer my-token"},
        }
    ],
    background=True,
)

JavaScript

const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Check the status of my last server deployment.',
    tools: [
        {
            type: 'mcp_server',
            name: 'Deployment Tracker',
            url: 'https://mcp.example.com/mcp',
            headers: { Authorization: 'Bearer my-token' }
        }
    ],
    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 '{
    "agent": "deep-research-preview-04-2026",
    "input": "Check the status of my last server deployment.",
    "tools": [
        {
            "type": "mcp_server",
            "name": "Deployment Tracker",
            "url": "https://mcp.example.com/mcp",
            "headers": {"Authorization": "Bearer my-token"}
        }
    ],
    "background": true
}'

Donnez à l'agent l'accès à vos propres données à l'aide de l'outil Recherche de fichiers.

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-preview-04-2026",
    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-preview-04-2026',
    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-preview-04-2026",
    "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 à différentes audiences (par exemple, "technique", "exécutif" ou "informel").

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-preview-04-2026",
    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-preview-04-2026',
    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-preview-04-2026",
    "background": true
}'

Entrées multimodales

Deep Research accepte les entrées multimodales, y compris les images et les documents (PDF), ce qui permet à l'agent d'analyser le contenu visuel et d'effectuer des recherches sur le Web contextualisées par les entrées fournies.

Python

import time
from google import genai

client = genai.Client()

prompt = """Analyze the interspecies dynamics and behavioral risks present
in the provided image of the African watering hole. Specifically, investigate
the symbiotic relationship between the avian species and the pachyderms
shown, and conduct a risk assessment for the reticulated giraffes based on
their drinking posture relative to the specific predator visible in the
foreground."""

interaction = client.interactions.create(
    input=[
        {"type": "text", "text": prompt},
        {
            "type": "image",
            "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"
        }
    ],
    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.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 prompt = `Analyze the interspecies dynamics and behavioral risks present
in the provided image of the African watering hole. Specifically, investigate
the symbiotic relationship between the avian species and the pachyderms
shown, and conduct a risk assessment for the reticulated giraffes based on
their drinking posture relative to the specific predator visible in the
foreground.`;

const interaction = await client.interactions.create({
    input: [
        { type: 'text', text: prompt },
        {
            type: 'image',
            uri: 'https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg'
        }
    ],
    agent: 'deep-research-preview-04-2026',
    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 with image input
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": [
        {"type": "text", "text": "Analyze the interspecies dynamics and behavioral risks present in the provided image of the African watering hole. Specifically, investigate the symbiotic relationship between the avian species and the pachyderms shown, and conduct a risk assessment for the reticulated giraffes based on their drinking posture relative to the specific predator visible in the foreground."},
        {"type": "image", "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"}
    ],
    "agent": "deep-research-preview-04-2026",
    "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"

Compréhension des documents

Transmettez des documents directement en tant qu'entrée multimodale. L'agent analyse les documents fournis et effectue des recherches basées sur leur contenu.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input=[
        {"type": "text", "text": "What is this document about?"},
        {
            "type": "document",
            "uri": "https://arxiv.org/pdf/1706.03762",
            "mime_type": "application/pdf",
        },
    ],
    background=True,
)

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: [
        { type: 'text', text: 'What is this document about?' },
        {
            type: 'document',
            uri: 'https://arxiv.org/pdf/1706.03762',
            mime_type: 'application/pdf'
        }
    ],
    background: true
});

REST

# 1. Start the research task with document input
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "deep-research-preview-04-2026",
    "input": [
        {"type": "text", "text": "What is this document about?"},
        {"type": "document", "uri": "https://arxiv.org/pdf/1706.03762", "mime_type": "application/pdf"}
    ],
    "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, y compris des résumés de réflexion, des résultats textuels et des images générées. Vous devez définir stream=True et background=True.

Pour recevoir des étapes de raisonnement intermédiaires (réflexions) et des mises à jour sur la progression, vous devez activer les résumés de réflexion en définissant thinking_summaries sur "auto" dans agent_config. Sans cela, le flux ne peut fournir que les résultats finaux.

Types d'événements de flux

Type d'événement Type de delta Description
content.delta thought_summary Étape de raisonnement intermédiaire de l'agent.
content.delta text Partie du texte de sortie final.
content.delta image Image générée (encodée en base64).

L'exemple suivant démarre une tâche de recherche et traite le flux avec une reconnexion automatique. Il suit les interaction_id et last_event_id afin de pouvoir reprendre là où il s'est arrêté en cas de perte de connexion (par exemple, après le délai d'expiration de 600 secondes).

Python

from google import genai

client = genai.Client()

interaction_id = None
last_event_id = None
is_complete = False

def process_stream(stream):
    global interaction_id, last_event_id, is_complete
    for chunk in stream:
        if chunk.event_type == "interaction.start":
            interaction_id = chunk.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 in ("interaction.complete", "error"):
            is_complete = True

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

# Reconnect if the connection drops
while not is_complete and interaction_id:
    status = client.interactions.get(interaction_id)
    if status.status != "in_progress":
        break
    stream = client.interactions.get(
        id=interaction_id, stream=True, last_event_id=last_event_id,
    )
    process_stream(stream)

JavaScript

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

const client = new GoogleGenAI({});

let interactionId;
let lastEventId;
let isComplete = false;

async function processStream(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 (['interaction.complete', 'error'].includes(chunk.event_type)) {
            isComplete = true;
        }
    }
}

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

// Reconnect if the connection drops
while (!isComplete && interactionId) {
    const status = await client.interactions.get(interactionId);
    if (status.status !== 'in_progress') break;
    const resumeStream = await client.interactions.get(interactionId, {
        stream: true, last_event_id: lastEventId,
    });
    await processStream(resumeStream);
}

REST

# 1. Start the stream (save the INTERACTION_ID from the interaction.start event
#    and the last "event_id" you receive)
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-preview-04-2026",
    "background": true,
    "stream": true,
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto"
    }
}'

# 2. If the connection drops, reconnect with your saved IDs
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID?stream=true&last_event_id=LAST_EVENT_ID" \
-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.1-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?',
    model: 'gemini-3.1-pro-preview',
    previous_interaction_id: 'COMPLETED_INTERACTION_ID'
});
console.log(interaction.outputs[interaction.outputs.length - 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?",
    "model": "gemini-3.1-pro-preview",
    "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 longues, tableaux comparatifs
Recommandé pour Chatbots, extraction, écriture créative Étude de marché, diligence raisonnable, revues de littérature, analyse de la concurrence

Configurer l'agent

Deep Research utilise le paramètre agent_config pour contrôler le comportement. Transmettez-le sous forme de dictionnaire avec les champs suivants :

Champ Type Par défaut Description
type string Obligatoire doit être "deep-research"
thinking_summaries string "none" Définissez la valeur sur "auto" pour recevoir des étapes de raisonnement intermédiaires pendant le streaming. Définissez la valeur sur "none" pour désactiver la fonctionnalité.
visualization string "auto" Définissez la valeur sur "auto" pour activer les graphiques et les images générés par l'agent. Définissez la valeur sur "off" pour désactiver la fonctionnalité.
collaborative_planning boolean false Définissez la valeur sur true pour activer l'examen du plan en plusieurs étapes avant le début de la recherche.

Python

agent_config = {
    "type": "deep-research",
    "thinking_summaries": "auto",
    "visualization": "auto",
    "collaborative_planning": False,
}

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Research the competitive landscape of cloud GPUs.",
    agent_config=agent_config,
    background=True,
)

JavaScript

const interaction = await client.interactions.create({
    agent: 'deep-research-preview-04-2026',
    input: 'Research the competitive landscape of cloud GPUs.',
    agent_config: {
        type: 'deep-research',
        thinking_summaries: 'auto',
        visualization: 'auto',
        collaborative_planning: false,
    },
    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 cloud GPUs.",
    "agent": "deep-research-preview-04-2026",
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto",
        "visualization": "auto",
        "collaborative_planning": false
    },
    "background": true
}'

Disponibilité et prix

Vous pouvez accéder à l'agent Gemini Deep Research à l'aide de l'API Interactions dans Google AI Studio et l'API Gemini.

La tarification suit un modèle de paiement à l'utilisation basé sur les modèles Gemini sous-jacents et les outils spécifiques utilisés par l'agent. Contrairement aux requêtes de chat standards, où une requête conduit à une seule sortie, une tâche Deep Research est un workflow agentique. Une seule requête déclenche une boucle autonome de planification, de recherche, de lecture et de raisonnement.

Coûts estimés

Les coûts varient en fonction de la profondeur de la recherche requise. L'agent détermine de manière autonome la quantité de lecture et de recherche nécessaire pour répondre à votre requête.

  • Deep Research (deep-research-preview-04-2026) : pour une requête typique nécessitant une analyse modérée, l'agent peut utiliser environ 80 requêtes de recherche, environ 250 000 jetons d'entrée (environ 50 à 70 % mis en cache) et environ 60 000 jetons de sortie.
    • Total estimé : entre 1 et 3 $ par tâche
  • Deep Research Max (deep-research-max-preview-04-2026) : pour une analyse approfondie du paysage concurrentiel ou une due diligence complète, l'agent peut utiliser jusqu'à environ 160 requêtes de recherche, environ 900 000 jetons d'entrée (environ 50 à 70 % mis en cache) et environ 80 000 jetons de sortie.
    • Total estimé : entre 3 et 7 $ par tâche

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 place 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 informations 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.
  • Utilisez la planification collaborative : pour les requêtes complexes, activez la planification collaborative afin d'examiner et d'affiner le plan de recherche avant son exécution.
  • Entrées multimodales : l'agent Deep Research accepte les entrées multimodales. Utilisez cette option avec précaution, car elle augmente les coûts et le risque de 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 pas fournir d'outils d'appel de fonction personnalisés pour le moment, mais vous pouvez utiliser des serveurs MCP (Model Context Protocol) distants avec l'agent Deep Research.
  • Sortie structurée : l'agent Deep Research n'est actuellement pas compatible avec 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 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.

Étape suivante