Gemini Deep Research

Google Gemini's Deep Research Agent autonomously breaks down complex queries, searches the web systematically, and produces structured markdown reports with citations. It handles the kind of multi-source synthesis that would take a human hours of browsing.

Prerequisites

• GEMINI_API_KEY environment variable must be set (obtain from Google AI Studio)
• Python 3.8+ with the requests library installed
• Requires a direct Gemini API key — OAuth tokens are not supported

How to Run the Script

The script is at scripts/deep_research.py relative to this skill's directory (i.e., the directory containing this SKILL.md). Resolve the full path from the skill's location before running.

python3 <this-skill-directory>/scripts/deep_research.py \
  --query "<research query>" \
  --stream \
  --output-dir ./reports

Key flags

Flag	Purpose	Default
--query	(required) The research question	—
--stream	Print progress updates while waiting	off
--output-dir	Where to save the report files	current dir
--format	Custom output structure (see example below)	free-form
--file-search-store	Gemini file-search store name	none
--api-key	Override GEMINI_API_KEY env var	env var

Before running

1. Check for GEMINI_API_KEY: Run echo $GEMINI_API_KEY to see if it's set. If empty, ask the user whether they'd like to provide a Gemini API key (they can get one from https://aistudio.google.com/apikey). If the user provides one, pass it via --api-key. If the user declines, do not use this skill — fall back to other research approaches and let the user know why.
2. Ensure requests is installed: python3 -c "import requests". If missing, install it: pip3 install requests.

Example commands

Basic research:

python3 <this-skill-directory>/scripts/deep_research.py \
  --query "Current state of quantum error correction techniques" \
  --stream --output-dir ./reports

Custom output format:

python3 <this-skill-directory>/scripts/deep_research.py \
  --query "Competitive landscape of EV batteries" \
  --format "1. Executive Summary\n2. Key Players (data table)\n3. Technology Comparison\n4. Supply Chain Risks" \
  --stream --output-dir ./reports

Output

The script produces two timestamped files in the output directory:

• deep-research-YYYY-MM-DD-HH-MM-SS.md — the final markdown report
• deep-research-YYYY-MM-DD-HH-MM-SS.json — full interaction metadata

The report is also printed to stdout so you can capture it directly.

Execution Notes

• This is a long-running task — it typically takes 2–10 minutes depending on query complexity. Use --stream so the user can see progress.
• Always run with a reasonable timeout (at least 600000ms / 10 minutes) when using the Bash tool.
• After the script finishes, read and present the generated .md report to the user. Summarize key findings and point them to the full report file.

API Details

• Endpoint: https://generativelanguage.googleapis.com/v1beta/interactions
• Agent model: deep-research-pro-preview-12-2025
• Auth: x-goog-api-key header