> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NVIDIA AI-Q

> Nimble ships as a built-in web search tool in the NVIDIA AI-Q Blueprint: live web context for enterprise research agents, configured in one YAML block.

### Overview

The [NVIDIA AI-Q Blueprint](https://github.com/NVIDIA-AI-Blueprints/aiq) is an open reference implementation for enterprise research agents. It connects agents to internal data, reasons over it with NVIDIA-served models, and returns sourced business insight. It runs on the NeMo Agent Toolkit, so its tools are `nat` functions declared in a workflow YAML.

Nimble ships as the `nimble_web_search` function, a built-in data-source plugin. Calls go to Nimble's [Search API](/nimble-sdk/web-tools/search) and come back as `<Document>` blocks the agent can cite. No fork, no custom tool code.

The provider ships in **AI-Q v2.2.0 and later**.

### What the integration unlocks

Any AI-Q agent gains live web retrieval without tool-specific code. The model passes a natural-language question, and the provider returns ranked results as escaped XML:

```xml theme={"system"}
<Document href="https://docs.nvidia.com/cuda/">
<title>
CUDA Toolkit Documentation
</title>
Find installation instructions, launch highlights, programming guides, compiler
documentation, API references, CUDA libraries, profiling tools, samples, and ...
</Document>
```

Every block carries an absolute `href`, and the provider drops results without one. Nimble handles anti-bot evasion, JavaScript rendering, and geo-targeting underneath.

### Quick Start

#### 1. Get a Nimble API key

Get your API key from [Nimble's dashboard](https://online.nimbleway.com/settings/api-keys) (free trial available) and export it in the environment AI-Q runs in:

```bash theme={"system"}
export NIMBLE_API_KEY="your-api-key"
```

<Note>
  Set this before starting AI-Q. Without it the tool still registers and logs one
  warning, then returns an error the first time the agent searches. Startup looks
  healthy while the agent cannot search, so treat that warning as a failure.
</Note>

#### 2. Install AI-Q with the provider

```bash theme={"system"}
git clone https://github.com/NVIDIA-AI-Blueprints/aiq.git && cd aiq
./scripts/setup.sh
```

`setup.sh` creates the virtual environment and installs every data-source plugin, `nimble_web_search` included.

To add it to a checkout you already have:

```bash theme={"system"}
uv pip install -e ./sources/nimble_web_search
```

#### 3. Add the function to your workflow

Declare `nimble_web_search` under `functions` in your workflow YAML:

```yaml theme={"system"}
functions:
  web_search_tool:
    _type: nimble_web_search
    max_results: 5
    search_depth: lite
    country: US
    locale: en
```

Then reference `web_search_tool` from the agent that should search.

#### 4. Confirm the tool registered

```bash theme={"system"}
nat info components --types function | grep nimble_web_search
```

A row for `nimble_web_search` means the plugin entry point resolved.

### Configuration

<AccordionGroup>
  <Accordion title="api_key" icon="key">
    **Optional in config, required in practice.** Falls back to the `NIMBLE_API_KEY` environment variable. A key set here is passed straight to the SDK and never written to the process environment.
  </Accordion>

  <Accordion title="max_results" icon="list-ol">
    **Optional.** Results to return, `1` to `100`. Defaults to `5`. Sent unclamped, so Nimble validates the range and reports the error.
  </Accordion>

  <Accordion title="search_depth" icon="layer-group">
    **Optional.** `lite`, `fast`, or `deep`. Defaults to `lite`.

    * `lite`: title, URL, and description only. Lowest latency and lowest token cost.
    * `fast`: rich content at low latency, and the depth Nimble recommends for agent loops.
    * `deep`: full page content per result. Returns the raw page, including navigation and image data, so pair it with `max_content_length`.

    See [Search Depth](/nimble-sdk/web-tools/search-depth) for the tradeoffs and [Pricing](/nimble-sdk/admin/pricing) for what each depth costs.
  </Accordion>

  <Accordion title="focus" icon="bullseye">
    **Optional.** Defaults to `general`. Leave it there for research and general agent use.

    The provider accepts `general`, `news`, `location`, `shopping`, `geo`, and `social`, and validates the value at config load, so a typo surfaces at startup with the valid set named in the error.

    `focus` is a workflow setting, not an agent-chosen parameter. The model only supplies a query, so a general research question cannot silently reroute.
  </Accordion>

  <Accordion title="max_content_length" icon="scissors">
    **Optional.** Characters kept per result, truncated with an ellipsis. Defaults to `10000`. Set to `None` to disable truncation. Matters most with `search_depth: deep`.
  </Accordion>

  <Accordion title="max_retries" icon="rotate">
    **Optional.** Attempts on a transient failure, `1` to `10`. Defaults to `3`, with exponential backoff capped at 30 seconds. Authentication and authorization errors return immediately instead of retrying.
  </Accordion>

  <Accordion title="country and locale" icon="globe">
    **Optional.** `country` is an ISO 3166 code for geo-targeted results, default `US`. `locale` is a language code, default `en`.
  </Accordion>
</AccordionGroup>

NVIDIA maintains the full parameter table in its own [configuration reference](https://docs.nvidia.com/aiq-blueprint/latest/customization/configuration-reference.html#nimble-web-search).

### Additional Resources

<CardGroup cols={2}>
  <Card title="AI-Q Configuration Reference" icon="book-open" href="https://docs.nvidia.com/aiq-blueprint/latest/customization/configuration-reference.html#nimble-web-search">
    NVIDIA's own parameter table for `nimble_web_search`.
  </Card>

  <Card title="AI-Q on GitHub" icon="github" href="https://github.com/NVIDIA-AI-Blueprints/aiq">
    The blueprint, the provider source, and its tests.
  </Card>

  <Card title="Nimble Search API" icon="magnifying-glass" href="/api-reference/search/search">
    The endpoint behind the provider: parameters and response format.
  </Card>

  <Card title="Nimble MCP Server" icon="plug" href="/integrations/mcp-server/mcp-server">
    Reach Extract, Map, and Crawl over the Model Context Protocol.
  </Card>
</CardGroup>