---
title: "NVIDIA AI-Q Blueprint: Deep Research with Live Web Data"
slug: nvidia-ai-q-with-bright-data
date: 2026-11-19T09:34:08+00:00
modified: 2026-11-19T09:34:11+00:00
permalink: https://brightdata.com/blog/ai/nvidia-ai-q-with-bright-data
type: blog
---

[ Blog ](https://brightdata.com/blog "Blog") / [AI](https://brightdata.com/blog/ai)







 [AI](https://brightdata.com/blog/ai)

# NVIDIA AI-Q Blueprint: Deep Research with Live Web Data

Learn how to connect NVIDIA AI-Q to live web data with Bright Data’s SERP API and Web Unlocker API, and what each deep research report costs.

 21 min read





 [ ](https://brightdata.com/blog/authors/satyam-tripathi)

 [Satyam Tripathi

Technical Writer

 ](https://brightdata.com/blog/authors/satyam-tripathi)





 ![NVIDIA AI-Q With Bright Data](https://media.brightdata.com/2026/11/nvidia-ai-q-blueprint-deep-research-B-core-sample.png)





The [NVIDIA AI-Q Blueprint](https://github.com/NVIDIA-AI-Blueprints/deep-researcher-agent) is an open-source AI deep research agent. AI-Q plans a research job, runs researcher agents across web and enterprise data, and writes a citation-backed report. NVIDIA also lists AI-Q as the Deep Researcher Agent.

Each job gets a fixed budget of data source calls. A block page or a two-line SERP snippet costs a call but adds little evidence. A full page gives more evidence but can add navigation links as citable sources.

This guide shows what the AI-Q code expects from a search tool and how to give AI-Q live web data with Bright Data.

## TL;DR

- **NVIDIA AI-Q Blueprint `v2.2.1` gives each deep research job 100 data source calls, and a circuit breaker stops searching after 8 consecutive failed calls.** The config can lower both limits but not raise them.
- **AI-Q treats URLs in tool output as citable sources.** One Markdown page can add over 170 citable URLs.
- **AI-Q batches up to 4 queries by default for tools with one string argument.**
- **The Bright Data source you build returns page text and keeps one URL per document.** Live Google results come from the SERP API, and the Web Unlocker API handles CAPTCHAs and anti-bot challenges.

## How the NVIDIA AI-Q Blueprint runs a deep research job

AI-Q sends each request through an intent classifier first. Quick factual questions go to a shallow researcher. Questions that need a full report go to a deep researcher. The deep researcher splits the job across several agents. An optional source router suggests sources, a planner builds a research plan, researcher workers query the sources concurrently, and a writer produces the report. Before deep research starts, a clarifier agent can run a search and ask the user a clarifying question.

Agents get their tools from a data source registry in the workflow YAML. An agent with no explicit tool list inherits every tool in the registry, except the tools in its `exclude_tools` list. In `v2.2.1`, AI-Q includes 2 web search tools, and the default CLI config assigns them to different researchers:

Tool nameUsed byDefault setting`web_search_tool`Shallow researcher5 results per query, each limited to 1,000 characters`advanced_web_search_tool`Deep researcher2 results per queryA new search source can be a drop-in replacement for these 2 tools. If the new tools keep the same names, every agent setting that refers to them stays valid. AI-Q is built on the NeMo Agent Toolkit (NAT). For details on NAT functions and YAML configuration, see [our walkthrough of NVIDIA NeMo with Bright Data](/blog/ai/nvidia-nemo-with-bright-data).

## What the AI-Q code expects from a web search tool

The AI-Q source code has 4 behaviors that affect whether a search tool adds evidence or wastes the job’s budget. All 4 behaviors are in the [`aiq_agent` package](https://github.com/NVIDIA-AI-Blueprints/deep-researcher-agent/tree/v2.2.1/src/aiq_agent) at `v2.2.1`.

In `v2.2.1`, these limits apply to each deep research job. The settings sit under `deep_research_agent` in the workflow config:

LimitConfig settingDefaultConfig can raise itData source calls per job`resource_limits.max_source_tool_calls`100NoConsecutive failed results before the circuit breaker opens`resource_limits.max_consecutive_source_tool_failures`8NoWall-clock timeout per job`resource_limits.max_execution_seconds`1 hourNoConcurrent data source calls, all workers`max_concurrent_source_tool_calls`5YesQueries per batch`max_source_tool_batch_size`4Yes**A job gets 100 data source calls, and the config can lower that number but not raise it.** Every query that an agent sends to a search or data tool uses one of those calls. The AI-Q code and logs use the term source-tool calls. In `resource_limits.py`, the default of each limit is also its maximum. If you set `resource_limits.max_source_tool_calls` to 200, NAT rejects the whole workflow config before AI-Q starts:

```none
Invalid configuration: functions: Input should be less than or equal to 100
```

To lower the limit, set `max_source_tool_calls` under `resource_limits` in the deep research agent config:

```none
functions:
  deep_research_agent:
    resource_limits:
      max_source_tool_calls: 50
```

To raise one of the first 3 limits, change its `DEFAULT_MAX_*` constant in `resource_limits.py`, and reapply the change after AI-Q upgrades.

A call uses the same amount of budget whether it returns 2 short snippets or 5 full pages. Every call should return page text with a length limit that fits the researcher’s context window.

**By default, a circuit breaker stops searching for the rest of the job after 8 consecutive failed results.** AI-Q counts the result that a tool returns, not each HTTP retry inside the tool. Once the circuit breaker opens, each later query returns `Source request skipped because the source circuit is open.` An expired API key or a provider allowlist that blocks the server IP doesn’t crash the job, but the report has little web evidence.

To decide whether a call failed, AI-Q checks the text that the tool returns, not the HTTP status of the page. AI-Q classifies 5 common outputs this way:

Text that the tool returnedCounted as a failed call`Error: HTTP 403`Yes`{"status_code": 403}`Yes`Search returned no results`YesAn “Access Denied” HTML page (the site sent HTTP 403)NoA JavaScript challenge page (the site sent HTTP 200)NoThe last 2 rows show what a site with [anti-bot protection](/blog/ai/ai-agents-without-getting-blocked) can send to HTTP clients that it flags as bots. In both cases, the report gets no useful evidence from that page. If the tool returns a block page unchanged, AI-Q treats the block page as evidence. If the tool reports the block page as an error, the error counts toward the circuit breaker. A search tool avoids both outcomes when it returns the public page that a regular browser sees.

**Every URL in a tool’s output can become a citable source.** In `v2.2.1`, only knowledge-layer tools, which search your own documents, get a special parser that AI-Q selects by tool name. For other tools, AI-Q extracts every `http` and `https` URL from the result and adds each URL to the job’s citation registry. The citation registry is the list of URLs that the report may cite. The citation verifier later keeps any citation whose URL is in that registry.

[Pages converted to Markdown](/glossary/html-to-markdown) keep their links, so AI-Q registers navigation, footer, and related-article links as sources. A single survey report page fetched as Markdown can add more than 170 citable URLs.

Some navigation menus also trigger an extractor error. The AI-Q source extractor can raise `ValueError: Invalid IPv6 URL` when a menu uses multi-line Markdown links, such as `[\n\nDocs\n\n](https://docs.example.com)`. In `v2.2.1`, AI-Q runs that extractor without a `try` block, so the researcher worker for that query fails instead of recording a failed call. The job continues but loses the notes for that query. A safe pattern is to strip link URLs from page text and keep a single URL per document.

**A tool with a single string argument gets batch mode.** Before the deep researcher sees a source tool, AI-Q checks the input schema of the tool. If the only argument is a string, AI-Q wraps the tool so the model can send a batch of up to 4 queries by default. The queries run concurrently. Tools with more arguments get no batch mode. For a single-string tool, the model sees one list argument:

```none
advanced_web_search_tool -> model-facing args: ['queries']
```

Batching reduces the number of model calls. Batching doesn’t reduce budget use, because each query in a batch still uses one data source call.

**Together, the 4 behaviors define 3 design rules:**

- Return page text from several results, so each call adds evidence instead of a block page or a snippet.
- Keep a single URL in each document, so the citation registry gets one source per document.
- Take a single query, so AI-Q gives the tool batch mode.

## Install a pinned AI-Q release

Before you start, have these ready:

- Python 3.11 to 3.13 and `uv` 0.11.25 or newer
- An `NVIDIA_API_KEY` from [build.nvidia.com](https://build.nvidia.com)
- A Bright Data account with an API key, plus a zone for the SERP API and a zone for the Web Unlocker API. A zone is the named configuration that receives your requests.
- Network egress to `api.brightdata.com`, `www.google.com`, `google.com`, and `integrate.api.nvidia.com` (the NVIDIA model endpoints)
- If a zone uses an [IP allowlist](https://docs.brightdata.com/api-reference/account-management-api/allowlist-ip), the egress IP of your server on that allowlist

NVIDIA renamed the GitHub repository from `aiq` to `deep-researcher-agent`, and the `develop` branch also renames the Python package and the environment variable prefix.

Release `v2.2.1`, its container images, and its [AI-Q documentation](https://docs.nvidia.com/aiq-blueprint/2.2.1/index.html) still use the AI-Q names, so pin `v2.2.1` and follow every step below with that release. Clone that tag and run the setup script:

```none
git clone --branch v2.2.1 https://github.com/NVIDIA-AI-Blueprints/deep-researcher-agent.git aiq
cd aiq
./scripts/setup.sh
```

The setup script creates the `.venv` virtual environment, installs the main bundled data sources, and copies `deploy/.env.example` to `deploy/.env`.

The default config uses the `NVIDIA_API_KEY` for the hosted Nemotron models. Those hosted endpoints are subject to the [NVIDIA API trial terms](https://assets.ngc.nvidia.com/products/api-catalog/legal/NVIDIA%20API%20Trial%20Terms%20of%20Service.pdf), which allow NVIDIA to collect inputs and outputs to improve its products and models. Use the hosted endpoints to test AI-Q on public questions, and [self-host the models as NVIDIA NIM microservices](https://docs.nvidia.com/aiq-blueprint/2.2.1/examples/cli-with-local-nims.html) for confidential data.

## Build a Bright Data web search source for AI-Q

You can connect AI-Q to Bright Data in 2 ways. For page text, copy the NAT function below. The function follows the 3 design rules above and replaces both default web search tools. For questions that need structured records, the [Bright Data Model Context Protocol (MCP) server](/ai/mcp-server) adds pre-built scrapers without code.

The MCP server also has search and scrape tools for general agents. For AI-Q, the NAT function searches, reads the top pages, and keeps one URL per document in a single call.

Each call runs a live Google search through the Bright Data [SERP API](/products/serp-api) and fetches the top result pages through the [Web Unlocker API](/products/web-unlocker). The Web Unlocker API handles proxy rotation, browser fingerprints, CAPTCHA solving, and anti-bot challenges, and it returns each page as Markdown. The SERP API returns parsed JSON results. Because the Bright Data APIs do that work, the tool code can focus on the AI-Q design rules. The output follows the `<Document>` format of the bundled AI-Q search tools, so the rest of AI-Q needs no code changes. Here is the flow of one call:

For a security review, here is the data flow. The Bright Data source runs inside the AI-Q process as a NAT function, so it needs no separate service. User questions go to the model endpoint. The search queries that the agents write go to the SERP API, which runs them on Google or Bing. The Web Unlocker API then fetches the top result pages from their sites. Apart from the Bright Data APIs, the tool contacts only `www.google.com` and `google.com` to resolve Google redirect links. If your network restricts egress, allow both hosts. The [Bright Data Trust Center](/trustcenter) has the compliance reports and certifications for your vendor review, including SOC 2, ISO 27001, and ISO 27701.

### Create the Bright Data zones

[Create a free Bright Data account](/cp/start) and get an API key. You also need a zone for each API. The [free tier](https://docs.brightdata.com/general/account/billing-and-pricing/free-tier) includes monthly credits that you can use for the SERP API, Web Unlocker API, and Web Scraper API.

To create the zones, open **Web Access** in the control panel and select **Create API**, which opens the **Add API** page. On **Choose API type**, select **SERP API**, click **Continue**, and complete the **Configure API** and **Test API** steps. Repeat the flow for **Web Unlocker API**:

*Account details in the header are blurred.*

Copy the name of each new zone from the **Web Access** page. The smoke test and the `.env` file use both names.

### Create the package

The package registers one NAT function, `brightdata_web_search`. The config later creates 3 search tools from that function. Create the package next to the bundled sources, in the same directory layout:

```none
sources/brightdata_web_search/
├── pyproject.toml
└── src/
    ├── __init__.py
    ├── client.py
    └── register.py
```

NAT discovers the function through the `nat.plugins` entry point when a workflow starts:

```none
[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools >= 64"]

[tool.setuptools]
packages = ["brightdata_web_search"]
package-dir = {"brightdata_web_search" = "src"}

[project]
name = "brightdata-web-search"
version = "0.1.0"
description = "NAT web search source for NVIDIA AI-Q: Bright Data SERP API plus Web Unlocker API"
requires-python = ">=3.11,<3.14"
license = {text = "Apache-2.0"}
dependencies = ["httpx>=0.27", "pydantic>=2.0"]

[project.entry-points."nat.plugins"]
brightdata_web_search = "brightdata_web_search.register"
```

Leave `src/__init__.py` empty, and put the search, redirect, and fetch logic in `src/client.py`. Four parts of the file are designed for AI-Q behavior:

- `clean_markdown()` removes every link URL. The citation registry sees one URL per document, and menus can’t trigger the extractor error. Link text stays, so a researcher can still search for a linked source by name.
- `search()` [retries a failed request](/blog/web-data/retry-failed-requests-python) and can send the query to Bing through the same SERP API. Only the final result counts toward the circuit breaker.
- A minimum-length check detects pages with little text, such as a sign-in page. For those pages, the document keeps the SERP snippet instead of the page text. Without the check, the researcher would read a near-empty page as the evidence for that URL. If your sources often return longer notices, such as paywall teasers, raise `MIN_PAGE_CHARS` in `client.py`.
- An in-memory page cache with a 15-minute TTL shares fetched pages across the Bright Data search tools in one process. Researchers often find the same page through different queries, and a cached page sends no new request.

Here is `src/client.py`:

```none
"""Bright Data SERP API + Web Unlocker API client shaped for AI-Q.

One call searches, resolves the real result URLs, reads the top pages as
Markdown, and returns one <Document> block per result with one URL in it.
"""

import asyncio
import html
import re
import time
from collections import OrderedDict
from urllib.parse import urlencode, urlsplit

import httpx

API_URL = "https://api.brightdata.com/request"
# Google uses at most 32 words of a query, so cut long agent-written ones
MAX_QUERY_WORDS = 32
MIN_PAGE_CHARS = 600
RECENCY = {"hour": "h", "day": "d", "week": "w", "month": "m", "year": "y"}
# Researchers in one job often reach the same page. Every tool in the
# process shares fetched pages for 15 minutes, so a repeat sends no request.
PAGE_CACHE_SECONDS = 900
PAGE_CACHE_SIZE = 256
_pages: OrderedDict[str, tuple[float, str]] = OrderedDict()

_XML_INVALID = re.compile(
    r"[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff\ufffe\uffff]"
)
_MD_IMAGE = re.compile(r"!\[[^\]]*\]\([^)]*\)")
_MD_LINK = re.compile(
    r"\[([^\]]*)\]\((?:[^()\s]|\([^()\s]*\))*(?:\s+\"[^\"]*\")?\)"
)
_BARE_URL = re.compile(r"https?://\S+")
_LINK_ROW = re.compile(r"^[\s\-*•|>#]*(\[[^\]]*\]\([^)]*\)[\s|•·,/-]*)+$")

def _xml(value: object) -> str:
    text = _XML_INVALID.sub("", "" if value is None else str(value))
    return html.escape(text, quote=True)

def render_document(url: str, title: str, content: str) -> str:
    """The <Document> shape that AI-Q's bundled search tools return."""
    return (
        f'<Document href="{_xml(url)}">\n<title>\n{_xml(title)}\n</title>\n'
        f"{_xml(content)}\n</Document>"
    )

def clean_markdown(markdown: str, max_chars: int) -> str:
    """Keep the text, drop link URLs: each document keeps one URL."""
    rows = [r for r in markdown.splitlines() if not _LINK_ROW.match(r)]
    text = _MD_IMAGE.sub("", "\n".join(rows))
    text = _MD_LINK.sub(lambda m: " ".join(m.group(1).split()), text)
    text = _BARE_URL.sub("", text)
    text = re.sub(r"\n\s*\n+", "\n\n", text).strip()
    if len(text) > max_chars:
        text = text[: max_chars - 3] + "..."
    return text

class BrightDataSearchClient:
    def __init__(
        self,
        api_key: str,
        serp_zone: str,
        unlocker_zone: str | None,
        *,
        country: str = "us",
        recency: str = "any",
        max_retries: int = 2,
        timeout: float = 60.0,
    ):
        self._headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        }
        self.serp_zone, self.unlocker_zone = serp_zone, unlocker_zone
        self.country, self.recency = country, recency
        self.max_retries, self.timeout = max_retries, timeout

    def _search_url(self, engine: str, query: str) -> str:
        if engine == "bing":
            params = {"q": query, "cc": self.country, "brd_json": 1}
            return "https://www.bing.com/search?" + urlencode(params)
        params = {"q": query, "hl": "en", "gl": self.country, "brd_json": 1}
        if self.recency in RECENCY:
            params["tbs"] = "qdr:" + RECENCY[self.recency]
        return "https://www.google.com/search?" + urlencode(params)

    async def _post(self, http: httpx.AsyncClient, body: dict):
        return await http.post(
            API_URL, headers=self._headers, json=body, timeout=self.timeout
        )

    async def search(self, http: httpx.AsyncClient, query: str) -> list[dict]:
        """Retry here, then try Bing. AI-Q counts the tool's result,
        not each HTTP attempt inside it."""
        query = " ".join(query.split()[:MAX_QUERY_WORDS])
        last_error = "no response"
        # The recency filter is a Google parameter, so filtered searches
        # use Google only
        engines = ("google",) if self.recency in RECENCY else ("google", "bing")
        for engine in engines:
            for attempt in range(self.max_retries):
                url = self._search_url(engine, query)
                body = {"zone": self.serp_zone, "url": url, "format": "raw"}
                try:
                    resp = await self._post(http, body)
                except httpx.HTTPError as exc:
                    last_error = type(exc).__name__
                    await asyncio.sleep(1.5 * (attempt + 1))
                    continue
                # The SERP API reports request errors in x-brd-* headers
                error = resp.headers.get("x-brd-error", "")
                if resp.status_code != 200:
                    error = error or f"HTTP {resp.status_code}"
                if "ip_forbidden" in error or resp.status_code in (401, 403):
                    raise RuntimeError(f"{self.serp_zone} refused: {error}")
                if not error:
                    try:
                        return resp.json().get("organic", [])
                    except ValueError:
                        error = "response was not JSON"
                last_error = error
                # Try the next engine instead of repeating this query
                if "recently failed" in error:
                    break
                await asyncio.sleep(1.5 * (attempt + 1))
        raise RuntimeError(f"search failed ({last_error})")

    async def resolve(self, http: httpx.AsyncClient, link: str) -> str | None:
        """Google can wrap result links in google.com/goto redirects.
        Cite the destination page."""
        parts = urlsplit(link)
        on_google = parts.hostname in ("google.com", "www.google.com")
        if not on_google or parts.path != "/goto":
            return link
        try:
            resp = await http.get(link, follow_redirects=False, timeout=15)
        except httpx.HTTPError:
            return None
        location = resp.headers.get("location", "")
        if location.startswith("http") and "google.com/" not in location:
            return location
        return None

    async def fetch_markdown(
        self, http: httpx.AsyncClient, url: str
    ) -> str | None:
        body = {
            "zone": self.unlocker_zone,
            "url": url,
            "format": "raw",
            "data_format": "markdown",
        }
        hit = _pages.get(url)
        if hit and time.monotonic() - hit[0] < PAGE_CACHE_SECONDS:
            return hit[1]
        for attempt in range(self.max_retries):
            try:
                resp = await self._post(http, body)
            except httpx.HTTPError:
                await asyncio.sleep(1.5 * (attempt + 1))
                continue
            target = int(resp.headers.get("x-brd-status-code") or 200)
            if resp.status_code == 200 and target < 400 and resp.text.strip():
                _pages[url] = (time.monotonic(), resp.text)
                _pages.move_to_end(url)
                if len(_pages) > PAGE_CACHE_SIZE:
                    _pages.popitem(last=False)
                return resp.text
            if resp.status_code < 500 and resp.status_code != 429:
                return None
            await asyncio.sleep(1.5 * (attempt + 1))
        return None

    async def research(
        self,
        query: str,
        *,
        max_results: int,
        fetch_top_k: int,
        max_content_length: int,
    ) -> str:
        async with httpx.AsyncClient() as http:
            results, seen = [], set()
            for item in await self.search(http, query):
                link = item.get("link") or ""
                url = None
                if link.startswith("http"):
                    url = await self.resolve(http, link)
                if not url or url in seen:
                    continue
                seen.add(url)
                results.append(
                    {
                        "url": url,
                        "title": item.get("title", ""),
                        "snippet": item.get("description", ""),
                    }
                )
                if len(results) == max_results:
                    break
            if not results:
                return "Search returned no results"

            k = fetch_top_k if self.unlocker_zone else 0
            pages = await asyncio.gather(
                *(self.fetch_markdown(http, r["url"]) for r in results[:k])
            )
            docs = []
            for i, r in enumerate(results):
                page = pages[i] if i < k else None
                text = clean_markdown(page, max_content_length) if page else ""
                # A page with almost no text is not evidence. Keep the snippet,
                # cleaned the same way, so each document keeps one URL.
                if len(text) < MIN_PAGE_CHARS:
                    text = clean_markdown(r["snippet"], max_content_length)
                title = clean_markdown(r["title"], max_content_length)
                docs.append(render_document(r["url"], title, text))
            return "\n\n---\n\n".join(docs)
```

`resolve()` replaces each Google redirect link with its destination URL, so every document that the tool returns cites the source page directly. If you want to limit sources to an allowlist of domains, filter `results` in `research()` before the `if not results` check. Include enough domains in the allowlist for your questions, because a call with no results left after the filter counts as a failed call.

Next, `src/register.py` registers the client as a NAT function with a single string argument, so AI-Q gives the function the batch wrapper:

```none
"""NeMo Agent Toolkit registration for the Bright Data web search source."""

import logging
import os
from typing import Literal

from pydantic import Field
from pydantic import SecretStr

from nat.builder.builder import Builder
from nat.builder.function_info import FunctionInfo
from nat.cli.register_workflow import register_function
from nat.data_models.function import FunctionBaseConfig

from .client import BrightDataSearchClient

logger = logging.getLogger(__name__)

class BrightDataWebSearchConfig(
    FunctionBaseConfig, name="brightdata_web_search"
):
    """Live search results from the Bright Data SERP API, with the top
    pages read through the Bright Data Web Unlocker API."""

    api_key: SecretStr | None = Field(
        default=None, description="Falls back to BRIGHTDATA_API_KEY."
    )
    serp_zone: str = Field(description="SERP API zone name.")
    unlocker_zone: str | None = Field(
        default=None, description="Web Unlocker zone. Unset: snippets only."
    )
    max_results: int = Field(default=5, ge=1, le=10)
    fetch_top_k: int = Field(default=3, ge=0, le=10)
    max_content_length: int = Field(default=6000, ge=1000)
    country: str = Field(default="us")
    recency: Literal["any", "hour", "day", "week", "month", "year"] = "any"
    max_retries: int = Field(default=2, ge=1, le=5)
    timeout: float = Field(
        default=60.0, ge=5, le=300, description="Seconds per HTTP request."
    )

@register_function(config_type=BrightDataWebSearchConfig)
async def brightdata_web_search(
    config: BrightDataWebSearchConfig, builder: Builder
):
    api_key = os.environ.get("BRIGHTDATA_API_KEY")
    if config.api_key:
        api_key = config.api_key.get_secret_value()

    if not api_key:
        logger.warning("BRIGHTDATA_API_KEY is not set")

        async def _unavailable(question: str) -> str:
            """Web search (unavailable: BRIGHTDATA_API_KEY is not set)."""
            return "Error: BRIGHTDATA_API_KEY is not set."

        yield FunctionInfo.from_fn(
            _unavailable, description=_unavailable.__doc__
        )
        return

    client = BrightDataSearchClient(
        api_key,
        config.serp_zone,
        config.unlocker_zone,
        country=config.country,
        recency=config.recency,
        max_retries=config.max_retries,
        timeout=config.timeout,
    )

    async def _search(question: str) -> str:
        """Searches the live web and reads the top result pages. Use it for
        current facts, figures, prices, and recent announcements.

        Args:
            question (str): One focused search query of 32 words or fewer.

        Returns:
            str: One <Document href="..."> block per result.
        """
        try:
            return await client.research(
                question,
                max_results=config.max_results,
                fetch_top_k=config.fetch_top_k,
                max_content_length=config.max_content_length,
            )
        except Exception as exc:
            # AI-Q counts a result that starts with "Error:" as a failed call
            return f"Error: web search failed: {exc}"

    yield FunctionInfo.from_fn(_search, description=_search.__doc__)
```

### Install and check the package

Install the package into the AI-Q virtual environment:

```none
uv pip install -e ./sources/brightdata_web_search
```

**Rerun this install after every `uv sync`.** The sync resets the environment to `uv.lock` and removes the editable install. For the container image, add `uv pip install --no-deps -e ./sources/brightdata_web_search` to the `RUN` step in `deploy/Dockerfile` that installs the bundled sources.

To smoke-test the function without starting AI-Q, save this script as `check_source.py`. The script builds the function with NAT, calls the function like an agent, and sends the output to the AI-Q source extractor:

```none
import asyncio
import os

from aiq_agent.common.citation_verification import (
    extract_sources_from_tool_result,
)
from nat.builder.workflow_builder import WorkflowBuilder
from nat.runtime.loader import PluginTypes
from nat.runtime.loader import discover_and_register_plugins

from brightdata_web_search.register import BrightDataWebSearchConfig

QUESTION = "GB300 NVL72 lead times for enterprise buyers"

async def main():
    discover_and_register_plugins(PluginTypes.ALL)
    config = BrightDataWebSearchConfig(
        serp_zone=os.environ["BRIGHTDATA_SERP_ZONE"],
        unlocker_zone=os.environ["BRIGHTDATA_UNLOCKER_ZONE"],
    )
    async with WorkflowBuilder() as builder:
        await builder.add_function("advanced_web_search_tool", config)
        tool = await builder.get_tool(
            "advanced_web_search_tool", wrapper_type="langchain"
        )
        args = tool.tool_call_schema.model_json_schema()["properties"]
        print("arguments:", list(args))

        output = await tool.ainvoke({"question": QUESTION})
        for doc in output.split("\n\n---\n\n"):
            print(doc.splitlines()[0][:72], f"{len(doc):,} chars")

        sources = extract_sources_from_tool_result(
            "advanced_web_search_tool", output
        )
        print(output.count("<Document "), "documents,", len(sources), "sources")

asyncio.run(main())
```

Export `BRIGHTDATA_API_KEY`, `BRIGHTDATA_SERP_ZONE`, and `BRIGHTDATA_UNLOCKER_ZONE` in your shell. Then run the script from the AI-Q repository root with `.venv/bin/python check_source.py`, which prints output like this:

```none
arguments: ['question']
<Document href="https://verda.com/blog/nvidia-gb300-nvl72-early-adopters 5,981 chars
<Document href="https://www.investing.com/news/company-news/coreweave-be 6,258 chars
<Document href="https://www.linkedin.com/posts/sonic-components-32511620 6,214 chars
<Document href="https://discover.vultr.com/cloud-gpu-gb300-nvl72-datashe 271 chars
4 documents, 4 sources
```

AI-Q replaces the `question` argument with the `queries` list for batch mode. The first 3 documents contain page text from the Web Unlocker API, and `max_content_length` limits each page to 6,000 characters. Each printed length also includes the title and the `<Document>` tags. The fourth document is a SERP snippet, because `fetch_top_k` is set to 3. The tool skips results that it can’t cite or that repeat a URL, so a run can return fewer than 5 documents. The script prints the first 72 characters of each document’s first line. Live results also change between runs, so your URLs can differ. In every run, the document and source counts on the last line should match. Matching counts mean that every citable URL belongs to a document that the tool returned.

If a zone uses an IP allowlist, a missing server IP shows in this output. A SERP API zone that blocks the IP returns an `Error:` line that names the zone. A Web Unlocker API zone that blocks the IP leaves every document as a short SERP snippet.

## Configure AI-Q and run a deep research job

In `deploy/.env`, set the NVIDIA API key and add the Bright Data credentials:

```none
NVIDIA_API_KEY=your_nvidia_api_key
BRIGHTDATA_API_KEY=your_bright_data_api_key
BRIGHTDATA_SERP_ZONE=your_serp_zone
BRIGHTDATA_UNLOCKER_ZONE=your_unlocker_zone
```

Copy `configs/config_cli_default.yml` to `configs/config_cli_brightdata.yml`. The replacement below adds a third tool, `recent_web_search_tool`, which filters results to the past week with a [Google search URL parameter](/blog/web-data/google-search-url-parameters). The data source registry gets a new source named `web_search_recent` for the new tool.

Under `functions`, replace the `data_sources`, `web_search_tool`, and `advanced_web_search_tool` entries with the following:

```none
functions:
  data_sources:
    _type: data_source_registry
    sources:
      - id: web_search
        name: "Web Search"
        description: "Search the live web and read the top result pages."
        tools:
          - web_search_tool
          - advanced_web_search_tool
      - id: web_search_recent
        name: "Web Search (past week)"
        description: "Search pages from the past week."
        tools:
          - recent_web_search_tool

  web_search_tool:
    _type: brightdata_web_search
    serp_zone: ${BRIGHTDATA_SERP_ZONE}
    unlocker_zone: ${BRIGHTDATA_UNLOCKER_ZONE}
    fetch_top_k: 1
    max_content_length: 2000

  advanced_web_search_tool:
    _type: brightdata_web_search
    serp_zone: ${BRIGHTDATA_SERP_ZONE}
    unlocker_zone: ${BRIGHTDATA_UNLOCKER_ZONE}
    fetch_top_k: 3
    max_content_length: 6000

  recent_web_search_tool:
    _type: brightdata_web_search
    serp_zone: ${BRIGHTDATA_SERP_ZONE}
    unlocker_zone: ${BRIGHTDATA_UNLOCKER_ZONE}
    recency: week
```

With this config, each tool returns up to 5 results per query. The other settings differ by tool:

ToolUsed byPages fetchedText per pageRecencyBilled requests per query`web_search_tool`Shallow researcherTop pageUp to 2,000 charactersAny timeUp to 2`advanced_web_search_tool`Deep researcherTop 3 pagesUp to 6,000 charactersAny timeUp to 4`recent_web_search_tool`Both researchersTop 3 pagesUp to 6,000 charactersPast weekUp to 4The shallow researcher is the fast path, so its tool fetches only the top page. Results without a page fetch keep their SERP snippets. The existing `exclude_tools` lists limit each researcher to its own tool, so the agent settings need no changes. Because no list includes `recent_web_search_tool`, both researchers can use the past-week tool.

At these settings, one deep research query can return up to about 19,000 characters. A full batch of 4 queries can add about 76,000 characters, or roughly 20,000 tokens, to the researcher’s context window. Lower `fetch_top_k` or `max_content_length` if prompt tokens matter more than page coverage.

To get search results for another country, set the `country` field of a tool, such as `country: de` for Germany. The tool also sends `hl=en`, which sets the Google interface language to English. To change it, edit `hl` in `_search_url()` in `client.py`.

Start the CLI with the new config:

```none
./scripts/start_cli.sh --config_file configs/config_cli_brightdata.yml
```

To confirm that each document still contains a single URL, watch the log during a deep research run. AI-Q logs `[CitationRegistry] Captured N source(s) from advanced_web_search_tool` once for each batch that returns sources. With the default batch size, a batch contains up to 4 queries with up to 5 results each, so N should stay at or below 20. A much larger N means that page links are still added to the citation registry.

### What to expect from an AI-Q run

In 3 test runs on the NVIDIA trial endpoints, a question about GB300 NVL72 availability took 13 to 27 minutes. The runs used 44 to 83 of the 100 data source calls. In the 27-minute run, the report cited 58 URLs from 35 domains, and each URL linked directly to its source page.

The NVIDIA trial endpoints also enforce rate limits. When many agents call the model at once, the NVIDIA model API can return HTTP 429 (Too Many Requests). If the writer step exhausts its retries, the job ends without a report. For long or concurrent jobs, self-host the models as NVIDIA NIM microservices.

The AI-Q citation verifier finds the source list by its heading. If the AI-Q writer uses a numbered heading, such as `## 8. Sources`, the verifier logs `No source section found`. The verifier then appends a second `## Sources` list with the source URLs. In the test runs, the list under the numbered heading had citation numbers instead of URLs. If a report ends with 2 source lists, post-process the report to remove the list that has no URLs.

### Run AI-Q in web mode

The web UI and the REST API run together from `./scripts/start_e2e.sh`, which loads `configs/config_web_default_llamaindex.yml` by default. Edit that file, and keep its `knowledge_layer` source under `data_sources`. Then copy 3 changes from the CLI config. Add the `web_search_recent` source to `data_sources`, replace both tool entries, and add `recent_web_search_tool`.

The web UI runs at `http://localhost`. In the **Data Sources** panel, the 2 web search sources appear as **Web Search** and **Web Search (past week)**. Both sources are enabled by default, and users can toggle each source per message:

*Both sources run the `brightdata_web_search` function that you built, and the past-week source adds a recency filter.*

To run headless jobs, submit them through the REST API. A job whose request body has no `data_sources` field gets every registry source, so list only the sources you want. This request limits a job to the past-week source:

```none
curl -X POST http://localhost:8000/v1/jobs/async/submit \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "deep_researcher",
    "input": "How have GB300 NVL72 lead times changed for enterprise buyers this quarter?",
    "data_sources": ["web_search_recent"]
  }'
```

The response contains a job ID. `GET /v1/jobs/async/job/{job_id}/state` then returns the job’s outputs, every source URL that the tools found, and the URLs that the report cites. Use the state endpoint to audit the cited pages before you share a report.

In the web UI, the **Report** tab ends each finished report with the same list of cited URLs. A separate web-mode run on GB300 NVL72 lead times cited 60 URLs from 44 domains, and each source had a direct link to its page:

*The chat column is dimmed, and one URL is blurred for privacy.*

## What a deep research report costs in web requests

With the search tools above, the 100-call budget sets the maximum web cost of the deep research phase. Bright Data bills only successful requests. Each search call is billed for at most 1 SERP API request. A search call from the deep researcher is also billed for up to 3 Web Unlocker API requests. At 100 calls, the deep research phase uses at most 400 billable requests. Clarifier searches don’t count toward the 100-call budget, so they can add requests above that limit. A REST job with `agent_type` set to `deep_researcher` makes no clarifier searches, because it runs the deep researcher directly. The current rates are on the [SERP API pricing page](/pricing/serp) and the [Web Unlocker API pricing page](/pricing/web-unlocker).

In the 27-minute GB300 NVL72 run, the job made 175 billed requests. Of those, 55 were SERP API requests and 120 were Web Unlocker API requests. The page cache handled 14 more page fetches without sending a request. The same job sent 2.56 million prompt tokens to Nemotron 3 Ultra. Multiply the request and token counts by your current rates to see what one report costs.

To track both costs in one place, use the [AI-Q tokenomics report](https://docs.nvidia.com/aiq-blueprint/2.2.1/profiling/index.html), which builds a cost report from `nat eval` profiler traces. The report assigns $0 to any tool that matches no key in its pricing YAML, so add the 3 search tools under `tokenomics.pricing.tools`. Set each `cost_per_call` to the price of one query. One query uses 1 SERP API request plus 1 Web Unlocker API request for each page that the tool fetches:

```none
tokenomics:
  pricing:
    tools:
      # USD per query. Replace each 0.0 with your current rates.
      web_search_tool:           # 1 SERP API + 1 Web Unlocker API request
        cost_per_call: 0.0
      advanced_web_search_tool:  # 1 SERP API + 3 Web Unlocker API requests
        cost_per_call: 0.0
      recent_web_search_tool:    # 1 SERP API + 3 Web Unlocker API requests
        cost_per_call: 0.0
```

Use the full tool names as keys. The report checks for an exact name first and then matches keys as substrings. If you start from the AI-Q sample pricing file, its `web_search` key gives all 3 tools one price unless you add these keys. Some queries fetch fewer pages, so the report gives an upper bound for web cost. For exact billed counts, check the zone usage in the Bright Data control panel.

## Add the Bright Data pre-built scrapers through MCP

Some research questions need a field as the answer, such as a price, a rating, or an employee count. Bright Data has [pre-built scrapers](/products/web-scraper) for public pages on sites such as Amazon and LinkedIn. The scrapers return those fields as structured records instead of page text. Bright Data maintains these scrapers, so you don’t write or update parsing code for those sites.

AI-Q loads MCP tools through a NAT function group of type `mcp_client`. The function group is one YAML entry and needs no code. The Bright Data MCP server lets you select tools from its [tool list](https://docs.brightdata.com/products/mcp-server/tools) with the `tools` and `groups` query parameters. Load only the tools that the agent needs, because an agent sends every tool schema with each model call. Create a separate Bright Data [Agent API key](https://docs.brightdata.com/api-reference/authentication) for AI-Q in **Account settings**. Set the MCP URL in `deploy/.env` with that key and only the scraper tools:

```none
BRIGHTDATA_MCP_URL="https://mcp.brightdata.com/mcp?token=your_agent_api_key&tools=search_scrapers,get_scraper_details,run_scraper,get_scraper_progress,get_scraper_results"
```

Give AI-Q logs the same access controls as the key, because [NAT logs the full MCP server URL](https://github.com/NVIDIA/NeMo-Agent-Toolkit/blob/v1.8.0/packages/nvidia_nat_mcp/src/nat/plugins/mcp/client/client_impl.py) when a workflow starts. Set an expiration date on the agent key. Because only AI-Q uses the agent key, you can rotate the agent key without changing your other keys. If your network restricts egress, also allow `mcp.brightdata.com`. Next, add the function group and a matching entry in the data source registry:

```none
function_groups:
  brightdata_mcp:
    _type: mcp_client
    server:
      transport: streamable-http
      url: ${BRIGHTDATA_MCP_URL}

functions:
  data_sources:
    _type: data_source_registry
    sources:
      # web_search and web_search_recent entries stay as they are
      - id: brightdata_scrapers
        name: "Bright Data scrapers"
        description: "Structured records from pre-built scrapers, such as Amazon products and public LinkedIn company pages."
        tools:
          - brightdata_mcp
```

At startup, AI-Q logs a line such as `Found available tool: brightdata_mcp__run_scraper` for each loaded tool, so check that all 5 tools appear.

To get a record, the agent finds a scraper with `search_scrapers`, reads the scraper input schema with `get_scraper_details`, and starts the scraper with `run_scraper`. For longer runs, the agent also polls progress with `get_scraper_progress` and fetches the records with `get_scraper_results`. AI-Q counts these calls toward the same 100-call budget as search. Bright Data bills the pre-built scrapers per delivered record, at the rates on the [Web Scraper API pricing page](/pricing/web-scraper).

In one test, the question asked for the price, star rating, and review count of a product on Amazon. The shallow researcher chose the scrapers automatically and answered from one Amazon record:

*The thinking trace shows each source by its registry ID, so `brightdata_scrapers` appears as **Brightdata Scrapers**.*

## Final thoughts

The NVIDIA AI-Q Blueprint gives each deep research job a fixed budget of data source calls and treats tool output as evidence. A web search source for AI-Q should return more evidence per call and give the citation registry one URL per document. The Bright Data source meets both goals by adding Web Unlocker API page text to live SERP API results and stripping link URLs. The Bright Data MCP server also adds pre-built scrapers for questions where a structured record is more useful than page text. Create a free Bright Data account, add the source to a pinned AI-Q release, and rerun a question that your team already answered manually.

## FAQ

### What is NVIDIA AI-Q?

NVIDIA AI-Q is an open-source NVIDIA AI Blueprint for AI deep research agents, built on the NeMo Agent Toolkit. AI-Q routes each question to a fast shallow researcher or to a multi-agent deep researcher that plans, searches, and writes a citation-backed report. NVIDIA also lists AI-Q as the Deep Researcher Agent.

### What are NVIDIA AI Blueprints?

NVIDIA AI Blueprints are reference workflows with code samples for AI applications. Many blueprints on build.nvidia.com are agents, such as the Deep Researcher Agent (AI-Q), a video search and summarization agent, and a voice agent. Blueprints can run on NVIDIA-hosted model endpoints or self-hosted NIM microservices.

### Is NVIDIA AI-Q free?

The AI-Q code is free under the Apache 2.0 license. NVIDIA’s hosted model endpoints are for trial use only, so production needs paid or self-hosted model inference. For live web data, the Bright Data free tier includes monthly credits for the SERP API and the Web Unlocker API.

### Where is the NVIDIA AI-Q blueprint on GitHub?

The code is at github.com/NVIDIA-AI-Blueprints/deep-researcher-agent, and the old aiq repository URL redirects there. Release `v2.2.1` uses the `aiq_agent` package and the `AIQ_` variable prefix, while `develop` renamed them to `deep_researcher_agent` and `DEEP_RESEARCHER_`. Pin a release tag before you add custom data sources.

### Does a deep research agent need a web search API key?

Yes, the bundled AI-Q web search tools need a search provider API key and return an error until the key is set. Microsoft retired the Bing Search APIs in 2025, and Google scheduled the end of its [Custom Search JSON API](/blog/web-data/google-search-api) for January 1, 2027. A Bright Data API key covers both the SERP API and the Web Unlocker API.



Contact usStart for free

No credit card required











 [ ](https://www.linkedin.com/in/triposat/)

Satyam Tripathi

 Technical Writer



  5 years experience



Satyam Tripathi helps SaaS and data startups turn complex tech into actionable content, boosting developer adoption and user understanding.



Expertise

  Python   Developer Education   Technical Writing



 [ View all articles ](https://brightdata.com/blog/authors/satyam-tripathi)











 Table of Contents







Data for AI

Supercharge your AI with instant and reliable access to web data. No blockers. No hassle.

Talk to an expert

Bright Data MCP

Get started with Bright Data’s Web MCP Server today with 5000 free monthly requests and unlock your AI’s full potential.

Start free now







 [ ](https://news.ycombinator.com/submitlink?t=NVIDIA+AI-Q+Blueprint%3A+Deep+Research+with+Live+Web+Data&u=https://brightdata.com/blog/ai/nvidia-ai-q-with-bright-data) [ ](https://www.linkedin.com/shareArticle?mini=true&title=NVIDIA+AI-Q+Blueprint%3A+Deep+Research+with+Live+Web+Data&url=https://brightdata.com/blog/ai/nvidia-ai-q-with-bright-data) [ ](http://www.reddit.com/submit?title=NVIDIA+AI-Q+Blueprint%3A+Deep+Research+with+Live+Web+Data&url=https://brightdata.com/blog/ai/nvidia-ai-q-with-bright-data)







##  You might also be interested in

 [ ](https://brightdata.com/blog/ai/browserbase-alternatives "Browserbase Alternatives: 9 Competitors Compared (2026)")

 [AI





Satyam Tripathi

Technical Writer





### Browserbase Alternatives: 9 Competitors Compared (2026)

Compare 9 Browserbase alternatives on idle-time billing, exit IPs, fingerprints, and latency, with hands-on tests. Bright Data ranks first.



 19-Nov-2026

 25 min read

 ](https://brightdata.com/blog/ai/browserbase-alternatives)

 [ ](https://brightdata.com/blog/ai/codex-and-chatgpt-with-bright-data "Bright Data Plugin for Codex and ChatGPT: Live Web Search")

 [AI





Satyam Tripathi

Technical Writer





### Bright Data Plugin for Codex and ChatGPT: Live Web Search

Learn how to install the Bright Data plugin once and use it in ChatGPT and Codex for live web search, dependency checks, and JSON-LD scrapers.



 19-Nov-2026

 9 min read

 ](https://brightdata.com/blog/ai/codex-and-chatgpt-with-bright-data)

 [ ](https://brightdata.com/blog/ai/best-mcp-gateways "The 10 Best MCP Gateways in 2026")

 [AI





Arindam Majumder

Technical Writer





### The 10 Best MCP Gateways in 2026

The 10 best MCP gateways in 2026, compared on auth, tool-level access control, audit logs, deployment, and pricing. Composio ranks first.



 17-Nov-2026

 18 min read

 ](https://brightdata.com/blog/ai/best-mcp-gateways)
