Gemini Deep Research Temsilcisi

Gemini Deep Research Temsilcisi, çok adımlı araştırma görevlerini bağımsız olarak planlar, yürütür ve sentezler. Gemini 3 Pro tarafından desteklenen bu özellik, web'de arama ve kendi verilerinizi kullanarak karmaşık bilgi ortamlarında gezinir ve ayrıntılı, alıntıları eksiksiz raporlar oluşturur.

Araştırma görevleri, tekrara dayalı arama ve okuma işlemlerini içerir ve tamamlanması birkaç dakika sürebilir. Aracı eşzamansız olarak çalıştırmak ve sonuçları yoklamak için arka planda yürütme'yi (background=true ayarlanmış) kullanmanız gerekir. Daha fazla bilgi için Uzun süren görevleri yönetme başlıklı makaleyi inceleyin.

Aşağıdaki örnekte, araştırma görevini arka planda başlatma ve sonuçları yoklama işlemi gösterilmektedir.

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"

Kendi verilerinizle araştırma yapma

Deep Research, çeşitli araçlara erişebilir. Aracı, varsayılan olarak google_search ve url_context aracını kullanarak herkese açık internetteki bilgilere erişebilir. Bu araçları varsayılan olarak belirtmeniz gerekmez. Ancak Dosya Arama aracını kullanarak temsilciye kendi verilerinize erişim izni vermek istiyorsanız aşağıdaki örnekte gösterildiği gibi eklemeniz gerekir.

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

Yönlendirilebilirlik ve biçimlendirme

İsteminizde belirli biçimlendirme talimatları vererek aracının çıktısını yönlendirebilirsiniz. Bu sayede raporları belirli bölümler ve alt bölümler halinde yapılandırabilir, veri tabloları ekleyebilir veya farklı kitlelere yönelik tonu ayarlayabilirsiniz (ör. "technical", "executive", "casual").

İstediğiniz çıkış biçimini giriş metninizde açıkça tanımlayın.

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

Uzun süreli görevleri işleme

Deep Research, planlama, arama, okuma ve yazma gibi adımları içeren çok aşamalı bir süreçtir. Bu döngü genellikle senkron API çağrılarının standart zaman aşımı sınırlarını aşar.

Temsilcilerin background=True kullanması gerekir. API, hemen kısmi bir Interaction nesnesi döndürür. Anket için etkileşim almak üzere id özelliğini kullanabilirsiniz. Etkileşim durumu in_progress'dan completed veya failed'a geçiş yapar.

Canlı Yayın

Deep Research, araştırma ilerlemesiyle ilgili gerçek zamanlı güncellemeler almak için akışı destekler. stream=True ve background=True öğelerini ayarlamanız gerekir.

Aşağıdaki örnekte, araştırma görevini başlatma ve akışı işleme adımları gösterilmektedir. En önemlisi, interaction_id etkinliğinden interaction.start etkinliğinin nasıl izleneceğini gösterir. Ağda kesinti olursa yayını devam ettirmek için bu kimliğe ihtiyacınız olacaktır. Bu kod, bağlantıyı kestiğiniz noktadan devam etmenizi sağlayan bir event_id değişkeni de sunar.

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.

Yayına yeniden bağlanılıyor

Uzun süren araştırma görevleri sırasında ağ kesintileri yaşanabilir. Bu durumu sorunsuz bir şekilde yönetmek için uygulamanız bağlantı hatalarını yakalamalı ve client.interactions.get() kullanarak akışı devam ettirmelidir.

Devam etmek için iki değer sağlamanız gerekir:

  1. Etkileşim kimliği: İlk akıştaki interaction.start etkinliğinden alınır.
  2. Son Etkinlik Kimliği: Başarıyla işlenen son etkinliğin kimliği. Bu, sunucuya etkinlik göndermeye bu noktadan sonra devam etmesini söyler. Belirtilmezse akışın başlangıcını görürsünüz.

Aşağıdaki örneklerde, ilk create isteğini yayınlamaya çalışıp bağlantı kesilirse get döngüsüne geri dönen esnek bir kalıp gösterilmektedir.

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"

Ek sorular ve etkileşimler

Temsilci nihai raporu döndürdükten sonra previous_interaction_id kullanarak görüşmeye devam edebilirsiniz. Bu sayede, tüm görevi yeniden başlatmadan araştırmanın belirli bölümleriyle ilgili açıklama, özet veya ayrıntı isteyebilirsiniz.

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

Gemini Deep Research Agent'ı ne zaman kullanmalısınız?

Deep Research yalnızca bir model değil, temsilcidir. Düşük gecikmeli sohbet yerine "analist-in-a-box" yaklaşımı gerektiren iş yükleri için en uygun seçenektir.

Özellik Standart Gemini Modelleri Gemini Deep Research Temsilcisi
Gecikme Saniye Dakika (Eşzamansız/Arka Plan)
İşlem Oluştur -> Çıkış Plan -> Search -> Read -> Iterate -> Output
Çıkış Etkileşimli metin, kod, kısa özetler Ayrıntılı raporlar, uzun analizler, karşılaştırmalı tablolar
İdeal kullanım alanları Chatbot'lar, ayıklama, yaratıcı yazma Pazar analizi, durum tespiti, literatür incelemeleri, rekabet ortamı

Kullanılabilirlik ve fiyatlandırma

  • Kullanılabilirlik: Google AI Studio ve Gemini API'deki Interactions API kullanılarak erişilebilir.
  • Fiyatlandırma: Belirli ücretler ve ayrıntılar için fiyatlandırma sayfasına göz atın.

Güvenlikle ilgili olarak göz önünde bulundurulması gerekenler

Bir temsilciye web'e ve özel dosyalarınıza erişim izni vermek için güvenlik risklerini dikkatlice değerlendirmeniz gerekir.

  • Dosyaları kullanarak istem ekleme: Aracı, sağladığınız dosyaların içeriğini okur. Yüklenen dokümanların (PDF'ler, metin dosyaları) güvenilir kaynaklardan geldiğinden emin olun. Kötü amaçlı bir dosya, aracının çıkışını manipüle etmek için tasarlanmış gizli metinler içerebilir.
  • Web içeriği riskleri: Aracı, herkese açık web'de arama yapar. Güçlü güvenlik filtreleri uyguladığımız halde, aracının kötü amaçlı web sayfalarıyla karşılaşma ve bunları işleme riski vardır. Kaynakları doğrulamak için yanıtta citations bilgilerini incelemenizi öneririz.
  • Veri sızdırma: Agent'ın web'e göz atmasına da izin veriyorsanız hassas dahili verileri özetlemesini isterken dikkatli olun.

En iyi uygulamalar

  • Bilinmeyenler için istem: Eksik verilerin nasıl işleneceği konusunda temsilciye talimat verin. Örneğin, isteminize "2025'e ait belirli rakamlar mevcut değilse tahmin etmek yerine bunların tahmin olduğunu veya kullanılamadığını açıkça belirt" ifadesini ekleyin.
  • Bağlam sağlama: Giriş isteminde doğrudan arka plan bilgileri veya kısıtlamalar sağlayarak aracının araştırmasına temel oluşturun.
  • Çok formatlı girişler: Deep Research temsilcisi, çok formatlı girişleri destekler. Maliyetleri artırdığı ve bağlam penceresinin taşmasına neden olabileceği için dikkatli kullanın.

Sınırlamalar

  • Beta durumu: Etkileşimler API'si herkese açık beta sürümündedir. Özellikler ve şemalar değişebilir.
  • Özel araçlar: Şu anda Deep Research aracısına özel işlev çağrısı araçları veya uzaktan MCP (Model Context Protocol) sunucuları sağlayamazsınız.
  • Yapılandırılmış çıkış ve plan onayı: Deep Research Aracısı şu anda insan onaylı planlamayı veya yapılandırılmış çıkışları desteklememektedir.
  • Maksimum araştırma süresi: Deep Research aracısının maksimum araştırma süresi 60 dakikadır. Çoğu görev 20 dakika içinde tamamlanır.
  • Mağaza şartı: background=True kullanılarak aracı yürütme işlemi için store=True gerekir.
  • Google Arama: Google Arama varsayılan olarak etkindir ve temellendirilmiş sonuçlar için belirli kısıtlamalar geçerlidir.
  • Ses girişleri: Ses girişleri desteklenmez.

Sırada ne var?

  • Interactions API hakkında daha fazla bilgi edinin.
  • Bu temsilciye güç veren Gemini 3 Pro modeli hakkında bilgi edinin.
  • Dosya Arama aracını kullanarak kendi verilerinizi nasıl kullanacağınızı öğrenin.