Агент 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
Мультимодальные входные данные
Deep Research поддерживает мультимодальные входные данные, включая изображения, PDF-файлы, аудио и видео, что позволяет агенту анализировать разнообразный контент и проводить веб-исследования в контексте предоставленных входных данных. Например, вы можете предоставить фотографию и попросить агента идентифицировать объекты, изучить их поведение или найти связанную информацию.
В следующем примере показан запрос на анализ изображения с использованием URL-адреса изображения.
Python
import time
from google import genai
client = genai.Client()
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-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 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.`;
const interaction = await 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-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 with image input
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": [
{"type": "text", "text": "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."},
{"type": "image", "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"}
],
"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"
Выполнение длительных задач
Глубокое исследование — это многоэтапный процесс, включающий планирование, поиск, чтение и запись. Этот цикл обычно превышает стандартные ограничения по времени ожидания для синхронных вызовов 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() .
Для возобновления работы необходимо указать два значения:
- Идентификатор взаимодействия: Получен из события
interaction.startв исходном потоке. - Идентификатор последнего события: Идентификатор последнего успешно обработанного события. Это указывает серверу на необходимость возобновления отправки событий после этой конкретной точки. Если идентификатор не указан, будет отправлено начало потока.
Следующие примеры демонстрируют устойчивый шаблон: попытка потоковой передачи первоначального запроса 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 |
|---|---|---|
| Задержка | Секунды | Минуты (асинхронный/фоновый режим) |
| Процесс | Сгенерировать -> Вывод | Планирование -> Поиск -> Чтение -> Итерация -> Вывод |
| Выход | Разговорный текст, код, краткие резюме | Подробные отчеты, развернутый анализ, сравнительные таблицы. |
| Лучше всего подходит для | Чат-боты, извлечение информации, креативное письмо | Анализ рынка, комплексная проверка, обзор литературы, анализ конкурентной среды. |
Наличие и цены
Вы можете получить доступ к Gemini Deep Research Agent, используя Interactions API в Google AI Studio и Gemini API.
Ценообразование основано на модели оплаты по мере использования, исходя из базовой модели Gemini 3 Pro и конкретных инструментов, используемых агентом. В отличие от стандартных запросов в чате, где запрос приводит к одному результату, задача «Глубокое исследование» представляет собой рабочий процесс агента. Один запрос запускает автономный цикл планирования, поиска, чтения и анализа.
Ориентировочные затраты
Стоимость зависит от глубины необходимого исследования. Агент самостоятельно определяет, сколько чтения и поиска потребуется для ответа на ваш запрос.
- Стандартная исследовательская задача: для типичного запроса, требующего умеренного анализа, агент может использовать около 80 поисковых запросов, около 250 тысяч входных токенов (примерно 50-70% кэшированных) и около 60 тысяч выходных токенов.
- Ориентировочная общая стоимость: ~2,00–3,00 доллара за задание.
- Сложная исследовательская задача: для глубокого анализа конкурентной среды или проведения всесторонней комплексной проверки агент может использовать до ~160 поисковых запросов, ~900 тыс. входных токенов (~50-70% из которых кэшированы) и ~80 тыс. выходных токенов.
- Ориентировочная общая стоимость: ~3,00–5,00 долларов за задание.
Вопросы безопасности
Предоставление агенту доступа к интернету и вашим личным файлам требует тщательного учета рисков для безопасности.
- Внедрение подсказок с использованием файлов: агент считывает содержимое предоставленных вами файлов. Убедитесь, что загружаемые документы (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 , которая используется в этом агенте.
- Узнайте, как использовать собственные данные с помощью инструмента поиска по файлам .