Gemini Deep Research Agent는 장기 리서치 태스크를 자율적으로 계획·검색·합성해 인용이 포함된 상세 보고서를 생성한다. Google AI Studio에서 버튼 클릭으로 쓸 수도 있지만, API를 통해 직접 프로덕션 워크플로에 통합할 수 있다.

Deep Research는 Interactions API(generate_content가 아님)로만 사용 가능하며, 백그라운드에서 비동기로 실행된다.

두 가지 모델 선택

설정

pip install google-genai
export GEMINI_API_KEY="your-api-key"
# API 키 생성: https://aistudio.google.com/apikey

첫 번째 딥 리서치 태스크

import time
from google import genai

client = genai.Client()

# background=True로 비동기 실행
interaction = client.interactions.create(
    input="Google TPU의 역사를 조사하라.",
    agent="deep-research-preview-04-2026",
    background=True,
)

# 완료 폴링
while True:
    interaction = client.interactions.get(interaction.id)
    if interaction.status == "completed":
        print(interaction.outputs[-1].text)
        break
    elif interaction.status == "failed":
        print(f"실패: {interaction.error}")
        break
    time.sleep(10)

협업 플래닝

보고서 생성 전에 리서치 계획을 검토하고 정제할 수 있다.

1단계: 계획 요청

plan = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="Google TPU와 경쟁사 하드웨어를 비교 조사하라.",
    agent_config={"type": "deep-research", "collaborative_planning": True},
    background=True,
)

while (result := client.interactions.get(id=plan.id)).status != "completed":
    time.sleep(5)
print(result.outputs[-1].text)

2단계: 계획 정제

refined = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="전력 효율 비교 섹션을 추가하라.",
    agent_config={"type": "deep-research", "collaborative_planning": True},
    previous_interaction_id=plan.id,
    background=True,
)

3단계: 실행 승인

# collaborative_planning=False로 명시해야 실행 시작
# "진행하세요" 같은 텍스트만으로는 실행되지 않음
report = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="계획이 좋습니다!",
    agent_config={"type": "deep-research", "collaborative_planning": False},
    previous_interaction_id=refined.id,
    background=True,
)

네이티브 차트·인포그래픽

import base64

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="글로벌 반도체 시장 트렌드를 분석하라. 시장 점유율 변화 차트를 포함하라.",
    agent_config={"type": "deep-research", "visualization": "auto"},
    background=True,
)

while (result := client.interactions.get(id=interaction.id)).status != "completed":
    time.sleep(5)

for output in result.outputs:
    if output.type == "text":
        print(output.text)
    elif output.type == "image" and output.data:
        image_bytes = base64.b64decode(output.data)
        # 파일로 저장하거나 Jupyter에서 display(Image(data=image_bytes))

팁: visualization="auto"를 설정해도 명시적으로 요청해야 최상의 결과.

MCP 서버 연결

외부 도구를 에이전트에 연결할 수 있다:

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="최근 지정학적 사건이 USD 금리에 미친 영향을 조사하라.",
    tools=[
        {
            "type": "mcp_server",
            "name": "Finance Data Provider",
            "url": "https://finance.example.com/mcp",
            "headers": {"Authorization": "Bearer my-token"},
        }
    ],
    background=True,
)

MCP 서버는 인증 없음, 베어러 토큰, OAuth를 모두 지원한다.

기본 제공 도구 설정

특정 도구만 허용하려면 tools 파라미터를 명시한다.

멀티모달 리서치 그라운딩

이미지, PDF, 오디오를 리서치 컨텍스트로 전달할 수 있다:

interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input=[
        {"type": "text", "text": "이 논문의 영향을 조사하라."},
        {"type": "document", "uri": "https://arxiv.org/pdf/1706.03762",
         "mime_type": "application/pdf"},
    ],
    background=True,
)

실시간 스트리밍

stream = client.interactions.create(
    input="AI 칩 시장 트렌드를 조사하라.",
    agent="deep-research-preview-04-2026",
    background=True,
    stream=True,
    agent_config={
        "type": "deep-research",
        "thinking_summaries": "auto",  # 중간 추론 단계 노출
        "visualization": "auto",
    },
)

for chunk in stream:
    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"\n💭 {chunk.delta.content.text}")

관련 문서

• gemini — Gemini 모델 및 서비스 생태계 전반
• deep-research-max — Deep Research Max 독립 제품 가이드
• gemini-3-1-flash-tts-tutorial-voice-app — Gemini API로 음성 앱 만들기

참고 자료

• How to use Deep Research with the Gemini API — Philipp Schmid (2026-04-29)
• Deep Research 공식 문서 — Google AI
• Interactions API 문서 — Google AI