Utiliser l'agent Gemini Deep Research

L'agent Gemini Deep Research est un agent d'IA géré conçu pour planifier, exécuter et synthétiser des workflows de recherche complexes en plusieurs étapes. Grâce à Gemini, l'agent explore différents types d'informations, y compris le Web public et les données d'entreprise privées, pour générer des rapports complets et cités qui accélèrent la prise de décision éclairée.

Cette page explique comment utiliser l'agent Gemini Deep Research, y compris ses principales capacités et limites, comment lancer une tâche de recherche et comment gérer les délais d'attente et la gestion des exceptions.

Quand utiliser Deep Research

Deep Research est un agent, et pas seulement un modèle. Elle est particulièrement adaptée aux charges de travail qui autorisent une approche d'analyse asynchrone plutôt qu'un chat à faible latence.

Tenez compte des points forts suivants de Deep Research lorsque vous planifiez votre projet :

  • Processus itératif : au lieu de générer des réponses instantanées comme les modèles de chat standards, Deep Research suit un workflow méthodique en plusieurs étapes : planifier > recherche multisource > itérer > résultat.

  • Charges de travail avancées : Deep Research est spécifiquement conçu pour gérer des tâches complexes telles que la diligence raisonnable, les analyses de marché et les analyses de la concurrence.

  • Ancrage étendu des données : l'agent Gemini Deep Research peut raisonner sur différentes sources de données simultanément. Cela inclut les serveurs MCP distants, les connaissances institutionnelles internes et le contexte direct des fichiers ou dossiers importés.

  • Rapports soignés : il génère des rapports complets et cités qui peuvent inclure des éléments visuels prêts à être présentés. Il s'agit, par exemple, de graphiques financiers, d'infographies intégrées et de matrices de positionnement sur le marché, qui sont générés à l'aide de HTML et d'un modèle d'image.

  • Grande capacité de pilotage : vous pouvez personnaliser fortement le résultat final directement dans votre requête. Cela inclut la définition d'un ton spécifique (par exemple, technique ou exécutif), la définition de formats stricts ou la demande de tableaux de données structurées.

Le tableau suivant compare l'agent Gemini Recherche approfondie aux modèles Gemini standards selon plusieurs métriques différentes, y compris la latence, les résultats et les cas d'utilisation les plus adaptés :

Fonctionnalité Modèles Gemini standards Agent Gemini Deep Research
Latence Secondes Minutes
Processus Générer → Sortie Plan → Recherche multisource → Itérer → Sortie
Sortie Texte et code de style conversationnel Rapports détaillés et cités avec des graphiques et des images intégrés
Application idéale Chatbots, extraction d'informations, synthèse Étude de marché, recherche approfondie, analyse de la concurrence

Capacités clés

Deep Research propose les fonctionnalités et les possibilités suivantes :

  • Ancrage sur plusieurs sources, y compris :
  • Résultats sous forme d'images et de graphiques : générez des rapports détaillés contenant des éléments prêts à l'emploi, tels que des infographies intégrées, des graphiques de matrice de positionnement sur le marché et des graphiques de performances financières.
  • Citations intégrées

Utiliser Deep Research

Vous pouvez accéder à l'agent Gemini Deep Research à l'aide du point de terminaison mondial (v1beta1) en utilisant le SDK Google Gen AI ou des requêtes directes de l'API REST. Pour obtenir un exemple d'utilisation, consultez le notebook Introduction to Gemini Deep Research Pro (Présentation de Gemini Deep Research Pro) sur GitHub.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.
  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. Make sure that you have the following role or roles on the project: roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.
    4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.
  6. 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

  7. Verify that billing is enabled for your Google Cloud project.

  8. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  9. Make sure that you have the following role or roles on the project: roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.
    4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

Démarrer une tâche Deep Research

Les tâches de recherche impliquent des recherches et des lectures itératives, et peuvent prendre plusieurs minutes. Vous devez exécuter l'agent Gemini Deep Research de manière asynchrone.

Vous devez utiliser l'exécution en arrière-plan et le mode streaming. Pour ce faire, définissez les champs background et stream sur True dans la configuration de la réponse lorsque vous exécutez l'agent. L'API renvoie immédiatement un objet Interaction partiel. Vous pouvez utiliser la propriété id pour récupérer une interaction pour l'interrogation. L'état de l'interaction passera de in_progress à completed ou failed.

Python


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,
  stream=True
)

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

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

REST

PROJECT_ID=PROJECT_ID;
curl --max-time 3600 --keepalive-time 10 -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
    -d '{
      "input": "Research the history of Google TPUs.",
      "agent": "deep-research-preview-04-2026",
      "background": true,
      "stream": true
    }'

L'API renvoie immédiatement un interaction_id. Cet ID est nécessaire pour se reconnecter au flux.

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 background=True et stream=True.

L'exemple suivant lance une tâche de recherche et traite le flux avec une reconnexion automatique. Il suit les interaction_id et last_event_id afin que, si la connexion est interrompue, il puisse reprendre là où il s'est arrêté.


from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

interaction_id = None
last_event_id = None
is_complete = False

def process_stream(stream):
  global interaction_id, last_event_id, is_complete
  for event in stream:
    if event.event_type == "interaction.created":
      interaction_id = event.interaction.id
    if event.event_id:
      last_event_id = event.event_id
    if event.event_type == "step.delta":
      if event.delta.type == "text":
        print(event.delta.text, end="", flush=True)
      elif event.delta.type == "thought":
        print(f"Thought: {event.delta.text}", flush=True)
    elif event.event_type in ("interaction.completed", "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)

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)

Se reconnecter au flux d'interactions

Pour récupérer un flux interrompu, envoyez une requête GET à l'aide du interaction_id d'origine. L'API rejoue tous les événements passés depuis le début de la session avant de poursuivre avec les mises à jour en temps réel.

Python


response = client.interactions.get(
  id = 'INTERACTION_ID',
  stream=True
)
for chunk in response:
  print(chunk)
      

REST

PROJECT_ID=PROJECT_ID;
INTERACTION_ID=INTERACTION_ID

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions/${INTERACTION_ID}"

Outils

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

Outil Clé Remarque
Recherche Google google_search Rechercher sur le Web public Cette option est activée par défaut.
Serveurs MCP mcp_server Connectez-vous à des serveurs MCP distants pour accéder à des outils externes.
Recherche sur le Web pour les entreprises enterprise_web_search Recherche sur le Web avec des contrôles de conformité supplémentaires.
Agent Search vertex_ai_search Recherchez dans les données de votre site Web ou dans vos ensembles de documents.

Le code suivant permet d'activer la recherche Google comme seul outil :


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,
  stream=True
)

Serveurs MCP

Indiquez le nom et l'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.

Consultez la référence suivante :

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 objet Non Paires clé-valeur envoyées en tant qu'en-têtes HTTP avec chaque requête au serveur (par exemple, jetons d'authentification).
allowed_tools tableau Non Limitez les outils du serveur que l'agent peut appeler.

Consultez l'exemple ci-dessous :


interaction = client.interactions.create(
  agent="deep-research-preview-04-2026",
  input="How to deploy an app to Cloud Run on Google Cloud?",
  tools=[
    {
      "type": "mcp_server",
      "name": "Google Cloud Developer Knowledge",
      "url": "https://developerknowledge.googleapis.com/mcp",
      "headers": {"Authorization": "Bearer token"},
    }
  ],
  background=True,
  stream=True
)

La recherche sur le Web Enterprise permet aux organisations d'ancrer les réponses de l'IA générative dans des données Web sécurisées, conformes et à jour. Il permet aux développeurs et aux entreprises de connecter des modèles d'IA à Internet sans compromettre la confidentialité des données ni la conformité réglementaire.

Consultez l'exemple ci-dessous :


interaction = client.interactions.create(
  agent="deep-research-preview-04-2026",
  input="Research on the latest trend on AI",
  tools=[
    {
      "type": "google_search",
      "search_type": ["enterprise_web_search"],
    }
  ],
  background=True,
  stream=True
)

Entrées multimodales

Deep Research est compatible avec 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 en fonction des entrées fournies.

Consultez l'exemple ci-dessous :


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,
  stream=True
)

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

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

Compréhension des documents

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

Consultez l'exemple ci-dessous :


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,
  stream=True
)

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 résultat dans votre texte d'entrée. Consultez l'exemple ci-dessous :


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,
    stream=True
)

Documentation de référence de l'API

Cette section fournit des informations de référence sur l'utilisation de l'agent Gemini Deep Research.

Pour en savoir plus, consultez API Interactions.

Méthode : interactions.create

Nom complet : projects.locations.interactions.create

Lance une nouvelle session de recherche approfondie.

Point de terminaison

post https://aiplatform.googleapis.com/v1beta1/{parent}/interactions

Paramètres du corps de la requête

Les paramètres du corps de la requête peuvent inclure les éléments suivants :

Paramètre Type Description
agent string Obligatoire. Spécifie le code d'ID de l'agent (par exemple, deep-research-preview-04-2026).
background boolean Obligatoire. Exécute l'interaction de manière asynchrone. Doit être défini sur true.
stream boolean Obligatoire. Active le streaming. Doit être défini sur true.
input array ou string Obligatoire. Liste contenant les entrées utilisateur. Un seul objet est accepté.
tools array Remplace les outils par défaut. Compatible avec google_search, external_data_mcp, vertex_search, etc.

Délai d'attente et gestion des exceptions

Lorsque vous interagissez avec un agent, vous pouvez rencontrer des délais de connexion dépassés ou des erreurs système. Cette section explique comment identifier et résoudre les problèmes de délai avant expiration et d'échec définitif.

Délai d'expiration souple

Un délai avant expiration non critique se produit lorsque la connexion à l'API Interactions est interrompue alors que l'agent traite toujours une requête. L'agent continue d'exécuter la requête en arrière-plan.

Pour reprendre la session et afficher les événements rejoués, reconnectez-vous au flux à l'aide de votre interaction_id. Consultez Se reconnecter au flux d'interactions.

Pannes graves

Une erreur fatale se produit lorsqu'un agent ou une erreur système interne met fin complètement au contexte de l'agent. Ces erreurs renvoient généralement un code d'état HTTP 500. Les causes courantes incluent le dépassement de la limite d'exécution de 120 minutes ou une défaillance du système.

Pour résoudre ce problème, arrêtez la session en cours et affinez votre requête avant de démarrer une nouvelle session.

Bonnes pratiques

Donner accès au Web et à vos fichiers à un agent autonome introduit une dynamique unique. Tenez compte des bonnes pratiques suivantes lorsque vous implémentez votre projet :

  • Demander à l'agent de répondre aux inconnues : indiquez explicitement à l'agent comment gérer les données manquantes. Par exemple, demandez-lui de préciser si un chiffre n'est pas disponible au lieu de l'estimer.

  • Évitez les risques d'injection de prompt : assurez-vous que les fichiers importés proviennent de sources fiables, car les fichiers malveillants peuvent contenir du texte caché conçu pour manipuler la sortie d'un agent.

  • Évitez l'exfiltration de données : soyez extrêmement prudent lorsque vous demandez à l'agent de résumer des données internes sensibles tout en lui donnant accès à la navigation sur le Web public.

  • Vérifiez les citations : même si un filtrage de niveau entreprise est appliqué, vérifiez toujours les citations fournies dans la réponse pour vous assurer que les sources Web sont fiables.

Limites

Tenez compte des limites suivantes lorsque vous planifiez votre projet :

  • Un seul tour : seules les requêtes à un seul tour sont acceptées. L'utilisation du champ previous_interaction_id de l'API n'est pas acceptée.

  • Sécurité pour les entreprises : pendant la version Preview, les clés de chiffrement gérées par le client (CMEK) et VPC Service Controls ne sont pas compatibles. Les contraintes de résidence des données multirégionales sont en cours d'évaluation.

  • Mise en cache : la mise en cache implicite est activée par défaut pour ce service. Il ne peut pas être désactivé.

  • Conservation des données : les requêtes et les résultats générés sont stockés pendant sept jours pour le traitement standard. Lorsque vous utilisez l'ancrage avec la recherche Google, Google stocke les requêtes, les informations contextuelles et les résultats générés pendant trois jours à des fins de débogage et de test. Si vous utilisez l'ancrage avec la recherche Google, vous ne pouvez pas désactiver le stockage de ces informations. Si vous avez besoin d'une durée de conservation des données nulle, nous vous recommandons d'utiliser l'ancrage avec la recherche sur le Web Enterprise.

Tarifs

Deep Research utilise les fonctionnalités de raisonnement avancées de Gemini pour effectuer des tâches de recherche agentives en plusieurs étapes. La facturation comprend l'utilisation du modèle (jetons) et l'exécution des outils (recherche et ancrage).

Pour en savoir plus, reportez-vous à la section Tarification.

Suivi des coûts

Par défaut, l'agent Gemini Deep Research applique automatiquement le libellé utilisateur is_deep_research à ses opérations. Dans Google Cloud, les libellés sont des paires clé/valeur légères utilisées pour organiser les ressources et suivre les coûts dans votre infrastructure.

  • Libellé automatique : vous n'avez pas besoin de configurer manuellement ce libellé dans vos requêtes d'API. L'agent inclut le libellé is_deep_research par défaut pour toutes les tâches exécutées.

  • Filtrer les rapports sur la facturation : vous pouvez filtrer les rapports Deep Research sur la facturation à l'aide du libellé de facturation is_deep_research.

  • Suivi complet : le libellé de facturation is_deep_research s'applique à l'utilisation de votre modèle (jetons d'entrée et de sortie) et à l'exécution de vos outils (utilisation de la recherche et de l'ancrage). Cela vous aide à agréger et à calculer le coût total de vos workflows de recherche asynchrones.

Quota

Pour gérer un trafic plus élevé, des tâches en arrière-plan simultanées ou des charges de recherche plus importantes, vous pouvez demander une augmentation du quota pour l'API Agent Platform directement dans votre projet Google Cloud .

Pour augmenter votre quota, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Quotas et limites du système.

    Accéder à la page "Quotas et limites du système"

  2. Assurez-vous d'avoir sélectionné le bon projet qui exécute vos charges de travail de recherche approfondie.

  3. Dans le champ de recherche du filtre, recherchez Agent Platform API (aiplatform.googleapis.com) pour trouver les quotas d'agents et d'interactions qui vous concernent.

  4. Sélectionnez la limite de quota spécifique que vous devez ajuster.

  5. Cliquez sur Modifier les quotas.

  6. Dans la boîte de dialogue Modifications de quota, saisissez la limite souhaitée dans le champ Nouvelle valeur. Fournissez une justification claire dans la description de la demande. Mentionner votre cas d'utilisation Deep Research spécifique, vos besoins en matière d'exécution en arrière-plan et les tendances de trafic attendues peut accélérer le processus d'approbation.

  7. Cliquez sur Envoyer la requête.

Conformité et sécurité

Cette section explique comment vos données sont conservées et mises en cache, et liste les contrôles de sécurité qui ne sont pas compatibles pendant l'aperçu.

Conservation des données

Les requêtes et les résultats générés sont stockés pendant sept (7) jours pour le traitement standard.

Comme indiqué dans la section 19 "Services d'IA générative : ancrage avec la recherche Google" des Conditions d'utilisation spécifiques aux services, Google stocke les requêtes et les informations contextuelles que les clients peuvent fournir, ainsi que les résultats générés pendant trois (3) jours afin de créer des résultats ancrés et des suggestions de recherche. Ces informations stockées peuvent être utilisées pour le débogage et le test des systèmes qui prennent en charge l'ancrage avec la recherche Google. Il n'est pas possible de désactiver le stockage de ces informations si vous utilisez l'ancrage dans la recherche Google. Si vous avez besoin d'une conservation des données nulle, nous vous recommandons d'utiliser Web Grounding for Enterprise.

Mise en cache

La mise en cache implicite est activée par défaut pour la Recherche approfondie et ne peut pas être désactivée.

Contrôles de sécurité

Les contrôles de sécurité suivants ne sont pas disponibles dans la version bêta :

  • Clés de chiffrement gérées par le client (CMEK)
  • VPC-Service Controls (VPC-SC)
  • Access Transparency (AXT)
  • Résidence des données
  • Résidence des données multirégionale

Étapes suivantes

Référence

Découvrez l'API Interactions, qui vous permet d'interagir avec un agent.

Tutoriel

Commencez avec ce notebook Python Deep Research sur GitHub.