Gemini 3 Pro ist da. Kostenlos in Google AI Studio ausprobieren

Diese Seite wurde von der Cloud Translation API übersetzt.

Gemini Deep Research Agent

Der Gemini Deep Research-Agent plant, führt aus und fasst mehrstufige Rechercheaufgaben selbstständig zusammen. Die Funktion basiert auf Gemini 3 Pro und kann komplexe Informationen aus dem Web und Ihren eigenen Daten zusammenführen, um detaillierte Berichte mit Quellenangaben zu erstellen.

Rechercheaufgaben erfordern iteratives Suchen und Lesen und können mehrere Minuten dauern. Sie müssen die Ausführung im Hintergrund verwenden (background=true festlegen), um den Agenten asynchron auszuführen und die Ergebnisse abzurufen. Weitere Informationen finden Sie unter Lang andauernde Aufgaben verarbeiten.

Das folgende Beispiel zeigt, wie Sie eine Rechercheaufgabe im Hintergrund starten und nach Ergebnissen suchen.

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"

Recherche mit eigenen Daten durchführen

Deep Research hat Zugriff auf eine Vielzahl von Tools. Standardmäßig hat der Agent über die Tools google_search und url_context Zugriff auf Informationen im öffentlichen Internet. Sie müssen diese Tools nicht standardmäßig angeben. Wenn Sie dem Agenten jedoch zusätzlich Zugriff auf Ihre eigenen Daten gewähren möchten, indem Sie das Tool File Search (Dateisuche) verwenden, müssen Sie es wie im folgenden Beispiel hinzufügen.

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

Steuerbarkeit und Formatierung

Sie können die Ausgabe des Agents steuern, indem Sie in Ihrem Prompt bestimmte Formatierungsanweisungen angeben. So können Sie Berichte in bestimmte Abschnitte und Unterabschnitte unterteilen, Datentabellen einfügen oder den Stil für verschiedene Zielgruppen anpassen (z.B. „technisch“, „offiziell“, „informell“).

Definieren Sie das gewünschte Ausgabeformat explizit in Ihrem Eingabetext.

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

Umgang mit lang andauernden Aufgaben

Deep Research ist ein mehrstufiger Prozess, der Planung, Suche, Lesen und Schreiben umfasst. Dieser Zyklus überschreitet in der Regel die Standard-Timeout-Limits für synchrone API-Aufrufe.

Für die Verwendung von background=True sind Agents erforderlich. Die API gibt sofort ein partielles Interaction-Objekt zurück. Mit dem Attribut id können Sie eine Interaktion für das Polling abrufen. Der Interaktionsstatus ändert sich von in_progress zu completed oder failed.

Streaming

Deep Research unterstützt Streaming, um Echtzeit-Updates zum Fortschritt der Recherche zu erhalten. Sie müssen stream=True und background=True festlegen.

Das folgende Beispiel zeigt, wie Sie eine Rechercheaufgabe starten und den Stream verarbeiten. Wichtig ist, dass gezeigt wird, wie die interaction_id aus dem interaction.start-Ereignis erfasst wird. Sie benötigen diese ID, um den Stream fortzusetzen, wenn es zu einer Netzwerkunterbrechung kommt. Mit diesem Code wird auch eine event_id-Variable eingeführt, mit der Sie die Verbindung an dem Punkt wiederherstellen können, an dem sie unterbrochen wurde.

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.

Verbindung zum Stream wird wiederhergestellt

Bei zeitaufwendigen Rechercheaufgaben kann es zu Netzwerkunterbrechungen kommen. Um dies zu beheben, sollte Ihre Anwendung Verbindungsfehler abfangen und den Stream mit client.interactions.get() fortsetzen.

Sie müssen zwei Werte angeben, um fortzufahren:

Interaktions-ID:Wird aus dem interaction.start-Ereignis im ursprünglichen Stream abgerufen.
ID des letzten Ereignisses:Die ID des letzten erfolgreich verarbeiteten Ereignisses. Dadurch wird der Server angewiesen, Ereignisse nach diesem bestimmten Punkt wieder zu senden. Wenn nicht angegeben, wird der Anfang des Streams zurückgegeben.

Die folgenden Beispiele zeigen ein robustes Muster: Es wird versucht, die erste create-Anfrage zu streamen, und es wird auf eine get-Schleife zurückgegriffen, wenn die Verbindung unterbrochen wird.

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"

Folgefragen und Interaktionen

Sie können die Unterhaltung fortsetzen, nachdem der Agent den endgültigen Bericht zurückgegeben hat, indem Sie previous_interaction_id verwenden. So können Sie bestimmte Abschnitte der Recherche zusammenfassen, erläutern oder näher ausführen lassen, ohne die gesamte Aufgabe neu zu starten.

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

Wann sollte der Gemini Deep Research-Agent verwendet werden?

Deep Research ist ein Agent, nicht nur ein Modell. Sie eignet sich am besten für Arbeitslasten, die einen „Analyst-in-a-Box“-Ansatz erfordern, anstatt Chat mit geringer Latenz.

Funktion	Standard-Gemini-Modelle	Gemini Deep Research Agent
Latenz	Sekunden	Minuten (asynchron/im Hintergrund)
Ablauf	Generieren -> Ausgabe	Planen –> Suchen –> Lesen –> Wiederholen –> Ausgeben
Ausgabe	Konversationstext, Code, kurze Zusammenfassungen	Detaillierte Berichte, ausführliche Analysen, Vergleichstabellen
Optimal für	Chatbots, Extraktion, kreatives Schreiben	Marktanalyse, Due Diligence, Literaturübersichten, Wettbewerbsanalyse

Verfügbarkeit und Preisgestaltung

Verfügbarkeit:Über die Interactions API in Google AI Studio und die Gemini API verfügbar.
Preise:Die genauen Preise und weitere Informationen finden Sie auf der Seite „Preise“.

Sicherheitsaspekte

Wenn Sie einem Agent Zugriff auf das Web und Ihre privaten Dateien gewähren, müssen Sie Sicherheitsrisiken sorgfältig abwägen.

Prompt-Injection über Dateien:Der Agent liest den Inhalt der von Ihnen bereitgestellten Dateien. Achten Sie darauf, dass hochgeladene Dokumente (PDFs, Textdateien) aus vertrauenswürdigen Quellen stammen. Eine schädliche Datei kann verborgenen Text enthalten, der die Ausgabe des Agents manipulieren soll.
Risiken bei Webinhalten:Der Agent durchsucht das öffentliche Web. Wir implementieren zwar robuste Sicherheitsfilter, es besteht jedoch das Risiko, dass der Agent auf schädliche Webseiten stößt und diese verarbeitet. Wir empfehlen, die in der Antwort bereitgestellten citations zu prüfen, um die Quellen zu überprüfen.
Exfiltration:Seien Sie vorsichtig, wenn Sie den Agent bitten, vertrauliche interne Daten zusammenzufassen, und ihm gleichzeitig erlauben, im Web zu suchen.

Best Practices

Aufforderung bei Unbekannten:Weisen Sie den Agent an, wie er mit fehlenden Daten umgehen soll. Fügen Sie Ihrem Prompt beispielsweise „Wenn keine konkreten Zahlen für 2025 verfügbar sind, geben Sie explizit an, dass es sich um Schätzungen oder nicht verfügbare Daten handelt, anstatt sie zu schätzen“ hinzu.
Kontext bereitstellen:Geben Sie Hintergrundinformationen oder Einschränkungen direkt im Eingabeaufforderung an, um die Recherche des Agents zu fundieren.
Multimodale Eingaben: Der Deep Research-Agent unterstützt multimodale Eingaben. Mit Vorsicht verwenden, da dies die Kosten erhöht und das Risiko eines Kontextfensterüberlaufs birgt.

Beschränkungen

Betastatus: Die Interactions API befindet sich in der öffentlichen Betaphase. Funktionen und Schemas können sich ändern.
Benutzerdefinierte Tools:Derzeit können Sie dem Deep Research-Agent keine benutzerdefinierten Tools für Funktionsaufrufe oder Remote-MCP-Server (Model Context Protocol) zur Verfügung stellen.
Strukturierte Ausgabe und Genehmigung von Plänen:Der Deep Research Agent unterstützt derzeit keine von Menschen genehmigten Pläne oder strukturierten Ausgaben.
Maximale Recherchezeit:Der Deep Research-Agent hat eine maximale Recherchezeit von 60 Minuten. Die meisten Aufgaben sollten innerhalb von 20 Minuten abgeschlossen sein.
Store-Anforderung:Für die Agent-Ausführung mit background=True ist store=True erforderlich.
Google Suche:Die Google Suche ist standardmäßig aktiviert und für die fundierten Ergebnisse gelten bestimmte Einschränkungen.
Audioeingaben:Audioeingaben werden nicht unterstützt.

Nächste Schritte

Weitere Informationen zur Interactions API
Informationen zum Gemini 3 Pro-Modell, auf dem dieser Agent basiert.
Informationen zur Verwendung Ihrer eigenen Daten mit dem Tool „Dateisuche“