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. Con la tecnología de 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 manejar 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 en 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 de MCP remotos, conocimiento institucional interno y contexto directo de archivos o carpetas subidos.

• Informes pulidos: Produce informes integrales 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 imagen.

• 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:

Funciones clave

Deep Research incluye las siguientes funciones y capacidades:

• Fundamentación en múltiples fuentes, que incluye lo siguiente:
  • Servidores de MCP remotos
  • Fundamentación con Agent Search
  • Fundamentación con la Búsqueda de Google o Fundamentación web para empresas, que se basan en estrictos estándares de privacidad y filtrado adecuados para cargas de trabajo empresariales
  • Cargas de archivos y carpetas intercaladas (como PDFs y hojas de cálculo), lo que te permite agregar contexto directamente al flujo de trabajo de investigación y obtener citas
• 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 Deep Research 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 Agent en GitHub.

Antes de comenzar

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

2. Verify that billing is enabled for your Cloud de Confiance project.

3. Enable the Agent Platform API, if it is not already enabled.

   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

4. 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 Cloud de Confiance 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 Cloud de Confiance console, go to the IAM page.

      Go to IAM
   2. Select the project.
   3. Click person_add Grant access.

   4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

   5. Click Select a role, then search for the role.
   6. To grant additional roles, click add 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 configurando background como True.

Puedes usar el agente de Deep Research de Gemini con o sin transmisión:

• Sondeo (sin transmisión): Establece background=True (y, de forma opcional, stream=False). La API devuelve un objeto Interaction de inmediato. Puedes usar la propiedad id para sondear la interacción hasta que el estado cambie de in_progress a completed o failed.
• Transmisión: Establece background=True y stream=True para recibir actualizaciones en tiempo real a medida que avanza la investigación. Para obtener más información, consulta Transmisión.

También puedes configurar el agente para que use el nivel diferido, que programa automáticamente trabajos en segundo plano para las horas no pico con una tarifa de descuento del 50%. Para usar el nivel diferido, stream debe establecerse en False durante la creación de la tarea.

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=False,
  service_tier="deferred"
)

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)
      

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": false,
      "service_tier": "deferred"
    }'

La API devuelve un interaction_id de inmediato. Puedes usar este ID para sondear el estado o volver a conectarte a una transmisión.

Transmisión

Deep Research admite la transmisión para recibir actualizaciones en tiempo real sobre el progreso de la investigación, incluidos resúmenes de pensamientos, resultados de texto e imágenes generadas. Cuando uses la transmisión, configura 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.

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

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 de forma explícita las herramientas para restringir o extender las capacidades del agente. Entre las herramientas compatibles, se incluyen las siguientes:

Búsqueda de Google

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:

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
)

Búsqueda web de Google para empresas

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 el resultado 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 Deep Research.

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:

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 seguirá 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 agente o un error interno del sistema finaliza por completo el contexto del agente. Por lo general, estos errores devuelven un código de estado HTTP 500. Entre las causas comunes, se 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, pídele que indique 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 que se proporcionan 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 varios pasos. La facturación incluye el uso del modelo (tokens) y la ejecución de herramientas (búsqueda y fundamentación).

En el caso de los trabajos en segundo plano, puedes usar el nivel diferido para obtener un descuento.

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

Seguimiento de costos

De forma predeterminada, el agente de Deep Research de Gemini aplica automáticamente la etiqueta de usuario is_deep_research a sus operaciones. En Cloud de Confiance by S3NS, 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 de tu modelo (tokens de entrada y salida) como a la ejecución de tu herramienta (uso de búsqueda y 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 Cloud de Confiance .

Para aumentar tu cuota, haz lo siguiente:

1. En la consola de Cloud de Confiance , 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, ingresa el límite solicitado en el campo Valor nuevo. 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 son compatibles 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 multirregional

¿Qué sigue?