Usar o agente do Deep Research do Gemini

O agente Deep Research do Gemini é um agente de IA gerenciado projetado para planejar, executar e sintetizar fluxos de trabalho de pesquisa complexos e de várias etapas. Com tecnologia do Gemini, o agente navega por diversos cenários de informações, incluindo a Web pública e dados corporativos privados, para gerar relatórios abrangentes e citados que aceleram a tomada de decisões embasadas.

Esta página explica como usar o agente Deep Research do Gemini, incluindo os principais recursos e limitações, como iniciar uma tarefa de pesquisa e como lidar com tempos limite e tratamento de erros.

Quando usar o Deep Research

O Deep Research é um agente, não apenas um modelo. Ele é mais adequado para cargas de trabalho que permitem uma abordagem de análise assíncrona em vez de chat de baixa latência.

Considere os seguintes pontos fortes da Deep Research ao planejar seu projeto:

  • Processo iterativo: em vez de gerar respostas instantâneas como os modelos de chat padrão, o Deep Research segue um fluxo de trabalho metódico e de várias etapas: Planejar > Pesquisa em várias fontes > Iterar > Saída.

  • Cargas de trabalho avançadas: a Deep Research foi projetada especificamente para lidar com tarefas complexas, como auditoria, análise de mercado e análise da concorrência.

  • Fundamentação de dados abrangente: o agente Deep Research do Gemini pode analisar várias fontes de dados simultaneamente. Isso inclui servidores MCP remotos, conhecimento institucional interno e contexto direto de arquivos ou pastas enviados.

  • Relatórios refinados: ele produz relatórios abrangentes e citados que podem apresentar recursos visuais prontos para apresentação. Isso inclui gráficos financeiros, infográficos inline e matrizes de posicionamento de mercado, que são gerados usando HTML e um modelo de imagem.

  • Alta capacidade de direcionamento: você pode personalizar muito a saída final diretamente no comando. Isso inclui definir um tom específico (por exemplo, técnico ou executivo), definir formatos estritos ou solicitar tabelas de dados estruturados.

A tabela a seguir compara o Gemini Deep Research Agent com os modelos padrão do Gemini em várias métricas diferentes, incluindo latência, saídas e o que cada um faz de melhor:

Recurso Modelos padrão do Gemini Agente Deep Research do Gemini
Latência Segundos Minutos
Processo Gerar → Saída Planejar → Pesquisa em várias fontes → Iterar → Saída
Saída Texto e código em estilo de conversa Relatórios detalhados e citados com gráficos e imagens inline
Ideal para Chatbots, extração de informações, resumo Análise de mercado, pesquisa detalhada e análise da concorrência

Principais recursos

O Deep Research vem com os seguintes recursos e capacidades:

  • Fundamentação em várias fontes, incluindo:
  • Saídas de imagens e gráficos: gere relatórios detalhados com recursos prontos para apresentação, como infográficos inline, gráficos de matriz de posicionamento no mercado e gráficos de desempenho financeiro.
  • Citações incorporadas

Como usar o Deep Research

É possível acessar o agente Deep Research do Gemini usando o endpoint global (v1beta1) com o SDK de IA generativa do Google ou solicitações diretas da API REST. Para um exemplo de uso, consulte o notebook de introdução ao agente de Deep Research do Gemini no GitHub.

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.
  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, 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

  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, 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

  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.

Iniciar uma tarefa do Deep Research

As atividades de pesquisa envolvem busca e leitura iterativas e podem levar vários minutos para serem concluídas. Você precisa executar o agente Deep Research do Gemini de forma assíncrona definindo background como True.

Você pode usar o agente do Deep Research do Gemini com ou sem streaming:

  • Pesquisa (sem streaming): defina background=True (e, opcionalmente, stream=False). A API retorna um objeto Interaction imediatamente. Você pode usar a propriedade id para pesquisar a interação até que o estado passe de in_progress para completed ou failed.
  • Streaming: defina background=True e stream=True para receber atualizações em tempo real conforme a pesquisa avança. Para mais informações, consulte Streaming.

Também é possível configurar o agente para usar o nível adiado, que programa automaticamente jobs em segundo plano para horários de menor movimento com uma taxa de desconto de 50%. Para usar o nível adiado, stream precisa ser definido como False durante a criação da tarefa.

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=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)
      

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

A API retorna um interaction_id imediatamente. Use esse ID para sondar o status ou se reconectar a um fluxo.

Streaming

O Deep Research oferece suporte ao streaming para receber atualizações em tempo real sobre o progresso da pesquisa, incluindo resumos de ideias, saída de texto e imagens geradas. Ao usar o streaming, defina background=True e stream=True.

O exemplo a seguir inicia uma tarefa de pesquisa e processa o stream com reconexão automática. Ele rastreia o interaction_id e o last_event_id para que, se a conexão cair, possa ser retomada de onde parou.


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)

Reconecte-se ao fluxo de interação

Para recuperar uma transmissão interrompida, envie uma solicitação GET usando o interaction_id original. A API vai reproduzir todos os eventos passados desde o início da sessão antes de continuar com as atualizações em tempo 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}"

Ferramentas

O Deep Research é compatível com várias ferramentas integradas e externas. Por padrão (quando nenhum parâmetro de ferramentas é fornecido), o agente tem acesso à Pesquisa Google e ao contexto de URL. É possível especificar ferramentas para restringir ou ampliar as capacidades do agente. As ferramentas compatíveis incluem:

Ferramenta Chave Observação
Pesquisa Google google_search Pesquisar na Web pública. Ativado por padrão.
Servidores MCP mcp_server Conectar-se a servidores MCP remotos para acessar ferramentas externas.
Pesquisa na web para empresas enterprise_web_search Pesquisa na Web com controles de compliance adicionais.
Agent Search vertex_ai_search Pesquise os dados do seu site ou seus conjuntos de documentos.

O seguinte ativa a Pesquisa Google como a única ferramenta:


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 MCP

Forneça o nome e o URL do servidor na configuração das ferramentas. Você também pode transmitir credenciais de autenticação e restringir quais ferramentas o agente pode chamar.

Consulte a seguinte referência:

Campo Tipo Obrigatório Descrição
type string Sim Precisa ser "mcp_server".
name string Não Um nome de exibição para o servidor MCP.
url string Não O URL completo do endpoint do servidor MCP.
headers objeto Não Pares de chave-valor enviados como cabeçalhos HTTP com cada solicitação ao servidor (por exemplo, tokens de autenticação).
allowed_tools matriz Não Restringe quais ferramentas do servidor o agente pode chamar.

Veja o exemplo a seguir:


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
)

Com a Pesquisa Google na Web Enterprise, as organizações podem embasar as respostas da IA generativa em dados da Web seguros, compatíveis e atualizados. Ele permite que desenvolvedores e empresas conectem modelos de IA à Internet sem comprometer a privacidade dos dados ou a conformidade regulatória.

Veja o exemplo a seguir:


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 multimodais

O Deep Research aceita entradas multimodais, incluindo imagens e documentos (PDFs), permitindo que o agente analise conteúdo visual e faça pesquisas baseadas na web contextualizadas pelas entradas fornecidas.

Veja o exemplo a seguir:


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)

Entendimento de documentos

Você pode transmitir documentos diretamente como entrada multimodal. O agente analisa os documentos fornecidos e realiza pesquisas com base no conteúdo deles.

Veja o exemplo a seguir:


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
)

Capacidade de direcionamento e formatação

Você pode direcionar a saída do agente fornecendo instruções de formatação específicas no comando. Assim, você pode estruturar relatórios em seções e subseções específicas, incluir tabelas de dados ou ajustar o tom para diferentes públicos-alvo, por exemplo, "técnico", "executivo" ou "informal".

Defina a saída explicitamente no texto de entrada. Veja o exemplo a seguir:


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
)

Referência da API

Esta seção fornece informações de referência da API para usar o agente de pesquisa avançada do Gemini.

Para mais informações, consulte API Interactions.

Método: interactions.create

Nome completo:projects.locations.interactions.create

Inicia uma nova sessão de Deep Research.

Endpoint

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

Parâmetros do corpo da solicitação

Os parâmetros do corpo da solicitação podem incluir o seguinte:

Parâmetro Tipo Descrição
agent string Obrigatório. Especifica o código de ID do agente (como deep-research-preview-04-2026).
background boolean Obrigatório. Executa a interação de forma assíncrona. Precisa ser definido como true.
stream boolean Opcional. Ativa o streaming. O valor padrão é false.
input array ou string Obrigatório. Uma lista que contém a entrada do usuário. Só é possível usar um objeto.
tools array Substitui as ferramentas padrão. Suporte a google_search, external_data_mcp, vertex_search etc.
service_tier string Defina como deferred para usar o nível adiado, que agenda automaticamente jobs em segundo plano para horários de menor movimento.

Tempos limite e tratamento de erros

Ao interagir com um agente, você pode encontrar tempos limite de conexão ou erros de sistema. Esta seção explica como identificar e resolver tempos limite flexíveis e falhas graves.

Tempos limite flexíveis

Um tempo limite flexível ocorre quando a conexão da API Interactions é interrompida enquanto o agente ainda está processando uma solicitação. O agente continua executando a solicitação em segundo plano.

Para retomar a sessão e ver os eventos reproduzidos, reconecte-se ao stream usando seu interaction_id. Consulte Reconectar ao fluxo de interação.

Falhas difíceis

Uma falha grave ocorre quando um erro de agente ou do sistema interno encerra completamente o contexto do agente. Esses erros geralmente retornam um código de status HTTP 500. As causas comuns incluem exceder o limite de execução de 120 minutos ou sofrer uma falha no sistema.

Para resolver essa falha, encerre a sessão atual e refine sua consulta antes de iniciar uma nova.

Práticas recomendadas

Dar acesso à Web e aos seus arquivos a um agente autônomo introduz dinâmicas únicas. Considere as seguintes práticas recomendadas ao implementar seu projeto:

  • Solicite informações desconhecidas: instrua explicitamente o agente sobre como lidar com dados ausentes. Por exemplo, peça para ele informar se um número não está disponível em vez de estimar.

  • Evite riscos de injeção de comandos: verifique se os arquivos enviados vêm de fontes confiáveis, já que arquivos maliciosos podem conter texto oculto projetado para manipular a saída de um agente.

  • Evite a exfiltração de dados: tenha muito cuidado ao pedir que o agente resuma dados internos sensíveis e, ao mesmo tempo, dê acesso para navegar na Web pública.

  • Verifique as citações: embora o filtro de nível empresarial seja aplicado, sempre verifique as citações fornecidas na resposta para garantir que as fontes da Web sejam confiáveis.

Limitações

Considere as seguintes limitações ao planejar seu projeto:

  • Apenas uma interação: só consultas de uma interação são aceitas. O uso do campo previous_interaction_id da API não é compatível.

  • Segurança empresarial: durante o pré-lançamento, as chaves de criptografia gerenciadas pelo cliente (CMEK) e o VPC Service Controls não são compatíveis. As restrições de residência de dados multirregionais estão em avaliação.

  • Armazenamento em cache: o armazenamento em cache implícito está ativado por padrão para esse serviço. Não é possível desativar.

  • Retenção de dados: os comandos e a saída gerada são armazenados por sete dias para processamento padrão. Ao usar o Embasamento com a Pesquisa Google, o Google armazena comandos, informações contextuais e resultados gerados por três dias para depuração e testes. Se você usa o embasamento com a Pesquisa Google, não é possível desativar o armazenamento dessas informações. Se você não quiser retenção de dados, recomendamos usar o embasamento com a Pesquisa na Web empresarial.

Preços

O Deep Research usa os recursos avançados de raciocínio do Gemini para realizar tarefas de pesquisa agêntica de várias etapas. O faturamento inclui o uso do modelo (tokens) e a execução de ferramentas (pesquisa e embasamento).

Para jobs em segundo plano, use o nível adiado para receber um desconto.

Para saber mais informações, consulte Preços.

Monitoramento de custos

Por padrão, o agente Deep Research do Gemini aplica automaticamente o rótulo de usuário is_deep_research às operações dele. No Google Cloud, os rótulos são pares de chave-valor leves usados para organizar recursos e rastrear custos em toda a infraestrutura.

  • Rotulagem automática: não é necessário configurar manualmente esse marcador nas solicitações de API. Por padrão, o agente inclui o marcador is_deep_research em todas as tarefas executadas.

  • Filtragem de faturamento: os relatórios de faturamento do Deep Research podem ser filtrados usando o rótulo de faturamento is_deep_research.

  • Rastreamento abrangente: o rótulo de faturamento is_deep_research se aplica ao uso do modelo (tokens de entrada e saída) e à execução de ferramentas (uso de pesquisa e embasamento). Isso ajuda a agregar e calcular o custo total dos fluxos de trabalho de pesquisa assíncrona.

Cota

Para acomodar tráfego mais alto, tarefas em segundo plano simultâneas ou cargas de pesquisa mais pesadas, solicite um aumento de cota para a API Agent Platform diretamente no seu projeto Google Cloud .

Para aumentar sua cota, faça o seguinte:

  1. No console do Google Cloud , acesse a página Cotas e limites do sistema.

    Acesse "Cotas e limites do sistema"

  2. Verifique se você selecionou o projeto correto que está executando suas cargas de trabalho de Deep Research.

  3. Na caixa de pesquisa de filtro, procure API Agent Platform (aiplatform.googleapis.com) para encontrar as cotas relevantes de agente e interação.

  4. Selecione o limite de cota específico que você precisa ajustar.

  5. Clique em Editar cotas.

  6. Na caixa de diálogo Mudanças de cota, no campo Novo valor, insira o limite solicitado. Forneça uma justificativa clara na descrição da solicitação. Mencionar seu caso de uso específico da Deep Research, as necessidades de execução em segundo plano e os padrões de tráfego esperados pode ajudar a acelerar o processo de aprovação.

  7. Clique em Enviar solicitação.

Segurança e conformidade

Esta seção explica como seus dados são retidos e armazenados em cache e lista os controles de segurança que não são compatíveis durante a prévia.

Retenção de dados

Os comandos e a saída gerada são armazenados por sete (7) dias para processamento padrão.

Conforme descrito na Seção 19 "Serviços de IA generativa: embasamento com a Pesquisa Google" dos Termos específicos do serviço, o Google armazena comandos e informações contextuais que os clientes podem fornecer, além de resultados gerados por três (3) dias para criar resultados embasados e sugestões de pesquisa. Essas informações armazenadas podem ser usadas para depuração e teste de sistemas que oferecem embasamento com a Pesquisa Google. Não é possível desativar o armazenamento dessas informações se você usa o embasamento com a Pesquisa Google. Se você não quiser retenção de dados, recomendamos usar o Fundamentação na Web para empresas.

Armazenamento em cache

O caching implícito é ativado por padrão para o Deep Research e não pode ser desativado.

Controles de segurança

Os seguintes controles de segurança não são compatíveis durante a prévia:

  • Chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês)
  • VPC Service Controls (VPC-SC)
  • Transparência no acesso (AXT)
  • Residência de dados
  • Residência de dados multirregional

A seguir

Referência

Saiba mais sobre a API Interactions, que permite interagir com um agente.

Tutorial

Comece a usar este notebook Python do Deep Research no GitHub.