Open Deep Research

To run the research assistant locally using Node.js, follow these steps:

1. Clone the repository.
2. Install dependencies using npm install.
3. Create a .env.local file in the root directory and configure your API keys.

Required environment variables:

• FIRECRAWL_KEY: Your Firecrawl API key for web search and extraction.
• OPENAI_KEY: Your OpenAI API key (defaults to using the o3-mini model).

If you are using a self-hosted Firecrawl instance, add:

• FIRECRAWL_BASE_URL: The URL of your instance (e.g., http://localhost:3002).

npm install

# Create .env.local with:
FIRECRAWL_KEY="your_firecrawl_key"
OPENAI_KEY="your_openai_key"

To run the research assistant using Docker:

1. Clone the repository.
2. Rename .env.example to .env.local and populate it with your API keys.
3. Build the image: docker build -f Dockerfile.
4. Start the container: docker compose up -d.
5. Execute the research command within the container using: docker exec -it deep-research npm run docker.

The system can automatically switch from o3-mini to DeepSeek R1 if a Fireworks API key is detected. Simply add the following to your environment variables:

• FIREWORKS_KEY: Your Fireworks API key.

FIREWORKS_KEY="api_key"

You can bypass OpenAI by using a local LLM server or other OpenAI-compatible providers (like OpenRouter or Gemini) by configuring the following environment variables in .env.local:

• OPENAI_ENDPOINT: The address of your local server or custom provider (e.g., http://localhost:1234/v1).
• OPENAI_MODEL or CUSTOM_MODEL: The name of the model to be used. (Note: The README mentions both OPENAI_MODEL and CUSTOM_MODEL for tweaking the model string).

To use a local LLM, comment out OPENAI_KEY and set these values.

# Example for local LLM
# OPENAI_KEY=""
OPENAI_ENDPOINT="http://localhost:1234/v1"
OPENAI_MODEL="model-name-here"

You can control the speed of research by adjusting the CONCURRENCY_LIMIT environment variable:

• High Performance: If using a paid Firecrawl account or a local version, increase CONCURRENCY_LIMIT to run searches and processing in parallel.
• Rate Limit Avoidance: If using a free version of Firecrawl, set CONCURRENCY_LIMIT=1 to avoid rate limit errors.

# To run faster
CONCURRENCY_LIMIT=10

# To avoid rate limits
CONCURRENCY_LIMIT=1

You can deploy the Deep Research service using Docker Compose. The configuration uses a local .env.local file for environment variables and mounts the current directory to /app/ inside the container to allow for live development or persistent access to local files.

To run the service, ensure you have a docker-compose.yml file in your project root and execute:

docker-compose up

services:
  deep-research:
    container_name: deep-research
    build: .
    env_file:
      - .env.local
    volumes:
      -  ./:/app/
    tty: true
    stdin_open: true

The agent uses Firecrawl for web searching and scraping. You can configure its behavior and connection using the following environment variables:

• FIRECRAWL_KEY: Your Firecrawl API key.
• FIRECRAWL_BASE_URL: The base URL for your Firecrawl instance (useful for self-hosted setups, e.g., http://localhost:3002).
• FIRECRAWL_CONCURRENCY: Controls the number of parallel requests made to Firecrawl. Defaults to 2. Increase this if your API rate limits allow.

Start the interactive research process by running npm start. The CLI will prompt you for:

1. Research Query: The topic you want to investigate.
2. Research Breadth: How many search results to process (recommended: 3-10, default: 4).
3. Research Depth: How many recursive iterations to perform (recommended: 1-5, default: 2).
4. Follow-up Questions: Answers to refine the research direction.

Upon completion, the system generates a markdown report saved as report.md or answer.md in your working directory.

Use writeFinalAnswer when you need a short, direct answer to a specific question based on research, rather than a long report. This is ideal for tasks like answering multiple-choice questions or extracting a single specific metric.

Parameters

• prompt: The specific question or format instructions (e.g., "Answer in Latex").
• learnings: The research findings to use for the answer.

import { writeFinalAnswer } from './deep-research';

const answer = await writeFinalAnswer({
  prompt: "What is the melting point of Gold? Answer in Celsius.",
  learnings: ["Gold melts at 1064 degrees Celsius."]
});

console.log(answer); // "1064°C"

The getModel() function returns the currently configured LanguageModelV1 instance based on the environment variables provided. If no valid configuration is found (i.e., no keys are set), it throws an error: No model found.

This is the primary way to access the model instance used by the application.

import { getModel } from './ai/providers';

const model = getModel();
// model is a LanguageModelV1 instance ready for use with AI SDK