Deep Research

Multi-step research agent with comprehensive reports

Overview

Deep Research is an autonomous agent that conducts multi-step research on complex topics. It breaks down research questions, executes parallel web searches, synthesizes findings, and produces comprehensive reports saved as documents.

Quick Start

Install the capability in your app:

bunx chat-js@alpha add deep-research

Deep research uses the same search provider as web search. Install one provider and configure its matching key. Missing search defaults to Tavily. To use Firecrawl, run bunx chat-js@alpha add firecrawl-search --replace:

# Option 1: Tavily (recommended)
TAVILY_API_KEY=your_tavily_key

# Option 2: Firecrawl
FIRECRAWL_API_KEY=your_firecrawl_key

How It Works

Deep research executes a 4-step pipeline:

Step 1: Clarification

If enabled, the agent analyzes the user’s request and asks clarifying questions when the scope is ambiguous. This ensures the research stays focused.

When clarification is needed:

• The agent responds with a question and pauses execution
• You provide the requested information in your next message
• If you explicitly selected the deep research tool, it remains selected after you respond
• Research continues automatically with the clarified scope

Step 2: Research Brief

The agent transforms the conversation into a structured research brief with a clear title and scope. This brief guides all subsequent research.

Step 3: Supervisor Loop

A supervisor agent orchestrates the research:

1. Reads the research brief
2. Identifies topics that need investigation
3. Dispatches researcher sub-agents to gather information
4. Collects and organizes findings
5. Continues until research is complete or iteration limit is reached

Each researcher agent:

• Executes web searches on its assigned topic
• Gathers relevant information from multiple sources
• Compresses findings into concise notes

Step 4: Final Report

The agent synthesizes all research notes into a comprehensive markdown report and saves it as a document using the canvas feature.

Configuration

Configure deep research behavior in chat.config.ts:

ai: {
  tools: {
    deepResearch: {
      defaultModel: "google/gemini-2.5-flash-lite",
      finalReportModel: "google/gemini-3-flash",
      allowClarification: true,      // Ask clarifying questions
      maxResearcherIterations: 1,    // Supervisor loop iterations
      maxConcurrentResearchUnits: 2, // Topics researched in parallel
      maxSearchQueries: 2,           // Queries per research topic
    },
  },
},

UI States

The research progress is shown in real-time:

Each research topic shows its own progress indicator as it’s being investigated.

Output

Deep research produces a document (via the canvas feature) containing:

• Comprehensive markdown report
• Structured findings organized by topic
• Citations from web sources

The document is saved to the user’s account and can be viewed, edited, and exported.