home / skills / cnemri / google-genai-skills / deep-research

deep-research skill

safe

This skill enables autonomous multi-step research using the Gemini Deep Research Agent to plan, search, read, and synthesize findings.

npx playbooks add skill cnemri/google-genai-skills --skill deep-research

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

2.4 KB

---
name: deep-research
description: "Perform autonomous, multi-step research using the Gemini Deep Research Agent (Interactions API). Supports web search, file/directory context, and resilient streaming."
---

# Deep Research

Use this skill to conduct deep, autonomous research tasks that require planning, searching, reading, and synthesizing information.

This skill uses the **Gemini Deep Research Agent** (`deep-research-pro-preview-12-2025`) via the Interactions API.

## Prerequisites

*   `GOOGLE_API_KEY`: Required for accessing the Interactions API (currently in Preview via AI Studio).
*   `google-genai` SDK v0.3.0+

## Usage

### Basic Research
Start a research task and stream the results to the console.

```bash
uv run skills/deep-research/scripts/research.py "Research the history of RISC-V architecture."
```

### Research with Context (Files or Directories)
Provide local files (PDFs, text) or entire directories for the agent to read and incorporate into its research.

**Direct Upload (Best for specific docs):**
```bash
# Single file
uv run skills/deep-research/scripts/research.py "Analyze this report" --file report.pdf

# Entire directory
uv run skills/deep-research/scripts/research.py "Summarize these meeting notes" --file ./notes/
```

**File Search Store (Best for large corpora):**
Use `--use-file-store` to index files into a searchable store (RAG) instead of uploading them into the context window.

```bash
uv run skills/deep-research/scripts/research.py "Find trends in these 1000 PDFs" --file ./large_corpus/ --use-file-store
```

### Saving the Report
Save the final Markdown report to a file.

```bash
uv run skills/deep-research/scripts/research.py "Competitive landscape of EV batteries" --output report.md
```

### Continuing Research (Follow-up)
Ask follow-up questions to an existing research session using the `Interaction ID` (displayed at the start of the previous run).

```bash
uv run skills/deep-research/scripts/research.py "Elaborate on the second point about lithium supply." --follow-up "INTERACTION_ID_HERE"
```

## References
*   [Online Documentation](references/online_docs.md)

## How it Works
1.  **Planning**: The agent breaks down your prompt into steps.
2.  **Execution**: It autonomously searches the web and reads your provided files.
3.  **Resilience**: The script automatically reconnects if the long-running stream drops.
4.  **Synthesis**: It produces a comprehensive, cited report.

Overview

This skill performs autonomous, multi-step research using the Gemini Deep Research Agent via the Interactions API. It plans tasks, executes web searches, ingests local files or directories, and synthesizes a cited Markdown report. It also supports resilient streaming and follow-up interactions for iterative research.

How this skill works

The agent first decomposes your prompt into a step-by-step plan. It then executes web searches and reads any provided files or indexed file stores, streaming progress as it works. If the streaming connection drops, the tool automatically reconnects and continues. The final output is a synthesized, cited report you can save to disk or continue with follow-up queries.

When to use it

When you need a comprehensive research report that combines web search and local documents.
When analyzing large document collections (PDFs, text) for trends or summaries.
When you want an automated multi-step investigation with citations and structure.
When you need resilient long-running research that can reconnect and continue.
When you plan to iterate using follow-up queries tied to a prior interaction session.

Best practices

Provide clear, specific research questions and scope to focus the agent’s planning phase.
Upload small, representative documents directly; use the file-store index for large corpora.
Include relevant directories rather than individual files when multiple documents share context.
Save and reuse the Interaction ID to follow up or refine prior research results.
Request the final output in Markdown if you intend to edit or publish the report.

Example use cases

Create a cited historical overview and timeline for a technology like RISC-V.
Summarize and extract trends across hundreds of industry PDFs using a file-store index.
Produce a competitive landscape report and save it as a Markdown deliverable.
Ingest internal meeting notes and generate an executive summary with action items.
Run iterative deep dives: start broad, then ask follow-ups referencing the Interaction ID.

FAQ

What credentials are required?

You must set GOOGLE_API_KEY and use the google-genai SDK v0.3.0+ to access the Interactions API.

How do I include local documents?

Pass file paths or directories. For large corpora, enable the file-store option to index documents rather than uploading them into the live context.