Gemini Deep Research 에이전트

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)

자바스크립트

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"

내 데이터를 사용해 조사

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

자바스크립트

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

조향성 및 서식

프롬프트에 구체적인 서식 지정 안내를 제공하여 에이전트의 출력을 조정할 수 있습니다. 이를 통해 보고서를 특정 섹션과 하위 섹션으로 구성하고, 데이터 표를 포함하거나, 다양한 잠재고객에 맞게 어조를 조정할 수 있습니다 (예: '기술', '경영진', '캐주얼')을 지정할 수 있습니다.

입력 텍스트에 원하는 출력 형식을 명시적으로 정의합니다.

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
)

자바스크립트

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

장기 실행 작업 처리

Deep Research는 계획, 검색, 읽기, 쓰기를 포함하는 다단계 프로세스입니다. 이 주기는 일반적으로 동기 API 호출의 표준 제한 시간을 초과합니다.

background=True를 사용하려면 에이전트가 필요합니다. API는 부분 Interaction 객체를 즉시 반환합니다. id 속성을 사용하여 폴링을 위한 상호작용을 가져올 수 있습니다. 상호작용 상태가 in_progress에서 completed 또는 failed로 전환됩니다.

스트리밍

Deep Research는 스트리밍을 지원하여 연구 진행 상황에 관한 실시간 업데이트를 수신합니다. stream=True 및 background=True를 설정해야 합니다.

다음 예에서는 리서치 작업을 시작하고 스트림을 처리하는 방법을 보여줍니다. 특히 interaction.start 이벤트에서 interaction_id를 추적하는 방법을 보여줍니다. 네트워크 중단이 발생한 경우 스트림을 재개하려면 이 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")

자바스크립트

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.

스트림에 다시 연결하는 중

장시간 실행되는 연구 작업 중에 네트워크 중단이 발생할 수 있습니다. 이 문제를 적절하게 처리하려면 애플리케이션이 연결 오류를 포착하고 client.interactions.get()를 사용하여 스트림을 재개해야 합니다.

다시 시작하려면 다음 두 값을 제공해야 합니다.

  1. 상호작용 ID: 초기 스트림의 interaction.start 이벤트에서 획득합니다.
  2. 마지막 이벤트 ID: 마지막으로 성공적으로 처리된 이벤트의 ID입니다. 이렇게 하면 서버가 해당 특정 지점 후에 이벤트를 다시 전송하도록 지시합니다. 제공되지 않으면 스트림의 시작이 반환됩니다.

다음 예에서는 초기 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})")

자바스크립트

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"

후속 질문 및 상호작용

에이전트가 최종 보고서를 반환한 후 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)

자바스크립트

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 에이전트를 사용해야 하는 경우

Deep Research는 모델이 아닌 에이전트입니다. 지연 시간이 짧은 채팅보다는 '분석가-인-어-박스' 접근 방식이 필요한 워크로드에 가장 적합합니다.

기능 표준 Gemini 모델 Gemini Deep Research 에이전트
지연 시간 초 분 (비동기/백그라운드)
절차 생성 -> 출력 계획 -> 검색 -> 읽기 -> 반복 -> 출력
출력 대화형 텍스트, 코드, 짧은 요약 자세한 보고서, 긴 형식 분석, 비교 표
권장 챗봇, 추출, 창의적인 글쓰기 시장 분석, 실사, 문헌 검토, 경쟁 환경

사용 가능 여부 및 가격 책정

  • 사용 가능 여부: Google AI Studio 및 Gemini API의 Interactions API를 사용하여 액세스할 수 있습니다.
  • 가격: 구체적인 요금과 세부정보는 가격 책정 페이지를 참고하세요.

안전 고려사항

에이전트가 웹과 비공개 파일에 액세스하도록 허용하려면 안전 위험을 신중하게 고려해야 합니다.

  • 파일을 사용한 프롬프트 삽입: 에이전트가 제공된 파일의 콘텐츠를 읽습니다. 업로드된 문서 (PDF, 텍스트 파일)가 신뢰할 수 있는 출처에서 제공되었는지 확인합니다. 악성 파일에는 에이전트의 출력을 조작하기 위해 설계된 숨겨진 텍스트가 포함될 수 있습니다.
  • 웹 콘텐츠 위험: 에이전트가 공개 웹을 검색합니다. 강력한 안전 필터를 구현하고 있지만 에이전트가 악성 웹페이지를 접하고 처리할 위험이 있습니다. 소스 확인을 위해 대답에 제공된 citations를 검토하는 것이 좋습니다.
  • 무단 반출: 에이전트가 웹을 탐색하도록 허용하는 경우 민감한 내부 데이터를 요약하도록 요청할 때는 주의해야 합니다.

권장사항

  • 알 수 없는 항목에 대한 프롬프트: 상담사에게 누락된 데이터를 처리하는 방법을 안내합니다. 예를 들어 프롬프트에 '2025년의 구체적인 수치를 사용할 수 없는 경우 추정하지 말고 예측치이거나 사용할 수 없다고 명시하세요'를 추가합니다.
  • 컨텍스트 제공: 입력 프롬프트에 배경 정보나 제약 조건을 직접 제공하여 에이전트의 조사를 그라운딩합니다.
  • 멀티모달 입력 Deep Research Agent는 멀티모달 입력을 지원합니다. 비용이 증가하고 컨텍스트 윈도우 오버플로 위험이 있으므로 신중하게 사용하세요.

제한사항

  • 베타 상태: Interactions API는 공개 베타 버전입니다. 기능과 스키마는 변경될 수 있습니다.
  • 맞춤 도구: 현재 Deep Research 에이전트에 맞춤 함수 호출 도구나 원격 MCP (모델 컨텍스트 프로토콜) 서버를 제공할 수 없습니다.
  • 구조화된 출력 및 계획 승인: 현재 심층 조사 에이전트는 사람이 승인한 계획 또는 구조화된 출력을 지원하지 않습니다.
  • 최대 조사 시간: Deep Research 에이전트의 최대 조사 시간은 60분입니다. 대부분의 작업은 20분 이내에 완료됩니다.
  • 스토어 요구사항: background=True를 사용하는 에이전트 실행에는 store=True가 필요합니다.
  • Google 검색: Google 검색은 기본적으로 사용 설정되며 그라운딩된 결과에는 특정 제한사항이 적용됩니다.
  • 오디오 입력: 오디오 입력은 지원되지 않습니다.

다음 단계

  • Interactions API에 대해 자세히 알아보세요.
  • 이 에이전트를 지원하는 Gemini 3 Pro 모델에 대해 알아보세요.
  • 파일 검색 도구를 사용하여 자체 데이터를 사용하는 방법을 알아보세요.