---
name: gemini-deep-research
source: https://app.decimal.ai/s/gemini-deep-research@1/SKILL.md
source_sha256: e691036036ad
---

# 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](https://aistudio.google.com/apikey))
- 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.

```bash
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:**
```bash
python3 <this-skill-directory>/scripts/deep_research.py \
  --query "Current state of quantum error correction techniques" \
  --stream --output-dir ./reports
```

**Custom output format:**
```bash
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