Agente de Deep Research do Gemini

O agente Deep Research do Gemini planeja, executa e sintetiza de forma autônoma tarefas de pesquisa de várias etapas. Com tecnologia do Gemini 3 Pro, ele navega por informações complexas usando a pesquisa na Web e seus próprios dados para produzir relatórios detalhados e com citações.

As atividades de pesquisa envolvem busca e leitura iterativas e podem levar vários minutos para serem concluídas. É necessário usar a execução em segundo plano (defina background=true) para executar o agente de forma assíncrona e pesquisar resultados. Consulte Como processar tarefas de longa duração para mais detalhes.

O exemplo a seguir mostra como iniciar uma tarefa de pesquisa em segundo plano e consultar os resultados.

Python

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    input="Research the history of Google TPUs.",
    agent='deep-research-pro-preview-12-2025',
    background=True
)

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

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

JavaScript

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    input: 'Research the history of Google TPUs.',
    agent: 'deep-research-pro-preview-12-2025',
    background: true
});

console.log(`Research started: ${interaction.id}`);

while (true) {
    const result = await client.interactions.get(interaction.id);
    if (result.status === 'completed') {
        console.log(result.outputs[result.outputs.length - 1].text);
        break;
    } else if (result.status === 'failed') {
        console.log(`Research failed: ${result.error}`);
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 10000));
}

REST

# 1. Start the research task
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Research the history of Google TPUs.",
    "agent": "deep-research-pro-preview-12-2025",
    "background": true
}'

# 2. Poll for results (Replace INTERACTION_ID)
# curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID" \
# -H "x-goog-api-key: $GEMINI_API_KEY"

Pesquisar com seus próprios dados

O Deep Research tem acesso a várias ferramentas. Por padrão, o agente tem acesso a informações na Internet pública usando as ferramentas google_search e url_context. Não é necessário especificar essas ferramentas por padrão. No entanto, se você quiser dar ao agente acesso aos seus próprios dados usando a ferramenta Pesquisa de arquivos, adicione-a conforme mostrado no exemplo a seguir.

Python

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    input="Compare our 2025 fiscal year report against current public web news.",
    agent="deep-research-pro-preview-12-2025",
    background=True,
    tools=[
        {
            "type": "file_search",
            "file_search_store_names": ['fileSearchStores/my-store-name']
        }
    ]
)

JavaScript

const interaction = await client.interactions.create({
    input: 'Compare our 2025 fiscal year report against current public web news.',
    agent: 'deep-research-pro-preview-12-2025',
    background: true,
    tools: [
        { type: 'file_search', file_search_store_names: ['fileSearchStores/my-store-name'] },
    ]
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Compare our 2025 fiscal year report against current public web news.",
    "agent": "deep-research-pro-preview-12-2025",
    "background": true,
    "tools": [
        {"type": "file_search", "file_search_store_names": ["fileSearchStores/my-store-name"]},
    ]
}'

Capacidade de direcionamento e formatação

Você pode direcionar a saída do agente fornecendo instruções de formatação específicas no comando. Isso permite 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", "casual".

Defina o formato de saída desejado explicitamente no texto de entrada.

Python

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-pro-preview-12-2025",
    background=True
)

JavaScript

const 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
`;

const interaction = await client.interactions.create({
    input: prompt,
    agent: 'deep-research-pro-preview-12-2025',
    background: true,
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Research the competitive landscape of EV batteries.\n\nFormat the output as a technical report with the following structure: \n1. Executive Summary\n2. Key Players (Must include a data table comparing capacity and chemistry)\n3. Supply Chain Risks",
    "agent": "deep-research-pro-preview-12-2025",
    "background": true
}'

Como processar tarefas de longa duração

O Deep Research é um processo de várias etapas que envolve planejamento, pesquisa, leitura e escrita. Esse ciclo geralmente excede os limites de tempo limite padrão das chamadas de API síncronas.

Os agentes precisam usar o background=True. 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.

Streaming

O Deep Research é compatível com streaming para receber atualizações em tempo real sobre o progresso da pesquisa. Defina stream=True e background=True.

O exemplo a seguir mostra como iniciar uma tarefa de pesquisa e processar o fluxo. Principalmente, ele demonstra como rastrear o interaction_id do evento interaction.start. Você vai precisar desse ID para retomar o stream se ocorrer uma interrupção na rede. Esse código também apresenta uma variável event_id que permite retomar do ponto específico em que você se desconectou.

Python

stream = client.interactions.create(
    input="Research the history of Google TPUs.",
    agent="deep-research-pro-preview-12-2025",
    background=True,
    stream=True,
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto"
    }
)

interaction_id = None
last_event_id = None

for chunk in stream:
    if chunk.event_type == "interaction.start":
        interaction_id = chunk.interaction.id
        print(f"Interaction started: {interaction_id}")

    if chunk.event_id:
        last_event_id = chunk.event_id

    if chunk.event_type == "content.delta":
        if chunk.delta.type == "text":
            print(chunk.delta.text, end="", flush=True)
        elif chunk.delta.type == "thought_summary":
            print(f"Thought: {chunk.delta.content.text}", flush=True)

    elif chunk.event_type == "interaction.complete":
        print("\nResearch Complete")

JavaScript

const stream = await client.interactions.create({
    input: 'Research the history of Google TPUs.',
    agent: 'deep-research-pro-preview-12-2025',
    background: true,
    stream: true,
    agent_config: {
        type: 'deep-research',
        thinking_summaries: 'auto'
    }
});

let interactionId;
let lastEventId;

for await (const chunk of stream) {
    // 1. Capture Interaction ID
    if (chunk.event_type === 'interaction.start') {
        interactionId = chunk.interaction.id;
        console.log(`Interaction started: ${interactionId}`);
    }

    // 2. Track IDs for potential reconnection
    if (chunk.event_id) lastEventId = chunk.event_id;

    // 3. Handle Content
    if (chunk.event_type === 'content.delta') {
        if (chunk.delta.type === 'text') {
            process.stdout.write(chunk.delta.text);
        } else if (chunk.delta.type === 'thought_summary') {
            console.log(`Thought: ${chunk.delta.content.text}`);
        }
    } else if (chunk.event_type === 'interaction.complete') {
        console.log('\nResearch Complete');
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Research the history of Google TPUs.",
    "agent": "deep-research-pro-preview-12-2025",
    "background": true,
    "stream": true,
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto"
    }
}'
# Note: Look for the 'interaction.start' event to get the interaction ID.

Reconectando à transmissão

Interrupções de rede podem ocorrer durante tarefas de pesquisa de longa duração. Para lidar com isso de maneira adequada, seu aplicativo precisa capturar erros de conexão e retomar o fluxo usando client.interactions.get().

Você precisa fornecer dois valores para retomar:

  1. ID da interação:adquirido do evento interaction.start no fluxo inicial.
  2. ID do último evento:o ID do último evento processado com sucesso. Isso informa ao servidor para retomar o envio de eventos depois desse ponto específico. Se não for fornecido, você vai receber o início do stream.

Os exemplos a seguir demonstram um padrão resiliente: tentativa de transmitir a solicitação inicial de create e retorno a um loop de get se a conexão cair.

Python

import time
from google import genai

client = genai.Client()

# Configuration
agent_name = 'deep-research-pro-preview-12-2025'
prompt = 'Compare golang SDK test frameworks'

# State tracking
last_event_id = None
interaction_id = None
is_complete = False

def process_stream(event_stream):
    """Helper to process events from any stream source."""
    global last_event_id, interaction_id, is_complete
    for event in event_stream:
        # Capture Interaction ID
        if event.event_type == "interaction.start":
            interaction_id = event.interaction.id
            print(f"Interaction started: {interaction_id}")

        # Capture Event ID
        if event.event_id:
            last_event_id = event.event_id

        # Print content
        if event.event_type == "content.delta":
            if event.delta.type == "text":
                print(event.delta.text, end="", flush=True)
            elif event.delta.type == "thought_summary":
                print(f"Thought: {event.delta.content.text}", flush=True)

        # Check completion
        if event.event_type in ['interaction.complete', 'error']:
            is_complete = True

# 1. Attempt initial streaming request
try:
    print("Starting Research...")
    initial_stream = client.interactions.create(
        input=prompt,
        agent=agent_name,
        background=True,
        stream=True,
        agent_config={
            "type": "deep-research",
            "thinking_summaries": "auto"
        }
    )
    process_stream(initial_stream)
except Exception as e:
    print(f"\nInitial connection dropped: {e}")

# 2. Reconnection Loop
# If the code reaches here and is_complete is False, we resume using .get()
while not is_complete and interaction_id:
    print(f"\nConnection lost. Resuming from event {last_event_id}...")
    time.sleep(2) 

    try:
        resume_stream = client.interactions.get(
            id=interaction_id,
            stream=True,
            last_event_id=last_event_id
        )
        process_stream(resume_stream)
    except Exception as e:
        print(f"Reconnection failed, retrying... ({e})")

JavaScript

let lastEventId;
let interactionId;
let isComplete = false;

// Helper to handle the event logic
const handleStream = async (stream) => {
    for await (const chunk of stream) {
        if (chunk.event_type === 'interaction.start') {
            interactionId = chunk.interaction.id;
        }
        if (chunk.event_id) lastEventId = chunk.event_id;

        if (chunk.event_type === 'content.delta') {
            if (chunk.delta.type === 'text') {
                process.stdout.write(chunk.delta.text);
            } else if (chunk.delta.type === 'thought_summary') {
                console.log(`Thought: ${chunk.delta.content.text}`);
            }
        } else if (chunk.event_type === 'interaction.complete') {
            isComplete = true;
        }
    }
};

// 1. Start the task with streaming
try {
    const stream = await client.interactions.create({
        input: 'Compare golang SDK test frameworks',
        agent: 'deep-research-pro-preview-12-2025',
        background: true,
        stream: true,
        agent_config: {
            type: 'deep-research',
            thinking_summaries: 'auto'
        }
    });
    await handleStream(stream);
} catch (e) {
    console.log('\nInitial stream interrupted.');
}

// 2. Reconnect Loop
while (!isComplete && interactionId) {
    console.log(`\nReconnecting to interaction ${interactionId} from event ${lastEventId}...`);
    try {
        const stream = await client.interactions.get(interactionId, {
            stream: true,
            last_event_id: lastEventId
        });
        await handleStream(stream);
    } catch (e) {
        console.log('Reconnection failed, retrying in 2s...');
        await new Promise(resolve => setTimeout(resolve, 2000));
    }
}

REST

# 1. Start the research task (Initial Stream)
# Watch for event: interaction.start to get the INTERACTION_ID
# Watch for "event_id" fields to get the LAST_EVENT_ID
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Compare golang SDK test frameworks",
    "agent": "deep-research-pro-preview-12-2025",
    "background": true,
    "stream": true,
    "agent_config": {
        "type": "deep-research",
        "thinking_summaries": "auto"
    }
}'

# ... Connection interrupted ...

# 2. Reconnect (Resume Stream)
# Pass the INTERACTION_ID and the LAST_EVENT_ID you saved.
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID?stream=true&last_event_id=LAST_EVENT_ID&alt=sse" \
-H "x-goog-api-key: $GEMINI_API_KEY"

Perguntas e interações complementares

Você pode continuar a conversa depois que o agente retornar o relatório final usando o previous_interaction_id. Assim, é possível pedir esclarecimentos, resumos ou mais detalhes sobre seções específicas da pesquisa sem precisar reiniciar toda a tarefa.

Python

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    input="Can you elaborate on the second point in the report?",
    model="gemini-3-pro-preview",
    previous_interaction_id="COMPLETED_INTERACTION_ID"
)

print(interaction.outputs[-1].text)

JavaScript

const interaction = await client.interactions.create({
    input: 'Can you elaborate on the second point in the report?',
    agent: 'deep-research-pro-preview-12-2025',
    previous_interaction_id: 'COMPLETED_INTERACTION_ID'
});
console.log(interaction.outputs[-1].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "input": "Can you elaborate on the second point in the report?",
    "agent": "deep-research-pro-preview-12-2025",
    "previous_interaction_id": "COMPLETED_INTERACTION_ID"
}'

Quando usar o agente do Deep Research do Gemini

O Deep Research é um agente, não apenas um modelo. Ele é mais adequado para cargas de trabalho que exigem uma abordagem de "analista em uma caixa" em vez de um chat de baixa latência.

Recurso Modelos padrão do Gemini Agente de Deep Research do Gemini
Latência Segundos Minutos (assíncrono/em segundo plano)
Processo Gerar -> Saída Planejar -> Pesquisar -> Ler -> Iterar -> Saída
Saída Texto conversacional, código, resumos curtos Relatórios detalhados, análises longas, tabelas comparativas
Ideal para Chatbots, extração, escrita criativa Análise de mercado, due diligence, revisões de literatura, análise da concorrência

Disponibilidade e preços

  • Disponibilidade:acessível usando a API Interactions no Google AI Studio e na API Gemini.
  • Preços:consulte a página de preços para conferir tarifas e detalhes específicos.

Considerações sobre segurança

Dar acesso à Web e aos seus arquivos particulares exige uma análise cuidadosa dos riscos de segurança.

  • Injeção de comandos usando arquivos:o agente lê o conteúdo dos arquivos que você fornece. Verifique se os documentos enviados (PDFs, arquivos de texto) são de fontes confiáveis. Um arquivo malicioso pode conter texto oculto projetado para manipular a saída do agente.
  • Riscos de conteúdo da Web:o agente pesquisa na Web pública. Embora implementemos filtros de segurança robustos, há o risco de o agente encontrar e processar páginas da Web maliciosas. Recomendamos que você analise o citations fornecido na resposta para verificar as fontes.
  • Exfiltração:tenha cuidado ao pedir para o agente resumir dados internos sensíveis se você também permitir que ele navegue na Web.

Práticas recomendadas

  • Solicite informações desconhecidas:instrua o agente sobre como lidar com dados ausentes. Por exemplo, adicione "Se números específicos para 2025 não estiverem disponíveis, declare explicitamente que são projeções ou que não estão disponíveis, em vez de estimar" ao comando.
  • Forneça contexto:embasar a pesquisa do agente com informações ou restrições de contexto diretamente no comando de entrada.
  • Entradas multimodais: o agente do Deep Research aceita entradas multimodais. Use com cuidado, porque isso aumenta os custos e o risco de estouro da janela de contexto.

Limitações

  • Status Beta: a API Interactions está na versão Beta pública. Os recursos e esquemas podem mudar.
  • Ferramentas personalizadas:no momento, não é possível fornecer ferramentas personalizadas de chamada de função ou servidores MCP (Protocolo de Contexto de Modelo) remotos para o agente Deep Research.
  • Saída estruturada e aprovação de planos:no momento, o agente do Deep Research não é compatível com planejamento aprovado por humanos nem saídas estruturadas.
  • Tempo máximo de pesquisa:o agente do Deep Research tem um tempo máximo de pesquisa de 60 minutos. A maioria das tarefas é concluída em até 20 minutos.
  • Requisito de armazenamento:a execução do agente usando background=True exige store=True.
  • Pesquisa Google:a Pesquisa Google está ativada por padrão, e restrições específicas se aplicam aos resultados embasados.
  • Entradas de áudio:não são aceitas.

A seguir