7.5 KiB
7.5 KiB
Gemini Deep Research Skill
Execute autonomous multi-step research tasks using Google's Gemini Deep Research Agent. Unlike standard LLM queries that respond in seconds, Deep Research is an "analyst-in-a-box" that plans, searches, reads, and synthesizes information into comprehensive, cited reports.
Overview
The Deep Research Agent (deep-research-pro-preview-12-2025) powered by Gemini 3 Pro:
- Plans research strategy based on your query
- Searches the web and analyzes sources
- Reads and extracts relevant information
- Iterates through multiple search/read cycles
- Outputs detailed, cited reports
This process takes 2-10 minutes but produces thorough analysis that would take a human researcher hours.
Installation
# Navigate to skill directory
cd skills/deep-research
# Install dependencies
pip install -r requirements.txt
# Set up API key
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
Getting a Gemini API Key
- Go to Google AI Studio
- Click "Get API key"
- Create a new key or use an existing one
- Copy the key to your
.envfile
Quick Start
# Basic research query
python3 scripts/research.py --query "Research the competitive landscape of cloud providers in 2024"
# Stream progress in real-time
python3 scripts/research.py --query "Compare React, Vue, and Angular frameworks" --stream
# Get structured JSON output
python3 scripts/research.py --query "Analyze the EV market" --json
Commands
--query / -q
Start a new research task.
# Basic query
python3 scripts/research.py -q "Research the history of containerization"
# With output format specification
python3 scripts/research.py -q "Compare database solutions" \
--format "1. Executive Summary\n2. Comparison Table\n3. Pros/Cons\n4. Recommendations"
# Start without waiting for results
python3 scripts/research.py -q "Research topic" --no-wait
--stream
Stream research progress in real-time. Shows thinking steps and builds the report as it's generated.
python3 scripts/research.py -q "Analyze market trends" --stream
--status / -s
Check the status of a running research task.
python3 scripts/research.py --status abc123xyz
--wait / -w
Wait for a specific research task to complete.
python3 scripts/research.py --wait abc123xyz
--continue
Continue a conversation from previous research. Useful for follow-up questions.
# First, run initial research
python3 scripts/research.py -q "Research Kubernetes architecture"
# Output: Interaction ID: abc123xyz
# Then ask follow-up
python3 scripts/research.py -q "Elaborate on the networking section" --continue abc123xyz
--list / -l
List recent research tasks from local history.
python3 scripts/research.py --list
python3 scripts/research.py --list --limit 20
Output Options
| Flag | Description |
|---|---|
| (default) | Human-readable markdown report |
--json / -j |
Structured JSON output |
--raw / -r |
Raw API response |
Configuration
Environment Variables
| Variable | Default | Description |
|---|---|---|
GEMINI_API_KEY |
(required) | Your Google Gemini API key |
DEEP_RESEARCH_TIMEOUT |
600 |
Max wait time in seconds |
DEEP_RESEARCH_POLL_INTERVAL |
10 |
Seconds between status polls |
DEEP_RESEARCH_CACHE_DIR |
~/.cache/deep-research |
Local history cache directory |
.env File
GEMINI_API_KEY=your-api-key-here
DEEP_RESEARCH_TIMEOUT=600
DEEP_RESEARCH_POLL_INTERVAL=10
Cost & Performance
Estimated Costs
Deep Research uses a pay-as-you-go model based on token usage:
| Task Type | Search Queries | Input Tokens | Output Tokens | Estimated Cost |
|---|---|---|---|---|
| Standard | ~80 | ~250k (50-70% cached) | ~60k | $2-3 |
| Complex | ~160 | ~900k (50-70% cached) | ~80k | $3-5 |
Time Expectations
- Simple queries: 2-5 minutes
- Complex analysis: 5-10 minutes
- Maximum: 60 minutes (API limit)
Use Cases
Market Analysis
python3 scripts/research.py -q "Analyze the competitive landscape of \
EV battery manufacturers, including market share, technology, and supply chain"
Technical Research
python3 scripts/research.py -q "Compare Rust vs Go for building \
high-performance backend services" \
--format "1. Performance Benchmarks\n2. Memory Safety\n3. Ecosystem\n4. Learning Curve"
Due Diligence
python3 scripts/research.py -q "Research Company XYZ: recent news, \
financial performance, leadership changes, and market position"
Literature Review
python3 scripts/research.py -q "Review recent developments in \
large language model efficiency and optimization techniques"
Error Handling
| Error | Cause | Solution |
|---|---|---|
GEMINI_API_KEY not set |
Missing API key | Set in .env or environment |
API error 429 |
Rate limited | Wait and retry |
Research timed out |
Task took too long | Simplify query or increase timeout |
Failed to parse result |
Unexpected response | Use --raw to see actual output |
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (API, config, timeout) |
| 130 | Cancelled by user (Ctrl+C) |
Architecture
┌─────────────────┐ ┌──────────────────────┐
│ CLI Script │──────│ DeepResearchClient │
│ (research.py) │ │ │
└─────────────────┘ └──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Gemini Deep │
│ Research API │
│ │
│ POST /interactions │
│ GET /interactions │
└──────────────────────┘
│
▼
┌──────────────────────┐
│ HistoryManager │
│ (~/.cache/deep- │
│ research/) │
└──────────────────────┘
Safety & Privacy
- Read-only: This skill only reads/researches; no file modifications
- No secrets in queries: Avoid including sensitive data in research queries
- Source verification: Always verify citations in the output
- Cost awareness: Each task costs $2-5; be mindful of usage
Limitations
- No custom tools: Cannot use MCP or function calling
- No structured output enforcement: JSON formatting relies on prompt engineering
- Web-only research: Cannot access private/authenticated sources
- 60-minute max: Very complex tasks may time out