Agjent i Kërkimeve të Thellë Gemini

Agjenti i Kërkimeve të Thellë Gemini planifikon, ekzekuton dhe sintetizon në mënyrë autonome detyra kërkimore me shumë hapa. I mundësuar nga Gemini 3 Pro, ai lundron në peizazhe komplekse informacioni duke përdorur kërkimin në internet dhe të dhënat tuaja për të prodhuar raporte të detajuara dhe të cituara.

Detyrat kërkimore përfshijnë kërkim dhe lexim përsëritës dhe mund të zgjasin disa minuta për t'u përfunduar. Duhet të përdorni ekzekutimin në sfond (set background=true ) për të ekzekutuar agjentin në mënyrë asinkrone dhe për të kërkuar rezultate. Shihni Trajtimi i detyrave të gjata për më shumë detaje.

Shembulli i mëposhtëm tregon se si të filloni një detyrë kërkimore në sfond dhe të bëni një sondazh për rezultatet.

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

PUSHTIM 

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

Hulumtoni me të dhënat tuaja

Deep Research ka qasje në një sërë mjetesh. Si parazgjedhje, agjenti ka qasje në informacion në internetin publik duke përdorur mjetin google_search dhe url_context . Nuk keni nevojë t'i specifikoni këto mjete si parazgjedhje. Megjithatë, nëse dëshironi gjithashtu t'i jepni agjentit qasje në të dhënat tuaja duke përdorur mjetin File Search, do t'ju duhet ta shtoni atë siç tregohet në shembullin e mëposhtëm.

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

PUSHTIM 

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

Drejtueshmëria dhe formatimi

Mund ta drejtoni rezultatin e agjentit duke dhënë udhëzime specifike formatimi në njoftimin tuaj. Kjo ju lejon të strukturoni raportet në seksione dhe nënseksione specifike, të përfshini tabela të dhënash ose të përshtatni tonin për audienca të ndryshme (p.sh., "teknik", "ekzekutiv", "i rastësishëm").

Përcaktoni formatin e dëshiruar të daljes në mënyrë të qartë në tekstin tuaj të hyrjes.

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

PUSHTIM 

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

Trajtimi i detyrave afatgjata

Kërkimi i Thellë është një proces me shumë hapa që përfshin planifikimin, kërkimin, leximin dhe shkrimin. Ky cikël zakonisht tejkalon limitet standarde të kohës së skadimit të thirrjeve sinkrone të API-t.

Agjentët duhet të përdorin background=True . API kthen menjëherë një objekt të pjesshëm Interaction . Mund të përdorni vetinë id për të marrë një ndërveprim për anketim. Gjendja e ndërveprimit do të kalojë nga in_progress në completed ose failed .

Transmetim

Kërkimi i Thellë mbështet transmetimin në kohë reale për të marrë përditësime mbi progresin e kërkimit. Duhet të vendosni stream=True dhe background=True .

Shembulli i mëposhtëm tregon se si të filloni një detyrë kërkimore dhe të përpunoni transmetimin. Më e rëndësishmja, ai demonstron se si të gjurmoni interaction_id nga ngjarja interaction.start . Do t'ju duhet ky ID për të rifilluar transmetimin nëse ndodh një ndërprerje e rrjetit. Ky kod gjithashtu prezanton një variabël event_id e cila ju lejon të rifilloni nga pika specifike ku jeni shkëputur.

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

PUSHTIM 

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.

Duke u rilidhur me transmetimin

Ndërprerjet e rrjetit mund të ndodhin gjatë detyrave të gjata kërkimore. Për ta trajtuar këtë me efikasitet, aplikacioni juaj duhet të kapë gabimet e lidhjes dhe të rifillojë transmetimin duke përdorur client.interactions.get() .

Duhet të jepni dy vlera për të rifilluar:

  1. ID e ndërveprimit: E fituar nga ngjarja interaction.start në rrjedhën fillestare.
  2. ID e Ngjarjes së Fundit: ID-ja e ngjarjes së fundit të përpunuar me sukses. Kjo i tregon serverit të rifillojë dërgimin e ngjarjeve pas asaj pike specifike. Nëse nuk jepet, do të merrni fillimin e transmetimit.

Shembujt e mëposhtëm demonstrojnë një model elastik: përpjekja për të transmetuar kërkesën fillestare create dhe kthimi në një cikël get nëse lidhja ndërpritet.

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

PUSHTIM 

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

Pyetje dhe ndërveprime pasuese

Mund ta vazhdoni bisedën pasi agjenti të kthejë raportin përfundimtar duke përdorur previous_interaction_id . Kjo ju lejon të kërkoni sqarime, përmbledhje ose hollësi mbi pjesë specifike të hulumtimit pa e rinisur të gjithë detyrën.

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

PUSHTIM 

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

Kur duhet të përdoret Agjenti i Kërkimeve të Thellë Gemini

Kërkimi i Thellë është një agjent , jo vetëm një model. Është më i përshtatshmi për ngarkesat e punës që kërkojnë një qasje "analist-në-kuti" në vend të bisedave me vonesë të ulët.

Karakteristikë Modelet Standarde të Binjakëve Agjent i Kërkimeve të Thellë Gemini
Latencia Sekonda Minuta (Asinkron/Sfond)
Procesi Gjenero -> Dalje Plan -> Kërko -> Lexo -> Itero -> Dalje
Prodhimi Tekst bisedor, kod, përmbledhje të shkurtra Raporte të hollësishme, analiza të gjata, tabela krahasuese
Më e mira për Chatbot, nxjerrje, shkrim krijues Analiza e tregut, kujdesi i duhur, rishikimet e literaturës, peizazhi konkurrues

Disponueshmëria dhe çmimet

  • Disponueshmëria: E aksesueshme duke përdorur Interactions API në Google AI Studio dhe Gemini API.
  • Çmimet: Shihni faqen e Çmimeve për tarifa dhe detaje specifike.

Konsideratat e sigurisë

Dhënia e aksesit në internet dhe në skedarët tuaj privatë një agjenti kërkon shqyrtim të kujdesshëm të rreziqeve të sigurisë.

  • Injeksion i menjëhershëm duke përdorur skedarë: Agjenti lexon përmbajtjen e skedarëve që jepni. Sigurohuni që dokumentet e ngarkuara (PDF, skedarë teksti) vijnë nga burime të besueshme. Një skedar keqdashës mund të përmbajë tekst të fshehur të projektuar për të manipuluar rezultatin e agjentit.
  • Rreziqet e përmbajtjes së uebit: Agjenti kërkon në uebin publik. Ndërsa ne zbatojmë filtra të fuqishëm sigurie, ekziston rreziku që agjenti të hasë dhe të përpunojë faqe uebi me qëllim të keq. Ne rekomandojmë të rishikoni citations e dhëna në përgjigje për të verifikuar burimet.
  • Ekfiltrimi: Kini kujdes kur i kërkoni agjentit të përmbledhë të dhëna të brendshme të ndjeshme nëse po e lejoni edhe atë të shfletojë uebin.

Praktikat më të mira

  • Njoftim për të panjohurat: Udhëzoni agjentin se si të trajtojë të dhënat që mungojnë. Për shembull, shtoni në njoftimin tuaj "Nëse shifra specifike për vitin 2025 nuk janë të disponueshme, deklaroni qartë se ato janë parashikime ose të padisponueshme në vend të vlerësimeve" .
  • Jepni kontekst: Bazoni kërkimin e agjentit duke dhënë informacion mbi sfondin ose kufizimet direkt në kërkesën e të dhënave hyrëse.
  • Hyrjet multimodale. Agjenti i Kërkimit të Thellë mbështet hyrjet multimodale. Përdoreni me kujdes, pasi kjo rrit kostot dhe rrezikon tejmbushjen e dritares së kontekstit.

Kufizime

  • Statusi Beta : API-ja e Ndërveprimeve është në beta publike. Karakteristikat dhe skemat mund të ndryshojnë.
  • Mjete të personalizuara: Aktualisht nuk mund t'i ofroni agjentit të Deep Research mjete të personalizuara të Thirrjes së Funksioneve ose serverë të largët MCP (Model Context Protocol).
  • Prodhimi i strukturuar dhe miratimi i planit: Agjenti i Kërkimit të Thellë aktualisht nuk mbështet planifikimin ose rezultatet e strukturuara të miratuara nga njerëzit.
  • Koha maksimale e kërkimit: Agjenti i Kërkimit të Thellë ka një kohë maksimale kërkimi prej 60 minutash. Shumica e detyrave duhet të përfundojnë brenda 20 minutash.
  • Kërkesa për ruajtje: Ekzekutimi i agjentit duke përdorur background=True kërkon store=True .
  • Kërkimi në Google: Kërkimi në Google është aktivizuar si parazgjedhje dhe zbatohen kufizime specifike për rezultatet e bazuara.
  • Hyrjet audio: Hyrjet audio nuk mbështeten.

Çfarë vjen më pas