Prerequisites

• Python 3.11–3.13
• uv package manager
• NVIDIA API key from NVIDIA AI (for NIM models)
• Node.js 22+ and npm (optional, for web UI mode)

Optional requirements: - A web-search API key for the configured provider: Tavily, Exa, Nimble, or You.com - A paper search API key for one of the supported providers: Serper (SERPER_API_KEY), SerpAPI (SERPAPI_API_KEY), or SearchAPI (SEARCHAPI_API_KEY)

Note: Configure at least one data source (web search, paper search, or knowledge layer) to enable research functionality.

If these optional API keys are not provided, the agent continues to operate without the corresponding search capabilities. Refer to Obtain API Keys for details.

Hardware Requirements

When using NVIDIA API Catalog (the default), inference runs on NVIDIA-hosted infrastructure and there are no local GPU requirements. The hardware references below apply only when self-hosting models via NVIDIA NIM.

For detailed installation instructions, refer to Installation -- Hardware Requirements.

Install core with development dependencies

uv pip install -e ".[dev]"

Getting Started

Automated Setup

Run the setup script to initialize the environment:

./scripts/setup.sh

This script: - Creates a Python virtual environment with uv - Installs all Python dependencies (core, frontends, benchmarks, data sources) - Installs UI dependencies (if Node.js is available)

Manual Installation

For selective installation, install packages individually:

```bash

Install frontends (pick what you need)

uv pip install -e ./frontends/cli # CLI frontend uv pip install -e ./frontends/debug # Debug console uv pip install -e ./frontends/aiq_api # Unified API (includes debug)

Install benchmarks (pick what you need)

uv pip install -e ./frontends/benchmarks/freshqa

Install data sources (pick what you need)

uv pip install -e ./sources/tavily_web_search uv pip install -e ./sources/exa_web_search uv pip install -e ./sources/google_scholar_paper_search uv pip install -e ./sources/nimble_web_search uv pip install -e ./sources/you_com uv pip install -e "./sources/knowledge_layer[llamaindex,foundational_rag]" ```

Or run directly with the NeMo Agent Toolkit CLI (dotenv loads deploy/.env into the environment)

dotenv -f deploy/.env run nat run --config_file configs/config_cli_default.yml --input "How do I install CUDA?" ```

The CLI frontend source is in frontends/cli/.

No-auth local setup (LlamaIndex default)

docker compose --env-file ../.env -f docker-compose.yaml up -d --build

To select a different backend config, set BACKEND_CONFIG in deploy/.env, for example:

Step 1: Install the dataset

The dataset files are not included in the repository. We have included a script to retrieve them from the Deep Research Bench Github Repository and format them for the NeMo Agent Toolkit evaluator.

To download the dataset files, run the following script:

python frontends/benchmarks/deepresearch_bench/scripts/download_drb_dataset.py

Create and activate virtual environment

uv venv --python 3.13 .venv source .venv/bin/activate

Set Up Environment Variables

Create a .env file in deploy/ directory:

cp deploy/.env.example deploy/.env

Replace your API keys.

Note: Depending on your usecase, deep research report quality can be enhanced by enabling searching across academic research papers. We use Serper for this. If you want to use paper search, follow the steps in the Customization guide to enable it.

Configuration Files

The configs/ directory holds YAML workflow configs that define agents, tools, LLMs, and routing. Use the one that matches your run mode and data sources:

Activate the virtual environment

source .venv/bin/activate

BACKEND_CONFIG=/app/configs/config_web_frag.yml

```

For more details, refer to: - deploy/compose/README.md

Optional: Phoenix Tracing

If your config enables Phoenix tracing, start the Phoenix server before running nat eval.

Start server (separate terminal):

uvx --from arize-phoenix phoenix serve

For detailed benchmark documentation, refer to: - Deep Research Bench README - FreshQA README

Obtain API Keys

Obtain an NVIDIA API Key

1. Sign in to NVIDIA Build
2. Click on any model, then select "Deploy" > "Get API Key" > "Generate Key"

Obtain a Tavily API Key

1. Sign in to Tavily
2. Navigate to your dashboard
3. Generate an API key

Obtain an Exa API Key

1. Sign in to Exa
2. Create an API key from the dashboard
3. Add it to deploy/.env as EXA_API_KEY

Refer to the exa_web_search section in the Configuration Reference for workflow usage.

Obtain a You.com API Key

Follow the You.com quickstart to create an API key and add it to deploy/.env as YDC_API_KEY. Refer to You.com API Suite for tool configuration.

Obtain a Paper Search API Key

Paper search supports three interchangeable providers. Set the provider field on the paper_search function in your workflow config (defaults to serper):

Refer to sources/google_scholar_paper_search/README.md for configuration details.

Command-line interface (CLI)

The CLI provides an interactive research assistant in your terminal:

```bash

Software Components

The checked-in default CLI and web profiles use these core components:

• NVIDIA NeMo Agent Toolkit 1.8.0
• LangChain Deep Agents 0.6.5 or newer
• NVIDIA Nemotron 3.5 Lightning for intent classification and shallow research in the default profiles
• NVIDIA Nemotron 3 Ultra for clarification and every deep-research role
• Google Gemma 4 31B IT (document summary, if used)
• NVIDIA Nemotron 3 Embed 1B (embedding model for the knowledge layer, if used)
• NVIDIA Nemotron 3 Nano Omni 30B A3B Reasoning (vision-language model for the LlamaIndex knowledge layer, if used)
• Tavily Search API for web search
• Serper, SerpAPI, or SearchAPI for Google Scholar paper search

Known hosted-serving limitation: Nemotron 3.5 Lightning can intermittently produce citation-incomplete or malformed shallow drafts when served through NVIDIA API Catalog. AI-Q fails closed instead of publishing those drafts. The Brev getting-started launchable uses Nemotron Ultra for shallow research; the general-purpose shipped profiles retain Lightning. See Troubleshooting for details and the self-hosted Lightning option.

The shipped frontier profile, configs/config_frontier_models.yml, uses GPT-5.6 Luna for intent classification, shallow research, source routing, and deep-research execution, with GPT-5.6 Sol for clarification, orchestration, planning, and writing. Treat any bring-your-own model or modified profile as an experimental customization until the complete workflow is evaluated with that exact model, prompt, hyperparameter, tool-calling, and structured-output configuration. Refer to Configuration Files; there is no single all-features profile.

Evaluating the Workflow

The frontends/benchmarks/ directory contains evaluation pipelines for assessing agent performance.