Skip to main content

Documentation Index

Fetch the complete documentation index at: https://chatjs.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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

Enable deep research in chat.config.ts: 
ai: {
  tools: {
    deepResearch: {
      enabled: true,
    },
  },
}
Deep research uses the same search provider as web search. Configure one of the supported providers: 
# 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: {
      enabled: true,
      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
    },
  },
},
OptionDefaultDescription
allowClarificationtrueWhether to ask clarifying questions
maxResearcherIterations1Max supervisor loop iterations
maxConcurrentResearchUnits2Topics researched in parallel
maxSearchQueries2Max search queries per research topic
deepResearch modelgemini-2.5-flash-liteModel for research and supervision
deepResearchFinalReport modelgemini-3-flashModel for final report generation
Research uses multiple LLM calls. Consider cost implications when increasing iteration limits or using more expensive models.

​
UI States

The research progress is shown in real-time:
StateShows
startedResearch has begun
writingWriting research brief or final report
thoughtsResearch topics being investigated
completedResearch finished, report available
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.