Usa el agente de Deep Research de Gemini

El agente de Deep Research de Gemini es un agente de IA administrado diseñado para planificar, ejecutar y sintetizar flujos de trabajo de investigación complejos de varios pasos. Potenciado por Gemini, el agente navega por diversos entornos de información, incluidos la Web pública y los datos empresariales privados, para generar informes integrales con citas que aceleran la toma de decisiones fundamentadas.

En esta página, se explica cómo usar el agente de Deep Research de Gemini, incluidas sus capacidades y limitaciones clave, cómo iniciar una tarea de investigación y cómo controlar los tiempos de espera y el manejo de errores.

Cuándo utilizar Deep Research

Deep Research es un agente, no solo un modelo. Es más adecuado para cargas de trabajo que permiten un enfoque de análisis asíncrono en lugar de un chat de baja latencia.

Ten en cuenta las siguientes ventajas de Deep Research cuando planifiques tu proyecto:

  • Proceso iterativo: En lugar de generar respuestas instantáneas como los modelos de chat estándar, Deep Research sigue un flujo de trabajo metódico de varios pasos: Planificar > Búsqueda de múltiples fuentes > Iterar > Salida.

  • Cargas de trabajo avanzadas: Deep Research está diseñado específicamente para manejar tareas complejas, como la diligencia debida, el análisis de mercado y el análisis de la competencia.

  • Fundamentación de datos extensa: El agente de Deep Research de Gemini puede razonar en varias fuentes de datos de forma simultánea. Esto incluye servidores MCP remotos, conocimiento institucional interno y contexto directo de archivos o carpetas subidos.

  • Informes pulidos: Produce informes exhaustivos con citas que pueden incluir elementos visuales listos para presentaciones. Estos incluyen gráficos financieros, infografías intercaladas y matrices de posicionamiento en el mercado, que se generan con HTML y un modelo de imágenes.

  • Alta capacidad de dirección: Puedes personalizar en gran medida el resultado final directamente en tu instrucción. Esto incluye establecer un tono específico (por ejemplo, técnico o ejecutivo), definir formatos estrictos o solicitar tablas de datos estructurados.

En la siguiente tabla, se compara el agente de investigación profunda de Gemini con los modelos estándar de Gemini en varias métricas diferentes, incluidas la latencia, los resultados y para qué es mejor cada uno:

Función Modelos de Gemini estándar Agente de Deep Research de Gemini
Latencia Segundos Minutos
Proceso Generar → Salida Plan → Búsqueda de varias fuentes → Iteración → Resultado
Salida Texto y código de estilo conversacional Informes detallados y citados con gráficos e imágenes intercalados
Ideal para Chatbots, extracción de información y resúmenes Análisis de mercado, investigación detallada y análisis de la competencia

Funciones clave

Deep Research incluye las siguientes funciones y capacidades:

  • Fundamentación en múltiples fuentes, que incluye lo siguiente:
  • Resultados de imágenes y gráficos: Genera informes detallados que contienen recursos listos para presentaciones, como infografías intercaladas, gráficos de matriz de posicionamiento en el mercado y gráficos de rendimiento financiero.
  • Citas intercaladas

Cómo usar Deep Research

Puedes acceder al agente de investigación profunda de Gemini con el extremo global (v1beta1) a través del SDK de IA generativa de Google o de solicitudes directas a la API de REST. Para ver un ejemplo de uso, consulta el notebook Introduction to Gemini Deep Research Pro en GitHub.

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
  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 serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  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 serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  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.

Cómo iniciar una tarea de Deep Research

Las tareas de investigación implican búsquedas y lecturas iterativas, y pueden tardar varios minutos en completarse. Debes ejecutar el agente de Deep Research de Gemini de forma asíncrona.

Debes usar la ejecución en segundo plano y el modo de transmisión. Para ello, establece los campos background y stream en True en la configuración de respuesta cuando ejecutes el agente. La API devuelve un objeto Interaction parcial de inmediato. Puedes usar la propiedad id para recuperar una interacción de sondeo. El estado de interacción pasará de in_progress a completed o 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
    }'

La API devuelve un interaction_id de inmediato. Este ID es obligatorio para volver a conectarse a la transmisión.

Transmisión

La Investigación profunda admite la transmisión para recibir actualizaciones en tiempo real sobre el progreso de la investigación, incluidos resúmenes de ideas, resultados de texto e imágenes generadas. Debes configurar background=True y stream=True.

En el siguiente ejemplo, se inicia una tarea de investigación y se procesa la transmisión con reconexión automática. Realiza un seguimiento de interaction_id y last_event_id para que, si se interrumpe la conexión, pueda reanudarse desde donde se detuvo.


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)

Vuelve a conectarte al flujo de interacción

Para recuperar una transmisión interrumpida, envía una solicitud GET con el interaction_id original. La API reproducirá todos los eventos pasados desde el inicio de la sesión antes de continuar con las actualizaciones en tiempo real.

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

Herramientas

Deep Research admite varias herramientas integradas y externas. De forma predeterminada (cuando no se proporciona ningún parámetro de herramientas), el agente tiene acceso a la Búsqueda de Google y al contexto de URL. Puedes especificar explícitamente herramientas para restringir o extender las capacidades del agente. Entre las herramientas compatibles, se incluyen las siguientes:

Herramienta Clave Nota
Búsqueda de Google google_search Buscar en la Web pública Habilitada de forma predeterminada.
Servidores de MCP mcp_server Conectarse a servidores de MCP remotos para acceder a herramientas externas
Búsqueda web de Google para empresas enterprise_web_search Búsqueda web con controles de cumplimiento adicionales.
Agent Search vertex_ai_search Busca los datos de tu sitio web o tus conjuntos de documentos.

El siguiente código habilita la Búsqueda de Google como la única herramienta:


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
)

Servidores de MCP

Proporciona el nombre y la URL del servidor en la configuración de herramientas. También puedes pasar credenciales de autenticación y restringir las herramientas a las que puede llamar el agente.

Consulta la siguiente referencia:

Campo Tipo Obligatorio Descripción
type cadena Debe ser "mcp_server".
name cadena No Es un nombre visible para el servidor de MCP.
url cadena No Es la URL completa del extremo del servidor de MCP.
headers objeto No Pares clave-valor enviados como encabezados HTTP con cada solicitud al servidor (por ejemplo, tokens de autenticación).
allowed_tools array No Restringe las herramientas del servidor a las que puede llamar el agente.

Consulta el siguiente ejemplo:


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 Búsqueda web para empresas permite a las organizaciones fundamentar las respuestas de la IA generativa en datos web seguros, compatibles y actualizados. Permite que los desarrolladores y las empresas conecten modelos de IA a Internet sin comprometer la privacidad de los datos ni el cumplimiento de las reglamentaciones.

Consulta el siguiente ejemplo:


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
)

Entradas multimodales

Deep Research admite entradas multimodales, incluidas imágenes y documentos (PDFs), lo que permite que el agente analice contenido visual y realice investigaciones basadas en la Web contextualizadas por las entradas proporcionadas.

Consulta el siguiente ejemplo:


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)

Comprensión de documentos

Puedes pasar documentos directamente como entrada multimodal. El agente analiza los documentos proporcionados y realiza investigaciones basadas en su contenido.

Consulta el siguiente ejemplo:


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
)

Capacidad de dirección y formato

Puedes guiar la respuesta del agente proporcionando instrucciones de formato específicas en tu instrucción. Esto te permite estructurar los informes en secciones y subsecciones específicas, incluir tablas de datos o ajustar el tono para diferentes públicos, por ejemplo, "técnico", "ejecutivo" o "informal".

Define el resultado de forma explícita en el texto de entrada. Consulta el siguiente ejemplo:


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
)

Referencia de la API

En esta sección, se proporciona información de referencia de la API para usar el agente de Deep Research de Gemini.

Para obtener más información, consulta la API de Interactions.

Método: interactions.create

Nombre completo: projects.locations.interactions.create

Inicia una nueva sesión de Investigación profunda.

Extremo

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

Parámetros del cuerpo de la solicitud

Los parámetros del cuerpo de la solicitud pueden incluir lo siguiente:

Parámetro Tipo Descripción
agent string Obligatorio. Especifica el código de ID del agente (por ejemplo, deep-research-preview-04-2026).
background boolean Obligatorio. Ejecuta la interacción de forma asíncrona. Debe establecerse en true.
stream boolean Obligatorio. Habilita la transmisión. Debe establecerse en true.
input array o string Obligatorio. Es una lista que contiene la entrada del usuario. Solo se admite un objeto.
tools array Anula las herramientas predeterminadas. Admite google_search, external_data_mcp, vertex_search, etcétera.

Tiempos de espera y manejo de errores

Cuando interactúas con un agente, es posible que se agote el tiempo de espera de la conexión o que se produzcan errores del sistema. En esta sección, se explica cómo identificar y resolver los tiempos de espera flexibles y las fallas graves.

Tiempos de espera flexibles

Se produce un tiempo de espera flexible cuando se interrumpe la conexión de la API de Interactions mientras el agente aún procesa una solicitud. El agente continúa ejecutando la solicitud en segundo plano.

Para reanudar la sesión y ver los eventos reproducidos, vuelve a conectarte a la transmisión con tu interaction_id. Consulta Cómo volver a conectarse al flujo de interacción.

Fallas graves

Se produce una falla grave cuando un error del agente o del sistema interno finaliza por completo el contexto del agente. Por lo general, estos errores devuelven un código de estado HTTP 500. Las causas comunes incluyen superar el límite de ejecución de 120 minutos o experimentar una falla del sistema.

Para resolver este error, detén la sesión actual y define mejor tu búsqueda antes de iniciar una nueva sesión.

Prácticas recomendadas

Darle acceso a un agente autónomo a la Web y a tus archivos introduce dinámicas únicas. Ten en cuenta las siguientes prácticas recomendadas cuando implementes tu proyecto:

  • Solicitud de datos desconocidos: Indica explícitamente al agente cómo controlar los datos faltantes. Por ejemplo, indícale que diga si una cifra no está disponible en lugar de estimarla.

  • Evita los riesgos de inyección de instrucciones: Asegúrate de que los archivos subidos provengan de fuentes confiables, ya que los archivos maliciosos podrían contener texto oculto diseñado para manipular el resultado de un agente.

  • Evita la filtración de datos: Ten mucho cuidado cuando le pidas al agente que resuma datos internos sensibles y, al mismo tiempo, le des acceso para navegar por la Web pública.

  • Verifica las citas: Si bien se aplica un filtrado de nivel empresarial, siempre verifica las citas proporcionadas en la respuesta para asegurarte de que las fuentes web sean confiables.

Limitaciones

Ten en cuenta las siguientes limitaciones cuando planifiques tu proyecto:

  • Solo un turno: Solo se admiten las consultas de un solo turno. No se admite el uso del campo previous_interaction_id de la API.

  • Seguridad empresarial: Durante la versión preliminar, no se admiten las claves de encriptación administradas por el cliente (CMEK) ni los Controles del servicio de VPC. Las restricciones de residencia de datos multirregionales están en evaluación.

  • Almacenamiento en caché: El almacenamiento en caché implícito está habilitado de forma predeterminada para este servicio. No se puede desactivar.

  • Retención de datos: Las instrucciones y el resultado generado se almacenan durante siete días para el procesamiento estándar. Cuando se usa la Fundamentación con la Búsqueda de Google, Google almacena las instrucciones, la información contextual y el resultado generado durante tres días para realizar pruebas y depuración. Si usas la fundamentación con la Búsqueda de Google, no puedes desactivar el almacenamiento de esta información. Si necesitas que no se retengan datos, te recomendamos que uses la fundamentación con la Búsqueda web empresarial.

Precios

Deep Research usa las funciones avanzadas de razonamiento de Gemini para realizar tareas de investigación de agentes de varios pasos. La facturación comprende el uso del modelo (tokens) y la ejecución de herramientas (búsqueda y fundamentación).

Para obtener más información, consulta Precios.

Seguimiento de costos

De forma predeterminada, el agente de Gemini Deep Research aplica automáticamente la etiqueta de usuario is_deep_research a sus operaciones. En Google Cloud, las etiquetas son pares clave-valor ligeros que se usan para organizar los recursos y hacer un seguimiento de los costos en toda tu infraestructura.

  • Etiquetado automático: No es necesario que configures manualmente esta etiqueta en tus solicitudes a la API. El agente incluye la etiqueta is_deep_research de forma predeterminada para todas las tareas ejecutadas.

  • Filtrado de facturación: Los informes de facturación de Deep Research se pueden filtrar con la etiqueta de facturación is_deep_research.

  • Seguimiento integral: La etiqueta de facturación is_deep_research se aplica tanto al uso del modelo (tokens de entrada y salida) como a la ejecución de la herramienta (uso de la búsqueda y la fundamentación). Esto te ayuda a agregar y calcular el costo total de tus flujos de trabajo de investigación asíncronos.

Cuota

Para admitir un mayor tráfico, tareas en segundo plano simultáneas o cargas de investigación más pesadas, puedes solicitar un aumento de la cuota para la API de Agent Platform directamente en tu proyecto de Google Cloud .

Para aumentar tu cuota, haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página Cuotas y límites del sistema.

    Ir a Cuotas y límites del sistema

  2. Asegúrate de haber seleccionado el proyecto correcto que ejecuta tus cargas de trabajo de Deep Research.

  3. En el cuadro de búsqueda del filtro, busca Agent Platform API (aiplatform.googleapis.com) para encontrar las cuotas de interacción y agentes pertinentes.

  4. Selecciona el límite de cuota específico que necesitas ajustar.

  5. Haz clic en Editar cuotas.

  6. En el cuadro de diálogo Cambios en la cuota, en el campo Valor nuevo, ingresa el límite solicitado. Proporciona una justificación clara en la descripción de la solicitud. Mencionar tu caso de uso específico de Deep Research, las necesidades de ejecución en segundo plano y los patrones de tráfico esperados puede ayudar a acelerar el proceso de aprobación.

  7. Haz clic en Enviar solicitud.

Cumplimiento y seguridad

En esta sección, se explica cómo se conservan y almacenan en caché tus datos, y se enumeran los controles de seguridad que no se admiten durante la versión preliminar.

Retención de datos

Las instrucciones y el resultado generado se almacenan durante siete (7) días para el procesamiento estándar.

Como se describe en el Artículo 19 “Servicios de IA Generativa: Fundamentación con la Búsqueda de Google” de las Condiciones Específicas del Servicio, Google almacena las instrucciones y la información contextual que los clientes pueden proporcionar, así como el resultado generado, durante tres (3) días para crear resultados fundamentados y sugerencias de búsqueda. Esta información almacenada se puede usar para depurar y probar los sistemas que admiten la fundamentación con la Búsqueda de Google. No hay forma de inhabilitar el almacenamiento de esta información si usas la fundamentación con la Búsqueda de Google. Si necesitas que no se retengan datos, te recomendamos que uses Web Grounding for Enterprise.

Almacenamiento en caché

La almacenamiento en caché implícito está habilitado de forma predeterminada para Deep Research y no se puede desactivar.

Controles de seguridad

Los siguientes controles de seguridad no se admiten durante la versión preliminar:

  • Claves de encriptación administradas por el cliente (CMEK)
  • Controles del servicio de VPC (VPC-SC)
  • Transparencia de acceso (AXT)
  • Residencia de los datos
  • Residencia de datos en múltiples regiones

¿Qué sigue?

Referencia

Obtén información sobre la API de Interactions, que te permite interactuar con un agente.

Instructivo

Comienza a usar este notebook de Python de Deep Research en GitHub.