Агент по глубоким исследованиям компании Gemini

Агент Gemini Deep Research автономно планирует, выполняет и обобщает многоэтапные исследовательские задачи. Работая на базе Gemini 3 Pro, он ориентируется в сложных информационных пространствах, используя веб-поиск и ваши собственные данные, для создания подробных отчетов с цитируемыми ссылками.

Исследовательские задачи включают итеративный поиск и чтение и могут занимать несколько минут. Для асинхронного запуска агента и получения результатов необходимо использовать фоновое выполнение (установите background=true ). Дополнительные сведения см. в разделе «Обработка длительных задач» .

В следующем примере показано, как запустить исследовательскую задачу в фоновом режиме и запросить результаты.

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));
}

ОТДЫХ 

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

Проведите исследование, используя собственные данные.

Deep Research имеет доступ к различным инструментам. По умолчанию агент имеет доступ к информации в общедоступном интернете, используя инструменты google_search и url_context . По умолчанию указывать эти инструменты не требуется. Однако, если вы дополнительно хотите предоставить агенту доступ к вашим собственным данным с помощью инструмента поиска файлов, вам потребуется добавить его, как показано в следующем примере.

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'] },
    ]
});

ОТДЫХ 

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"]},
    ]
}'

Управляемость и форматирование

Вы можете управлять выводом агента, указывая конкретные инструкции по форматированию в своем запросе. Это позволяет структурировать отчеты по определенным разделам и подразделам, включать таблицы данных или корректировать тон для разных аудиторий (например, «технические специалисты», «руководители», «неформальные пользователи»).

Укажите желаемый формат вывода явно во входном тексте.

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,
});

ОТДЫХ 

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

Выполнение длительных задач

Глубокое исследование — это многоэтапный процесс, включающий планирование, поиск, чтение и запись. Этот цикл обычно превышает стандартные ограничения по времени ожидания для синхронных вызовов API.

Агентам необходимо использовать background=True . API немедленно возвращает частичный объект Interaction . Вы можете использовать свойство id для получения информации о взаимодействии для опроса. Состояние взаимодействия будет переходить из in_progress в completed или failed .

Стриминг

Deep Research поддерживает потоковую передачу данных для получения обновлений о ходе исследований в режиме реального времени. Необходимо установить stream=True и background=True .

Следующий пример показывает, как начать исследовательскую задачу и обработать поток. Важно отметить, что он демонстрирует, как отслеживать interaction_id из события interaction.start . Этот ID понадобится вам для возобновления потока в случае прерывания сети. В этом коде также вводится переменная event_id , которая позволяет возобновить работу с того места, где произошло отключение.

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');
    }
}

ОТДЫХ 

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.

Повторное подключение к потоку

Во время длительных исследовательских задач могут возникать сбои в сети. Для корректной обработки таких ситуаций ваше приложение должно перехватывать ошибки подключения и возобновлять поток с помощью client.interactions.get() .

Для возобновления работы необходимо указать два значения:

  1. Идентификатор взаимодействия: Получен из события interaction.start в исходном потоке.
  2. Идентификатор последнего события: Идентификатор последнего успешно обработанного события. Это указывает серверу на необходимость возобновления отправки событий после этой конкретной точки. Если идентификатор не указан, будет отправлено начало потока.

Следующие примеры демонстрируют устойчивый шаблон: попытка потоковой передачи первоначального запроса create и последующий переход к циклу get , если соединение обрывается.

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));
    }
}

ОТДЫХ 

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

Дополнительные вопросы и взаимодействие

После того, как агент вернет окончательный отчет, вы можете продолжить разговор, используя previous_interaction_id . Это позволит вам запросить уточнения, обобщения или дополнения по конкретным разделам исследования, не начиная всю задачу заново.

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

ОТДЫХ 

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

Когда использовать Gemini Deep Research Agent

Deep Research — это агент , а не просто модель. Он лучше всего подходит для задач, требующих подхода «аналитик в коробке», а не для чата с низкой задержкой.

Особенность Стандартные модели Gemini Агент по глубоким исследованиям компании Gemini
Задержка Секунды Минуты (асинхронный/фоновый режим)
Процесс Сгенерировать -> Вывод Планирование -> Поиск -> Чтение -> Итерация -> Вывод
Выход Разговорный текст, код, краткие резюме Подробные отчеты, развернутый анализ, сравнительные таблицы.
Лучше всего подходит для Чат-боты, извлечение информации, креативное письмо Анализ рынка, комплексная проверка, обзор литературы, анализ конкурентной среды.

Наличие и цены

  • Доступность: Доступен через API взаимодействий в Google AI Studio и API Gemini.
  • Цены: Подробную информацию о тарифах и условиях смотрите на странице «Цены» .

Вопросы безопасности

Предоставление агенту доступа к интернету и вашим личным файлам требует тщательного учета рисков для безопасности.

  • Внедрение подсказок с использованием файлов: агент считывает содержимое предоставленных вами файлов. Убедитесь, что загружаемые документы (PDF-файлы, текстовые файлы) поступают из надежных источников. Вредоносный файл может содержать скрытый текст, предназначенный для манипулирования выводом агента.
  • Риски, связанные с веб-контентом: Агент осуществляет поиск в общедоступной сети Интернет. Хотя мы используем надежные фильтры безопасности, существует риск того, что агент может столкнуться с вредоносными веб-страницами и обработать их. Мы рекомендуем проверить citations предоставленные в ответе, чтобы убедиться в достоверности источников.
  • Извлечение информации: Будьте осторожны, запрашивая у агента краткое изложение конфиденциальных внутренних данных, если вы также разрешаете ему просматривать веб-страницы.

Передовые методы

  • Подсказка для неизвестных данных: проинструктируйте агента, как обрабатывать отсутствующие данные. Например, добавьте в подсказку фразу : «Если конкретные данные за 2025 год недоступны, явно укажите, что это прогнозы или данные, которые не доступны, а не оценки» .
  • Предоставьте контекст: обоснуйте исследование агента, предоставив справочную информацию или ограничения непосредственно в подсказке для ввода.
  • Многомодальный ввод. Deep Research Agent поддерживает многомодальный ввод. Используйте с осторожностью, так как это увеличивает затраты и риск переполнения контекстного окна.

Ограничения

  • Статус бета-версии : API взаимодействий находится в стадии публичного бета-тестирования. Функции и схемы могут изменяться.
  • Пользовательские инструменты: В настоящее время вы не можете предоставлять агенту Deep Research пользовательские инструменты вызова функций или удаленные серверы MCP (Model Context Protocol).
  • Структурированный вывод и утверждение плана: В настоящее время Deep Research Agent не поддерживает утверждение плана человеком или структурированный вывод.
  • Максимальное время исследования: Агент Deep Research может проводить исследование максимум 60 минут. Большинство задач должны быть выполнены в течение 20 минут.
  • Требование к хранилищу: Для выполнения агента с background=True требуется store=True .
  • Поиск Google: Поиск Google включен по умолчанию, и к полученным результатам применяются определенные ограничения .
  • Аудиовходы: Аудиовходы не поддерживаются.

Что дальше?

  • Узнайте больше об API взаимодействий .
  • Ознакомьтесь с информацией о модели Gemini 3 Pro , которая используется в этом агенте.
  • Узнайте, как использовать собственные данные с помощью инструмента поиска по файлам .