عامل تحقیقات عمیق Gemini به طور خودکار وظایف تحقیقاتی چند مرحلهای را برنامهریزی، اجرا و ترکیب میکند. این عامل که توسط Gemini 3 Pro پشتیبانی میشود، با استفاده از جستجوی وب و دادههای شخصی شما، در مناظر اطلاعاتی پیچیده پیمایش میکند تا گزارشهای دقیق و قابل استنادی تولید کند.
وظایف تحقیقاتی شامل جستجو و خواندن تکراری هستند و تکمیل آنها میتواند چندین دقیقه طول بکشد. شما باید از اجرای پسزمینه (set background=true ) برای اجرای ناهمگام عامل و نظرسنجی برای نتایج استفاده کنید. برای جزئیات بیشتر به بخش مدیریت وظایف طولانی مدت مراجعه کنید.
مثال زیر نحوه شروع یک کار تحقیقاتی در پسزمینه و نظرسنجی برای نتایج را نشان میدهد.
پایتون
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)
جاوا اسکریپت
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 به اطلاعات موجود در اینترنت عمومی دسترسی دارد. نیازی نیست که این ابزارها را به طور پیشفرض مشخص کنید. با این حال، اگر میخواهید با استفاده از ابزار جستجوی فایل ، به عامل دسترسی به دادههای خود را نیز بدهید، باید آن را همانطور که در مثال زیر نشان داده شده است، اضافه کنید.
پایتون
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']
}
]
)
جاوا اسکریپت
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"]},
]
}'
قابلیت هدایت و قالببندی
شما میتوانید با ارائه دستورالعملهای قالببندی خاص در اعلان خود، خروجی نماینده را هدایت کنید. این به شما امکان میدهد گزارشها را در بخشها و زیربخشهای خاص ساختار دهید، جداول داده را در آنها بگنجانید یا لحن را برای مخاطبان مختلف (مثلاً "فنی"، "اجرایی"، "غیررسمی") تنظیم کنید.
قالب خروجی مورد نظر را به طور صریح در متن ورودی خود تعریف کنید.
پایتون
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
)
جاوا اسکریپت
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 همزمان فراتر میرود.
عاملها (agents) ملزم به استفاده از background=True هستند. API بلافاصله یک شیء Interaction جزئی را برمیگرداند. میتوانید از ویژگی id برای بازیابی یک تعامل برای نظرسنجی استفاده کنید. وضعیت تعامل از in_progress به completed یا failed تغییر خواهد کرد.
پخش جریانی
Deep Research از پخش جریانی برای دریافت بهروزرسانیهای بلادرنگ در مورد پیشرفت تحقیق پشتیبانی میکند. شما باید stream=True و background=True را تنظیم کنید.
مثال زیر نحوه شروع یک کار تحقیقاتی و پردازش جریان را نشان میدهد. نکته مهم این است که نحوه ردیابی interaction_id از رویداد interaction.start را نشان میدهد. در صورت بروز وقفه در شبکه، برای از سرگیری جریان به این شناسه نیاز خواهید داشت. این کد همچنین یک متغیر event_id معرفی میکند که به شما امکان میدهد از نقطه خاصی که اتصال را قطع کردهاید، از سر بگیرید.
پایتون
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")
جاوا اسکریپت
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 در صورت قطع اتصال.
پایتون
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})")
جاوا اسکریپت
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 مکالمه را ادامه دهید. این به شما امکان میدهد بدون شروع مجدد کل کار، درخواست شفافسازی، خلاصهسازی یا شرح بخشهای خاصی از تحقیق را داشته باشید.
پایتون
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)
جاوا اسکریپت
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 یک عامل است، نه فقط یک مدل. این ابزار برای بارهای کاری که به رویکرد «تحلیلگر در دسترس» نیاز دارند، به جای چت با تأخیر کم، مناسبتر است.
| ویژگی | مدلهای استاندارد جمینی | نماینده تحقیقات عمیق جمینی |
|---|---|---|
| تأخیر | ثانیهها | دقیقه (غیرهمزمان/پسزمینه) |
| فرآیند | تولید -> خروجی | برنامهریزی -> جستجو -> خواندن -> تکرار -> خروجی |
| خروجی | متن مکالمه، کد، خلاصههای کوتاه | گزارشهای دقیق، تحلیلهای طولانی، جداول مقایسهای |
| بهترین برای | چتباتها، استخراج، نویسندگی خلاق | تحلیل بازار، بررسیهای لازم، بررسی ادبیات، محوطهسازی رقابتی |
موجودی و قیمتگذاری
- دسترسی: با استفاده از Interactions API در Google AI Studio و Gemini API قابل دسترسی است.
- قیمت: برای اطلاع از قیمتها و جزئیات بیشتر به صفحه قیمتها مراجعه کنید.
ملاحظات ایمنی
دادن دسترسی به وب و فایلهای خصوصی شما به یک نماینده، مستلزم بررسی دقیق خطرات ایمنی است.
- تزریق سریع با استفاده از فایلها: عامل، محتوای فایلهایی را که شما ارائه میدهید میخواند. اطمینان حاصل کنید که اسناد آپلود شده (PDFها، فایلهای متنی) از منابع معتبری آمدهاند. یک فایل مخرب میتواند حاوی متن پنهانی باشد که برای دستکاری خروجی عامل طراحی شده است.
- خطرات محتوای وب: عامل در وب عمومی جستجو میکند. در حالی که ما فیلترهای ایمنی قوی را پیادهسازی میکنیم، این خطر وجود دارد که عامل با صفحات وب مخرب مواجه شده و آنها را پردازش کند. توصیه میکنیم برای تأیید منابع
citationsارائه شده در پاسخ را بررسی کنید. - استخراج اطلاعات: اگر به مامور اجازه مرور وب را میدهید، هنگام درخواست خلاصهسازی دادههای حساس داخلی از او احتیاط کنید.
بهترین شیوهها
- درخواست برای موارد ناشناخته: به نماینده آموزش دهید که چگونه با دادههای از دست رفته برخورد کند. برای مثال، عبارت «اگر ارقام خاص برای سال ۲۰۲۵ در دسترس نیست، صریحاً بیان کنید که آنها پیشبینی هستند یا در دسترس نیستند و نه تخمین» را به درخواست خود اضافه کنید.
- زمینه را فراهم کنید: با ارائه اطلاعات پیشزمینه یا محدودیتها بهطور مستقیم در فرم ورودی، تحقیقات عامل را زمینهسازی کنید.
- ورودیهای چندوجهی عامل تحقیقات عمیق از ورودیهای چندوجهی پشتیبانی میکند. با احتیاط استفاده کنید، زیرا این امر هزینهها را افزایش میدهد و خطر سرریز پنجره زمینه را به همراه دارد.
محدودیتها
- وضعیت بتا : رابط برنامهنویسی کاربردی تعاملات (Interactions API) در مرحله بتای عمومی است. ویژگیها و طرحوارهها ممکن است تغییر کنند.
- ابزارهای سفارشی: در حال حاضر نمیتوانید ابزارهای فراخوانی تابع سفارشی یا سرورهای MCP (پروتکل زمینه مدل) از راه دور را به عامل Deep Research ارائه دهید.
- خروجی ساختاریافته و تأیید طرح: عامل تحقیقات عمیق در حال حاضر از برنامهریزی تأیید شده توسط انسان یا خروجیهای ساختاریافته پشتیبانی نمیکند.
- حداکثر زمان تحقیق: عامل تحقیقات عمیق حداکثر ۶۰ دقیقه زمان تحقیق دارد. اکثر وظایف باید ظرف ۲۰ دقیقه انجام شوند.
- الزام ذخیره: اجرای عامل با استفاده از
background=Trueنیاز بهstore=Trueدارد. - جستجوی گوگل: جستجوی گوگل به طور پیشفرض فعال است و محدودیتهای خاصی برای نتایج مبتنی بر آن اعمال میشود.
- ورودیهای صدا: ورودیهای صدا پشتیبانی نمیشوند.
قدم بعدی چیست؟
- درباره API تعاملات بیشتر بدانید.
- درباره مدل Gemini 3 Pro که این عامل را پشتیبانی میکند، بخوانید.
- یاد بگیرید که چگونه با استفاده از ابزار جستجوی فایل، از دادههای خود استفاده کنید.