{ "cells": [ { "cell_type": "markdown", "id": "4255acc0", "metadata": {}, "source": [ "# Try out the NVIDIA Deep Researcher Agent Blueprint!\n", "This notebook deploys the NVIDIA Deep Researcher Agent Blueprint — a reference application for an enterprise-grade research agent built with the [NeMo Agent toolkit](https://docs.nvidia.com/nemo/agent-toolkit/latest/). It uses a two-tier research architecture that keeps simple queries fast while reserving multi-phase deep research for complex topics. The blueprint demonstrates an AI-powered research workflow that combines intent-aware routing, shallow and deep research agents, and optional human-in-the-loop clarification, plus benchmarks and evaluation harnesses for evaluation-driven development.\n", "\n", "Some of the key capabilities of this blueprint are:\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
CapabilityDescriptionValue
Intelligence Dynamic RoutingSelects the right model, workflow depth, and data sourcesoptimal cost & performance
Custom Evaluation MetricsEvaluation harness with transparent reasoningtrust, auditability, reliability
Open RecipeFully open, modular codebase with pluggable componentseasy to customize and extend
Persistent Context ManagementVirtual file system and workspaces for data, code, and insightshandles long-running workflows
\n", "\n", "In this notebook, you will install the prerequisites, set up the workflow environment, and connect to NVIDIA-hosted NIM APIs. Once deployed, you will have a fully functional research assistant that can answer simple questions via fast tool-augmented lookup (shallow research) and produce citation-backed, publication-style reports for complex topics (deep research). You can run the blueprint with web search only, customize models and tools, and optionally add pluggable knowledge retrieval.\n", "\n", "\n", "Note: this notebook is designed to run as a [brev.dev launchable](https://brev.nvidia.com/launchable/deploy?launchableID=env-3ArAhMZxDcUsqbBUL8SbE2fAbKp)" ] }, { "cell_type": "markdown", "id": "94ca7ab0", "metadata": {}, "source": [ "![Architecture diagram](https://github.com/NVIDIA-AI-Blueprints/deep-researcher-agent/raw/develop/docs/assets/DeepResearcher-arch-light.png)" ] }, { "cell_type": "markdown", "id": "19647ad7", "metadata": {}, "source": [ "# Getting Started\n", "\n", "> [Software Components](#software-components) \n", "> [Hardware Requirements](#hardware-requirements) \n", "> [Prerequisites](#prerequisites) \n", "> [Spin Up Blueprint](#spin-up-blueprint) \n", "> [Environment Setup](#environment-setup) \n", "> [Run agent with NAT](#run-this-agent-using-the-nemo-agent-toolkit-run-command) \n", "> [Meta / Shallow / Deep examples](#meta-responses) \n", "> [Deployment using Docker Compose](#deployment-using-docker-compose) \n", "> [Optional Guardrails and Sandbox Profiles](#optional-guardrails-and-sandbox-profiles) \n", "> [Next Steps](#next-steps)" ] }, { "cell_type": "markdown", "id": "cfcf3065", "metadata": {}, "source": [ "## Software Components" ] }, { "cell_type": "markdown", "id": "3a13a1e7", "metadata": {}, "source": [ "The following are used by this project:\n", "\n", "- [NVIDIA NeMo Agent toolkit](https://docs.nvidia.com/nemo/agent-toolkit/latest/)\n", "- [NIM of nvidia/nemotron-3.5-lightning-30b-a3b](https://build.nvidia.com/nvidia/nemotron-3.5-lightning-30b-a3b/modelcard) for intent classification\n", "- [NIM of nvidia/nemotron-3-ultra-550b-a55b](https://build.nvidia.com/nvidia/nemotron-3-ultra-550b-a55b) for shallow research and every deep-research role in this Brev launchable\n", "- [NIM of nvidia/nemotron-3-embed-1b](https://build.nvidia.com/nvidia/nemotron-3-embed-1b) (Optional)\n", "- [NIM of nvidia/nemotron-3-nano-omni-30b-a3b-reasoning](https://build.nvidia.com/nvidia/nemotron-3-nano-omni-30b-a3b-reasoning) (Optional)\n", "- [NVIDIA google/gemma-4-31b-it](https://build.nvidia.com/google/gemma-4-31b-it) (Optional)\n", "- [Tavily Search API](https://tavily.com/) for web search\n", "- [NeMo Guardrails](https://docs.nvidia.com/nemo/guardrails/latest/) through NeMo Agent Toolkit middleware (Optional)\n", "- [NVIDIA OpenShell](https://docs.nvidia.com/openshell/latest/about/installation) (Optional)" ] }, { "cell_type": "markdown", "id": "413cdd2f", "metadata": {}, "source": [ "## Hardware Requirements\n", "\n", "We have two deployment options: \n", "\n", "- **Using Hosted NIMs**:\n", "If you are deploying this blueprint without the NVIDIA RAG knowledge layer backend, there are **no GPU requirements** for this blueprint on its own.\n", "\n", "- **Self-hosting NIMs:**\n", "See the model cards for current deployment options for `nvidia/nemotron-3.5-lightning-30b-a3b` and `nvidia/nemotron-3-ultra-550b-a55b`. This Brev launchable uses Ultra for shallow research because the NVIDIA API Catalog Lightning serving profile has a known citation-output reliability limitation. A validated self-hosted Lightning profile remains the lower-latency alternative. \n", "If using NVIDIA RAG knowledge layer backend, please see [NVIDIA RAG Documentation Pages](https://docs.nvidia.com/rag/latest/support-matrix.html)\n", "\n" ] }, { "cell_type": "markdown", "id": "62e9b0c5", "metadata": {}, "source": [ "## Prerequisites" ] }, { "cell_type": "markdown", "id": "f3a2023b", "metadata": {}, "source": [ "- **Docker Compose**\n", "- **LLM API key** – For your chosen provider (required for LLM inference):\n", " - **NVIDIA API Key** from [NVIDIA AI](https://build.nvidia.com/) (for NIM models)\n", "Optional requirements:\n", "- **Web search API key**:\n", " - **Tavily** – [tavily.com](https://tavily.com) (for general web search)\n", "- **Node.js 22+ and npm** (optional, for web UI mode)" ] }, { "cell_type": "markdown", "id": "393ff38a", "metadata": {}, "source": [ "## Spin Up Blueprint\n", "\n", "We will be using docker compose to deploy this blueprint and interact with the NAT `run` command as well as through the custom chat-based frontend UI." ] }, { "cell_type": "markdown", "id": "c9fcb628", "metadata": {}, "source": [ "### Environment Setup" ] }, { "cell_type": "markdown", "id": "29b3710e", "metadata": {}, "source": [ "1. **Clone** the NVIDIA Deep Researcher Agent Blueprint workflow repository\n", ">**Note**: Skip this step if you are not on brev and instead running from within the repository." ] }, { "cell_type": "code", "execution_count": null, "id": "3c6dcdf1", "metadata": {}, "outputs": [], "source": [ "%%bash\n", "# Only run this cell in a brev launchable\n", "git clone https://github.com/NVIDIA-AI-Blueprints/deep-researcher-agent.git deep-researcher" ] }, { "cell_type": "code", "execution_count": null, "id": "f30da0cd", "metadata": {}, "outputs": [], "source": [ "# Only run this cell in a brev launchable\n", "# moves the notebook into the directory\n", "%cd /home/ubuntu/deep-researcher\n", "repo_root = \"/home/ubuntu/deep-researcher\"" ] }, { "cell_type": "markdown", "id": "170c0be0", "metadata": {}, "source": [ "2. **Setup** Environment" ] }, { "cell_type": "code", "execution_count": null, "id": "346b1369", "metadata": {}, "outputs": [], "source": [ "%%bash\n", "# Some dependencies (for example, annoy via nemoguardrails) are built from source\n", "# and need a C/C++ compiler. Fresh Brev/Ubuntu VMs do not ship one.\n", "if ! command -v c++ >/dev/null 2>&1; then\n", " if command -v apt-get >/dev/null 2>&1; then\n", " SUDO=\"\"\n", " [ \"$(id -u)\" -ne 0 ] && SUDO=\"sudo\"\n", " $SUDO apt-get update -qq && $SUDO apt-get install -y -qq build-essential\n", " else\n", " echo \"No C/C++ compiler found. Install one (for example, Xcode Command Line Tools on macOS) before running setup.\"\n", " fi\n", "fi\n", "if ! command -v c++ >/dev/null 2>&1; then\n", " echo \"C/C++ compiler is still missing; setup will fail.\" >&2\n", " exit 1\n", "fi\n", "c++ --version | head -n 1" ] }, { "cell_type": "code", "execution_count": null, "id": "4243994f", "metadata": {}, "outputs": [], "source": [ "# Run setup from the project root (where pyproject.toml and scripts/setup.sh live).\n", "import os\n", "from pathlib import Path\n", "\n", "cwd = Path.cwd().resolve()\n", "configured_repo_root = globals().get(\"repo_root\")\n", "REPO_ROOT = Path(configured_repo_root).expanduser().resolve() if configured_repo_root else None\n", "\n", "search_roots = [cwd, *cwd.parents]\n", "if REPO_ROOT is not None:\n", " search_roots = [REPO_ROOT, *search_roots]\n", "\n", "REPO_ROOT = None\n", "for candidate in search_roots:\n", " if (candidate / \"pyproject.toml\").exists() and (candidate / \"scripts\" / \"setup.sh\").exists():\n", " REPO_ROOT = candidate\n", " break\n", "\n", "if REPO_ROOT is None:\n", " raise FileNotFoundError(\"Could not locate project root containing pyproject.toml and scripts/setup.sh\")\n", "\n", "os.environ[\"REPO_ROOT\"] = str(REPO_ROOT)\n", "os.chdir(REPO_ROOT)\n", "os.environ[\"UV_VENV_CLEAR\"] = \"1\"\n", "get_ipython().system(\"./scripts/setup.sh\")" ] }, { "cell_type": "code", "execution_count": null, "id": "242db69c", "metadata": {}, "outputs": [], "source": [ "%%bash\n", "source .venv/bin/activate" ] }, { "cell_type": "markdown", "id": "79037a12", "metadata": {}, "source": [ "3. **Obtain and set** API keys and environment variables" ] }, { "cell_type": "markdown", "id": "165f51ee", "metadata": {}, "source": [ "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
APIEnvironment VariablePurpose
NVIDIANVIDIA_API_KEYNIM / NGC model inference (required)
TavilyTAVILY_API_KEYWeb search (recommended)
\n", "\n", "**NVIDIA API key:** \n", "1. Go to [NVIDIA Build](https://build.nvidia.com/explore/discover) or [NGC](https://ngc.nvidia.com/). \n", "2. Sign in and open a model card (e.g. Nemotron). \n", "3. Use **Get API Key** → **Generate Key**, then copy the key (starts with `nvapi-`). \n", "\n", "**Tavily API key:** \n", "1. Go to [tavily.com](https://tavily.com) and create an account. \n", "2. Create an API key in the dashboard and add it to your environment. " ] }, { "cell_type": "code", "execution_count": null, "id": "9f1c6056", "metadata": {}, "outputs": [], "source": [ "import getpass\n", "import os\n", "\n", "if \"NVIDIA_API_KEY\" not in os.environ or os.environ[\"NVIDIA_API_KEY\"] == \"\":\n", " nvidia_api_key = getpass.getpass(\"Enter your NVIDIA API key: \")\n", " os.environ[\"NVIDIA_API_KEY\"] = nvidia_api_key\n", "\n", "if \"TAVILY_API_KEY\" not in os.environ or os.environ[\"TAVILY_API_KEY\"] == \"\":\n", " tavily_api_key = getpass.getpass(\"Enter your Tavily API key: \")\n", " os.environ[\"TAVILY_API_KEY\"] = tavily_api_key" ] }, { "cell_type": "markdown", "id": "39d61c60", "metadata": {}, "source": [ "### Run this agent using the NeMo Agent Toolkit [`run` command](https://docs.nvidia.com/nemo/agent-toolkit/latest/run-workflows/about-running-workflows.html#using-the-nat-run-command)" ] }, { "cell_type": "code", "execution_count": null, "id": "a73f34f8", "metadata": {}, "outputs": [], "source": [ "%%writefile config_simple_researcher.yml\n", "\n", "general:\n", " telemetry:\n", " logging:\n", " console:\n", " _type: console\n", " level: INFO\n", "\n", "llms:\n", " nemotron_lightning_intent_llm:\n", " _type: nim\n", " model_name: nvidia/nemotron-3.5-lightning-30b-a3b\n", " base_url: \"https://integrate.api.nvidia.com/v1\"\n", " api_key: ${NVIDIA_API_KEY}\n", " temperature: 0.1\n", " top_p: 0.9\n", " max_tokens: 1024\n", " num_retries: 5\n", " parallel_tool_calls: false\n", " chat_template_kwargs:\n", " enable_thinking: false\n", "\n", " # The API Catalog Lightning serving profile can intermittently produce citation-incomplete\n", " # shallow drafts. Deep Researcher Agent fails closed rather than publishing them. For a lower-latency\n", " # alternative, self-host Lightning with a serving profile validated end to end with Deep Researcher Agent.\n", " # nemotron_lightning_agent_llm:\n", " # _type: nim\n", " # model_name: nvidia/nemotron-3.5-lightning-30b-a3b\n", " # base_url: \"http:///v1\"\n", " # api_key: ${SELF_HOSTED_LIGHTNING_API_KEY}\n", " # temperature: 0.2\n", " # top_p: 0.7\n", " # max_tokens: 8192\n", " # num_retries: 5\n", " # parallel_tool_calls: false\n", " # chat_template_kwargs:\n", " # enable_thinking: true\n", "\n", " nemotron_ultra_shallow_llm:\n", " _type: nim\n", " model_name: nvidia/nemotron-3-ultra-550b-a55b\n", " base_url: \"https://integrate.api.nvidia.com/v1\"\n", " api_key: ${NVIDIA_API_KEY}\n", " temperature: 0.2\n", " top_p: 0.7\n", " max_tokens: 8192\n", " num_retries: 5\n", " parallel_tool_calls: false\n", " chat_template_kwargs:\n", " enable_thinking: true\n", "\n", " nemotron_ultra_llm:\n", " _type: nim\n", " model_name: nvidia/nemotron-3-ultra-550b-a55b\n", " base_url: \"https://integrate.api.nvidia.com/v1\"\n", " api_key: ${NVIDIA_API_KEY}\n", " temperature: 0.2\n", " top_p: 0.7\n", " max_tokens: 16384\n", " num_retries: 5\n", " chat_template_kwargs:\n", " enable_thinking: false\n", "\n", " nemotron_ultra_writer_llm:\n", " _type: nim\n", " model_name: nvidia/nemotron-3-ultra-550b-a55b\n", " base_url: \"https://integrate.api.nvidia.com/v1\"\n", " api_key: ${NVIDIA_API_KEY}\n", " temperature: 0.2\n", " top_p: 0.7\n", " max_tokens: 32768\n", " num_retries: 5\n", " chat_template_kwargs:\n", " enable_thinking: false\n", "\n", "functions:\n", " web_search_tool:\n", " _type: tavily_web_search\n", " max_results: 5\n", " max_retries: 3\n", " advanced_search: false\n", " max_content_length: 1000\n", "\n", " advanced_web_search_tool:\n", " _type: tavily_web_search\n", " max_results: 2\n", " advanced_search: true\n", "\n", " intent_classifier:\n", " _type: intent_classifier\n", " llm: nemotron_lightning_intent_llm\n", " tools:\n", " - web_search_tool\n", "\n", " shallow_research_agent:\n", " _type: shallow_research_agent\n", " llm: nemotron_ultra_shallow_llm\n", " tools:\n", " - web_search_tool\n", " max_llm_turns: 20\n", " max_tool_iterations: 5\n", "\n", " deep_research_agent:\n", " _type: deep_research_agent\n", " orchestrator_llm: nemotron_ultra_llm\n", " source_router_llm: nemotron_ultra_llm\n", " researcher_llm: nemotron_ultra_llm\n", " planner_llm: nemotron_ultra_llm\n", " writer_llm: nemotron_ultra_writer_llm\n", " tools:\n", " - advanced_web_search_tool\n", "\n", "workflow:\n", " _type: chat_deepresearcher_agent\n", " interactive_auth: false\n", " checkpoint_db: ${DEEP_RESEARCHER_CHECKPOINT_DB:-./checkpoints.db}\n" ] }, { "cell_type": "markdown", "id": "55351e5c", "metadata": {}, "source": [ "**What this config does:** \n", "\n", "This config defines a NAT workflow for the Deep Researcher Agent chat researcher. \n", "\n", "**`general`** includes the API worker settings and telemetry configuration.\n", "\n", "**`general.front_end`** wires the Web API (Deep Researcher Agent API Worker), async job store, and CORS for the chat UI.\n", "\n", "**`llms`** keeps Nemotron 3.5 Lightning for intent classification and uses a bounded Nemotron Ultra profile for shallow research, plus role-specific Ultra profiles for deep research. The commented Lightning shallow profile is intended for a self-hosted endpoint validated with Deep Researcher Agent; it is not configured to use NVIDIA API Catalog.\n", "\n", "**`functions`** register tools (Tavily web search, plus advanced search), the intent classifier, and the shallow and deep research agents with their assigned tools and LLMs.\n", " \n", "**`workflow`** is set to `chat_deepresearcher_agent`. See source code for this full agent in `src/deep_researcher_agent/agents/chat_researcher/agent.py`.\n", "\n", "**Optional settings:** \n", "\n", "`interactive_auth: false` disables interactive auth prompts for this local demo config.\n", "\n", "**Main agents:** intent classifier, shallow research, deep research. \n", "**Tools:** web search tool for shallow researcher and advanced web search for deep research.\n", "\n", ">**Optional — Frontier model config:** For improved research quality, you can use `configs/config_frontier_models.yml`, which assigns `gpt-5.6-luna` to intent classification, shallow research, source routing, and deep-research execution, and `gpt-5.6-sol` to clarification, orchestration, planning, and writing. When using Docker Compose or the web UI, set `BACKEND_CONFIG` to `/app/configs/config_frontier_models.yml`. Remember to set the required API keys in your `.env` file.\n" ] }, { "cell_type": "markdown", "id": "5399c23d", "metadata": {}, "source": [ "#### Meta Responses \n", "\n", "Documentation: `docs/source/architecture/agents/intent-classifier.md`\n", "\n", "Meta responses handle greetings and questions about what Deep Researcher Agent can do.\n" ] }, { "cell_type": "code", "execution_count": null, "id": "8be9016c", "metadata": {}, "outputs": [], "source": [ "!.venv/bin/nat run --config_file config_simple_researcher.yml --input \"Hello, what can you do?\" | sed 's/\\\\n/\\n/g'" ] }, { "cell_type": "markdown", "id": "1ba46836", "metadata": {}, "source": [ "#### Shallow Research\n", "\n", "Documentation: `docs/source/architecture/agents/shallow-researcher.md`\n", "\n", "Shallow research handles focused factual questions with a short tool-assisted lookup.\n" ] }, { "cell_type": "code", "execution_count": null, "id": "ce6cf290", "metadata": {}, "outputs": [], "source": [ "!.venv/bin/nat run --config_file config_simple_researcher.yml --input \"What is NVIDIA Spectrum-X primarily designed for?\" | sed 's/\\\\n/\\n/g'" ] }, { "cell_type": "markdown", "id": "18456f60", "metadata": {}, "source": [ "#### Deep Research \n", "\n", "Documentation: `docs/source/architecture/agents/deep-researcher.md` \n", "\n", "
\n", "Note: Deep research can take several minutes: multiple LLM calls and web searches run in sequence. Watch the logs to see planning and research steps.\n", "
\n" ] }, { "cell_type": "code", "execution_count": null, "id": "7df6078b", "metadata": {}, "outputs": [], "source": [ "!.venv/bin/nat run --config_file config_simple_researcher.yml --input \"Conduct a comprehensive technical comparison between NVIDIA GB300 and Google Ironwood AI accelerator platforms. Generate a structured report with the following sections: Compute Architecture, Memory Subsystem, Interconnect & Scalability, System & Power, Software Ecosystem and Benchmarks\" | sed 's/\\\\n/\\n/g'" ] }, { "cell_type": "markdown", "id": "ccb14b50", "metadata": {}, "source": [ "### Deployment using Docker Compose" ] }, { "cell_type": "markdown", "id": "7e35bd00", "metadata": {}, "source": [ "1. Set environment variables for docker compose deployment" ] }, { "cell_type": "code", "execution_count": null, "id": "60e5df99", "metadata": {}, "outputs": [], "source": [ "os.environ[\"BACKEND_URL\"] = \"http://deep-researcher-agent:8000\"\n", "os.environ[\"REQUIRE_AUTH\"] = \"false\"\n", "os.environ[\"BACKEND_CONFIG\"] = (\n", " \"/app/configs/config_web_default_llamaindex.yml\" # path to the NAT config file from inside the docker container\n", ")" ] }, { "cell_type": "markdown", "id": "b4071595", "metadata": {}, "source": [ "2. Create an env file with secrets" ] }, { "cell_type": "code", "execution_count": null, "id": "9767e5d9", "metadata": {}, "outputs": [], "source": [ "%%bash\n", "cat > deploy/.env < /dev/null 2>&1" ] }, { "cell_type": "markdown", "id": "e022a279", "metadata": {}, "source": [ "4. Verify the containers are running" ] }, { "cell_type": "code", "execution_count": null, "id": "5ef83438", "metadata": {}, "outputs": [], "source": [ "# Confirm all the below mentioned containers are running.\n", "import subprocess\n", "\n", "result = subprocess.run(\n", " [\"docker\", \"ps\", \"--format\", \"table {{.ID}}\\t{{.Names}}\\t{{.Status}}\"],\n", " check=False,\n", " capture_output=True,\n", " text=True,\n", ")\n", "\n", "print(result.stdout)" ] }, { "cell_type": "markdown", "id": "7f706821", "metadata": {}, "source": [ "The output should look something like this:\n", "\n", "```\n", "CONTAINER ID NAMES STATUS\n", "5f5bf0e2438f deep-researcher-blueprint-ui Up 2 minutes (healthy)\n", "e11fad0dba6e deep-researcher-agent Up 2 minutes\n", "66d55656299b deep-researcher-postgres Up 3 minutes (healthy)\n", "```" ] }, { "cell_type": "markdown", "id": "fed113dd", "metadata": {}, "source": [ "At this point, you should be able to access the NVIDIA Deep Researcher Agent frontend web application. On a local machine, visit http://localhost:3000. On Brev, open the forwarded/proxied port 3000 URL from the Brev environment.\n", "\n", ">**Warning:** This demo sets `REQUIRE_AUTH=false`. Keep the local or Brev URL private and use it only in a trusted demo environment. Anyone with access to the URL can access jobs, reports, and, when artifact capture is enabled, generated files. Enable authentication before sharing the deployment.\n", "\n", ">**Tip:** If you are running this notebook on brev, you will need to make the port for the Deep Researcher Agent frontend accessible. On the settings page for your machine, navigate to \"Using Ports\", enter \"3000\", click \"Expose Port\", and then click \"I accept\".\n", "\n", "**Select data sources:** In the UI, open the **data sources** panel (e.g. from the right side or connections icon). You will see available sources (e.g. Web Search, and optionally Paper Search, Knowledge Layer, or enterprise sources if configured). Toggle **on** the sources you want the agent to use for the next query. Web Search is usually enabled by default.\n", "\n", "**Send a query:** Type your question or research request in the chat input and send it. The agent will use only the **enabled** data sources for that query. For deep research, the UI may show clarification steps; respond as prompted. Results and the final report will appear in the chat.\n", "\n", "**Follow up on a report:** After a deep research report completes, you can ask follow-up questions or request a targeted rewrite from the completed report view. Deep Researcher Agent keeps the original report as context and starts a follow-up job when more research or synthesis is needed." ] }, { "cell_type": "markdown", "id": "optional-policy-sandbox-22", "metadata": {}, "source": [ "### Optional Guardrails and Sandbox Profiles\n", "\n", "The default UI deployment above uses `configs/config_web_default_llamaindex.yml`. Deep Researcher Agent also ships focused profiles for optional capabilities:\n", "\n", "- **Guardrails:** `configs/config_web_default_guardrails.yml` adds NeMo Guardrails checks at selected workflow and agent boundaries. Select it by setting `BACKEND_CONFIG=/app/configs/config_web_default_guardrails.yml` in `deploy/.env` before starting Docker Compose. See `docs/source/customization/guardrails.md`.\n", "- **OpenShell sandbox and durable artifacts:** `configs/config_openshell.yml` enables policy-bound sandbox execution, skills, and capture of generated files for the UI **Files** tab. Before using this profile, install and start the OpenShell gateway, generate or provide the policy file, and set the `DEEP_RESEARCHER_OPENSHELL_*` environment variables described in `docs/source/deployment/openshell.md`.\n", "\n", "These profiles are optional and are not required for the basic web-search workflow." ] }, { "cell_type": "code", "execution_count": null, "id": "52f86fe4", "metadata": {}, "outputs": [], "source": [ "# Bring docker containers down\n", "!docker compose -f deploy/compose/docker-compose.yaml down -v" ] }, { "cell_type": "code", "execution_count": null, "id": "93eca53f", "metadata": {}, "outputs": [], "source": [ "# Optional: Reset the environment\n", "# use only if you want to stop containers, remove volumes, and delete cached images\n", "!docker compose -f deploy/compose/docker-compose.yaml down -v --rmi all" ] }, { "cell_type": "markdown", "id": "r32cg5g3d9q", "metadata": {}, "source": [ "## (Optional) Add Observability with LangSmith\n", "\n", "[LangSmith](https://smith.langchain.com/) lets you trace, monitor, and debug your Deep Researcher Agent runs end-to-end.\n", "\n", "**1. Sign up and get an API key**\n", "\n", "Go to [smith.langchain.com](https://smith.langchain.com/), create an account, and generate an API key. Create a project to collect your traces.\n", "\n", "**2. Set your LangSmith environment variables**" ] }, { "cell_type": "code", "execution_count": null, "id": "gcgtlm1qmx5", "metadata": {}, "outputs": [], "source": [ "import getpass\n", "import os\n", "\n", "if \"LANGSMITH_API_KEY\" not in os.environ or os.environ[\"LANGSMITH_API_KEY\"] == \"\":\n", " langsmith_api_key = getpass.getpass(\"Enter your LangSmith API key: \")\n", " os.environ[\"LANGSMITH_API_KEY\"] = langsmith_api_key\n", "\n", "if \"LANGSMITH_PROJECT\" not in os.environ or os.environ[\"LANGSMITH_PROJECT\"] == \"\":\n", " os.environ[\"LANGSMITH_PROJECT\"] = input(\"Enter your LangSmith project name: \")" ] }, { "cell_type": "markdown", "id": "mp3fa80d86", "metadata": {}, "source": [ "**3. Add LangSmith tracing to your config**\n", "\n", "Run the cell below to automatically update `config_simple_researcher.yml` with LangSmith tracing:" ] }, { "cell_type": "code", "execution_count": null, "id": "ls_config_writer", "metadata": {}, "outputs": [], "source": [ "config_path = \"config_simple_researcher.yml\"\n", "\n", "with open(config_path) as f:\n", " content = f.read()\n", "\n", "if \"tracing:\" not in content:\n", " content = content.replace(\n", " \" level: INFO\\n\",\n", " \" level: INFO\\n\\n\"\n", " \" tracing:\\n\"\n", " \" langsmith:\\n\"\n", " \" _type: langsmith\\n\"\n", " \" project: ${LANGSMITH_PROJECT}\\n\"\n", " \" api_key: ${LANGSMITH_API_KEY}\\n\",\n", " 1,\n", " )\n", " with open(config_path, \"w\") as f:\n", " f.write(content)\n", " print(f\"Tracing config added to {config_path}\")\n", "else:\n", " print(\"Tracing config already present — no changes made.\")" ] }, { "cell_type": "markdown", "id": "ls_verify_md", "metadata": {}, "source": [ "**4. Run the agent and verify traces**\n", "\n", "Re-run the agent with the updated config:" ] }, { "cell_type": "code", "execution_count": null, "id": "ls_run_agent", "metadata": {}, "outputs": [], "source": [ "!.venv/bin/nat run --config_file config_simple_researcher.yml --input \"What is NVIDIA Spectrum-X?\" | sed 's/\\\\n/\\n/g'" ] }, { "cell_type": "markdown", "id": "ls_check_md", "metadata": {}, "source": [ "After the run completes, go to [smith.langchain.com](https://smith.langchain.com/), open your project, and you should see a new trace for the query above. Click into it to explore the agent's steps, LLM calls, and tool usage." ] }, { "cell_type": "markdown", "id": "together_lightweight_md", "metadata": {}, "source": [ "## (Optional) Use a Partner LLM Endpoint\n", "\n", "You can swap the LLM provider in `config_simple_researcher.yml` with any OpenAI-compatible API.\n", "\n", "For example, to use [Together.ai](https://www.together.ai/) with a supported model — sign up at [together.ai](https://www.together.ai/), generate an API key, and update the relevant Lightning or Ultra LLM block. The pattern below shows the provider change for one block:\n", "\n", "```yaml\n", "llms:\n", " nemotron_ultra_llm:\n", " _type: openai\n", " model_name: ${TOGETHER_MODEL_NAME}\n", " base_url: \"https://api.together.ai/v1\"\n", " api_key: ${TOGETHER_API_KEY}\n", " temperature: 0.1\n", " top_p: 0.3\n", " max_tokens: 16384\n", " num_retries: 5\n", "```\n", "\n", "Key changes from the default NIM config:\n", "- `_type: nim` → `_type: openai`\n", "- `base_url` → partner endpoint URL\n", "- `api_key` → your `TOGETHER_API_KEY`\n", "- Remove `chat_template_kwargs: enable_thinking: true` (NIM-specific)\n", "\n", "> More provider guides coming soon." ] }, { "cell_type": "markdown", "id": "ed4b4431", "metadata": {}, "source": [ "## Next Steps\n", "\n", "You have now deployed the NVIDIA Deep Researcher Agent Blueprint and interacted with the chat-based agent. To continue this journey, checkout the [Github repo](https://github.com/NVIDIA-AI-Blueprints/deep-researcher-agent).\n", "\n", "**More notebooks**: We have walkthroughs of the deep researcher agent and its customization in the `docs/notebooks/` directory.\n", "\n", "**Customization Guide**: Check out the [customization guide](https://docs.nvidia.com/aiq-blueprint/latest/customization/index.html)." ] } ], "metadata": { "kernelspec": { "display_name": ".venv", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.13.3" } }, "nbformat": 4, "nbformat_minor": 5 }