OpenLAIR 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_KEYenvironment variable must be set (obtain from Google AI Studio)- Python 3.8+ with the
requestslibrary 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
- Check for
GEMINI_API_KEY: Runecho $GEMINI_API_KEYto 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. - Ensure
requestsis 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 reportdeep-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
--streamso 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
.mdreport 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-keyheader