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 empresariais privados, para gerar relatórios abrangentes e citados que aceleram a tomada de decisões embasadas.
Nesta página, você vai aprender a 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 extensa: 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 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 de 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:
- Servidores MCP remotos
- Embasamento com o Agent Search
- Embasamento com a Pesquisa Google ou Embasamento na Web para empresas, que são respaldados por padrões rigorosos de privacidade e filtragem adequados para cargas de trabalho empresariais
- Uploads inline de arquivos e pastas (como PDFs e planilhas), permitindo inserir contexto diretamente no fluxo de trabalho de pesquisa e receber citações
- 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 in-line
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 Introdução ao Deep Research Agent do Gemini no GitHub.
Antes de começar
- Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
Make sure that you have the following role or roles on the project: roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
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.
- 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
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
- Click Grant access.
-
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
- Click Select a role, then search for the role.
- To grant additional roles, click Add another role and add each additional role.
- Click Save.
-
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
Make sure that you have the following role or roles on the project: roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
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.
- 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
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
- Click Grant access.
-
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
- Click Select a role, then search for the role.
- To grant additional roles, click Add another role and add each additional role.
- 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 do Deep Research do Gemini de forma assíncrona.
Você precisa usar a execução em segundo plano e o modo de streaming. Para fazer isso, defina os campos background e stream como True na configuração de resposta ao executar o agente. A API retorna um objeto Interaction parcial imediatamente. É possível usar a propriedade id para recuperar
uma interação para sondagem. O estado de interação vai mudar de
in_progress para 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=False
)
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
}'A API retorna um interaction_id imediatamente. Esse ID é necessário para
reconectar ao stream.
Streaming
O Deep Research oferece suporte a streaming para receber atualizações em tempo real sobre o progresso da pesquisa, incluindo resumos de ideias, saída de texto e imagens geradas. 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, ela 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 um fluxo descartado, envie uma solicitação GET usando o
interaction_id original. A API vai reproduzir todos os eventos anteriores 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. Você pode especificar explicitamente ferramentas para restringir ou ampliar as capacidades do agente. As ferramentas compatíveis incluem:
| Ferramenta | Chave | Observação |
|---|---|---|
| Pesquisa Google | google_search
|
Pesquise na Web pública. Ativado por padrão. |
| Servidores MCP | mcp_server
|
Conecte-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. |
Pesquisa Google
O seguinte comando 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. Também é possível transmitir credenciais de autenticação e restringir quais ferramentas o agente pode chamar.
Confira 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
)
Pesquisa na web para empresas
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
É possível 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:
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
|
Obrigatório. Ativa o streaming. Precisa ser definido como
true. |
input
|
array
ou
string |
Obrigatório. Uma lista que contém a entrada do usuário. Apenas um objeto é aceito. |
tools
|
array
|
Substitui as ferramentas padrão. É compatível com
google_search, external_data_mcp,
vertex_search etc. |
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 limites 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, interrompa 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 exclusivas. 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 a ele para navegar na Web pública.
Verifique as citações: embora seja aplicado um filtro de nível empresarial, 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ó é possível fazer consultas de uma interação. Não há suporte para o uso do campo
previous_interaction_idda API.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 é ativado por padrão para esse serviço. Não é possível desativar esse recurso.
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 recurso de 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 Enterprise.
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 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 rótulo nas solicitações de API. O agente inclui o rótulo
is_deep_researchpor padrão 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_researchse aplica ao uso do modelo (tokens de entrada e saída) e à execução da ferramenta (uso de pesquisa e embasamento). Isso ajuda a agregar e calcular o custo total dos seus fluxos de trabalho de pesquisa assíncronos.
Cota
Para acomodar tráfego mais alto, tarefas em segundo plano simultâneas ou cargas de pesquisa mais pesadas, você pode solicitar um aumento de cota para a API Agent Platform diretamente no seu projeto Google Cloud .
Para aumentar sua cota, faça o seguinte:
No console do Google Cloud , acesse a página Cotas e limites do sistema.
Verifique se você selecionou o projeto correto que está executando suas cargas de trabalho de Deep Research.
Na caixa de pesquisa de filtro, procure API Agent Platform (
aiplatform.googleapis.com) para encontrar as cotas de agente e interação relevantes.Selecione o limite de cota específico que você precisa ajustar.
Clique em Editar cotas.
Na caixa de diálogo Mudanças de cota, insira o limite solicitado no campo Novo valor. 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.
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 da saída gerada 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 suporte ao embasamento com a Pesquisa Google. Não é possível desativar o armazenamento dessas informações se você usar o embasamento com a Pesquisa Google. Se você não quiser retenção de dados, recomendamos usar o Web Grounding para empresas.
Armazenamento em cache
O armazenamento em cache 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 dos dados
- Residência de dados multirregional
A seguir
Referência da API Interactions
Saiba mais sobre a API Interactions, que permite interagir com um agente.
Notebook: Introduction to Gemini Deep Research Agent
Comece a usar este notebook Python do Deep Research no GitHub.