← Agent Frameworks 🕐 18 min read
Agent Frameworks

NVIDIA AI-Q Blueprint: Enterprise Deep Research Agent Architecture

Brandon Sneider · May 2026

> **Source credibility:** TIER 2 — vendor-produced technical documentation from NVIDIA. Architecture claims are reproducible via Apache-2.0 open-source code at `NVIDIA-AI-Blueprints/aiq`.

See also (wiki): wiki/agentic-ai-governance.md · wiki/hitl-deployment-pattern.md · wiki/mlops-ai-platform-engineering.md · wiki/token-economics.md · wiki/inference-economics.md

Source credibility: TIER 2 — vendor-produced technical documentation from NVIDIA. Architecture claims are reproducible via Apache-2.0 open-source code at NVIDIA-AI-Blueprints/aiq. Benchmark results (DeepResearch Bench, FreshQA, DeepSearchQA) use public third-party evaluation datasets with independently verifiable methodology. No independent n= survey data. Performance claims on external leaderboards are reproducible via tagged branches (drb1, drb2).

Overview

The NVIDIA AI-Q Blueprint is an enterprise-grade research agent published in 2025–2026 as an open-source reference implementation under Apache 2.0. It is built on the NVIDIA NeMo Agent Toolkit (NAT) and LangChain DeepAgents / LangGraph. The system handles both rapid Q&A and multi-hour deep research reports from a single endpoint, with evaluation harnesses included for continuous quality measurement.

The stated design goal is to give enterprise teams a production path to multi-agent research without building orchestration from scratch — a reference implementation rather than a SaaS product.

System Architecture: 4-Stage Pipeline

Stage 1: Intent Classification

Every query enters through a single Intent Classifier node. This is a single LLM call (not a pipeline) that simultaneously:

  • Classifies intent: meta (greeting, capability query) vs. research
  • Sets research depth: shallow vs. deep

The model assigned to this role in the default config is nvidia/nemotron-3-nano-30b-a3b. A dedicated lightweight model for this task is a deliberate design decision — latency on the classification call directly affects all downstream routing.

Routing outcomes from the classifier:

  • meta → immediate response, graph terminates
  • research/shallow → Shallow Researcher
  • research/deep → Clarifier → Deep Researcher

Escalation path: After shallow research completes, the system evaluates whether to escalate to deep. It scans the last 800 characters of the shallow response for escalation signals: “unable to find”, “need more research”, “i don’t have enough information”. If triggered and enable_escalation: true in config, the query routes through the Clarifier before deep research begins — never directly to deep research, preserving the HITL gate. This is gated by a config flag so operators can disable escalation if they want strict shallow-only mode.

State machine implementation: LangGraph StateGraph over ChatResearcherState. All routing is explicit and testable. Conversation checkpointing uses InMemorySaver for development and can be swapped to SQLite or PostgreSQL for persistent sessions in production.

Stage 2: Clarification (HITL Before Deep Research)

The Clarifier Agent runs before every deep research job — including escalated shallow queries. Purpose: deep research is expensive in both time and compute. The clarifier reduces wasted effort by narrowing scope before committing to a multi-phase research loop.

Internal flow:

  1. Invoke LLM with conversation history and configured tools
  2. Parse structured ClarificationResponse JSON: {needs_clarification: bool, clarification_question: str|null}
  3. If clarification needed and iteration < max_turns (default: 3): prompt user via HITL callback, append response, repeat
  4. If iteration >= max_turns: auto-complete clarification without further user input
  5. Optionally generate a structured research plan (title + sections) for user approval

Plan approval loop (when enable_plan_approval: true):

  • Agent presents plan: title + section list
  • User can: approve (keywords: “approve”, “yes”, “ok”, “proceed”, “go ahead”, “looks good”, “y”, “accept”), reject (keywords: “reject”, “no”, “cancel”, “stop”, “abort”, “n”), or provide feedback
  • Feedback triggers plan regeneration; up to max_plan_iterations (default: 10) iterations before auto-approve
  • ClarifierResult carries: clarifier_log, plan_title, plan_sections, plan_approved, plan_rejected

What passes downstream: The clarifier_result string (full dialog log + approved plan) is injected into the Deep Researcher orchestrator prompt, giving the researcher access to the approved scope and any context gathered during clarification.

Disabling the clarifier: Set enable_clarifier: false in the orchestrator config. This sends queries from the intent classifier directly to deep research with no HITL gate — appropriate for batch/automated pipelines, not recommended for user-facing deployments.

Stage 3: Shallow Research

Purpose: Bounded, fast, tool-augmented research optimized for speed. Single tool-calling loop — no multi-phase planning.

Design constraint: Speed is the architectural priority. The intent classifier routes here for queries that don’t require comprehensive investigation. If the shallow result is inadequate (detected via escalation keyword scan), the system escalates rather than retrying within the shallow path.

Data source filtering: The data_sources field in ChatResearcherState controls which tools are available per request:

  • None → all configured tools available
  • [] → only unmapped utility tools (no data-source-specific tools)
  • populated list → named sources plus unmapped utility tools

This enables the same agent deployment to serve different knowledge backends (internal knowledge base only, web only, hybrid) without reconfiguration — request-level scoping rather than agent-level.

Stage 4: Deep Research (Multi-Phase)

The Deep Researcher produces publication-ready reports via a coordinated orchestrator + subagent architecture using the LangChain deepagents library.

Subagent roles:

Subagent LLM Role Function
Orchestrator ORCHESTRATOR Coordinates subagents, manages research loops, synthesizes draft sections, catalogs citations, produces final report
Planner PLANNER Builds evidence-grounded outline via interleaved search and outline optimization; creates 4–6 strategic search queries mapped to report sections
Researcher RESEARCHER Executes search queries using configured tools; synthesizes relevant content

All three subagents plus the orchestrator share a think tool — a structured way to record reasoning, verify constraints, or plan next steps without taking external action. This prevents ungrounded generation between tool calls.

Research loop (default: 2 iterations):

  1. Orchestrator dispatches to Planner → Planner executes search queries → returns evidence-grounded outline
  2. Loop begins: Orchestrator dispatches to Researcher → Researcher executes queries → returns synthesized findings → Orchestrator updates draft sections → identifies gaps
  3. After max_loops iterations: Orchestrator catalogs citations, produces polished final report

max_loops configuration: Configurable per deployment. Default is 2. Higher values improve comprehensiveness at proportional token and time cost. The benchmark branches (drb1, drb2) use specific loop counts tuned for leaderboard submissions — operators should not assume production defaults match benchmark configs.

Middleware stack (shared across all subagents):

Middleware Purpose
EmptyContentFixMiddleware Replaces empty ToolMessage content with placeholder to prevent LLM API rejections
ToolNameSanitizationMiddleware Sanitizes corrupted or hallucinated tool names from LLM responses
ModelRetryMiddleware Retries model calls with exponential backoff; max 10 retries on transient failures

The retry middleware is non-trivial for production: NVIDIA’s own documentation notes that nemotron-3-super-120b-a12b endpoints on the Build API return HTTP 429/503 responses under load. The retry layer absorbs these without surfacing errors to users.

Model Architecture and Routing Logic

Default Model Assignment

Role Default Model Alternative
Intent classifier nvidia/nemotron-3-nano-30b-a3b —
Shallow researcher nvidia/nemotron-3-nano-30b-a3b nvidia/nemotron-3-super-120b-a12b
Deep research orchestrator / planner openai/gpt-oss-120b GPT-5.2 (frontier config)
Deep research researcher subagent nvidia/nemotron-3-nano-30b-a3b Nemotron Super
Document summary (optional) nvidia/nemotron-mini-4b-instruct —
Text embedding nvidia/llama-nemotron-embed-vl-1b-v2 —
Vision-language (image/chart extraction, optional) nvidia/nemotron-nano-12b-v2-vl —

Frontier Model Config

A separate config_frontier_models.yml assigns GPT-5.2 to the orchestrator and planner roles while keeping Nemotron Nano for the researcher subagent. This is a hybrid strategy: use the most capable available model for planning and synthesis (higher reasoning demand), use an efficient model for raw search execution (lower reasoning demand, higher volume).

Tradeoff: Frontier orchestrator/planner costs more per deep research job and requires an OPENAI_API_KEY. The benefit is higher RACE scores on the DeepResearch Bench — specifically Insight and Instruction Following dimensions where stronger reasoning models differentiate.

Nemotron Reasoning Models vs. Frontier Routing

The Nemotron family covers a capability spectrum:

  • Nemotron Nano 30B (MoE, 3B active): Primary workhorse for high-volume roles (classification, researcher, shallow research). MoE architecture means 3B parameters active per forward pass despite 30B total — lower inference cost than a dense 30B.
  • Nemotron Super 120B (MoE, 12B active): Step-up for research subagent quality. Limited Build API availability; recommended to self-host via NVIDIA NIM for production.
  • GPT-OSS 120B: Default orchestrator/planner in the standard deep research config. Open-weights equivalent to GPT-4 class.
  • GPT-5.2 (frontier): Optional orchestrator upgrade in the frontier config.

Self-hosting path: For air-gapped or regulated deployments, all models are available via NVIDIA NIM (NVIDIA Inference Microservices). NIM packages model weights with inference-optimized serving into a container. The hardware reference matrix in the README maps each model to minimum GPU requirements. The default API-hosted path (NVIDIA Build / integrate.api.nvidia.com) requires no local GPU.

MCP Integration and Enterprise Data Sources

AI-Q connects to enterprise data sources via Model Context Protocol (MCP) servers. The authentication architecture has three modes:

Mode 1: Service Account Credentials

Tool receives a service account credential (API key, OAuth client secret) from deployment environment. The MCP server authenticates to the upstream data source using that credential. All users of the agent share the same access scope. Appropriate for: internal knowledge bases, company-wide search indexes, read-only data sources where row-level security is not required.

Mode 2: AIQ Token Pass-Through

When REQUIRE_AUTH=true and a data source is marked requires_auth: true, the AIQ backend captures the user’s JWT (from the OAuth/OIDC sign-in flow) and forwards it to the MCP tool. The MCP server uses the user’s own identity to authenticate to the upstream system, preserving per-user access control. Appropriate for: data sources with row-level security, HR systems, finance systems where user identity must propagate.

Implementation detail: The frontend (NextAuth) stores a session and sets an idToken cookie after OAuth sign-in. The backend AuthMiddleware validates bearer tokens or the idToken cookie using registered JWT validators. A validator is registered via Python entry point (aiq_api.validators group) or programmatically before server start.

Mode 3: Native MCP Auth

Some MCP servers implement their own authentication protocol. AIQ passes through to the server’s native auth mechanism. NVIDIA’s documentation notes this “does not automatically authenticate to an upstream MCP server” — each tool still needs its own credential configuration.

Data source registry pattern:

functions:
  data_sources:
    _type: data_source_registry
    sources:
      - id: internal_mcp
        name: "Internal Knowledge Base"
        requires_auth: true
        tools:
          - internal_mcp_tool
      - id: web_search
        name: "Web Search"
        requires_auth: false
        tools:
          - tavily_web_search

The UI disables requires_auth: true sources until the user signs in. This creates a clean UX where unauthenticated users can still use web search while internal data sources gate on identity.

Data source filtering at request time: The data_sources field on each request narrows which sources are active for that request. An agent deployed with 10 data sources can be restricted to 2 for any given query. This enables persona-based routing (external user sees only web + public docs; authenticated internal user sees web + internal KB + HR data) without deploying separate agent instances.

HITL Checkpoints

Three distinct HITL touchpoints in the pipeline:

1. Clarification dialog (pre-deep-research)

  • Fires: on every deep research path, including escalated shallow queries
  • Mechanism: user_interaction_manager callback injected at registration; agent sends structured clarification questions, user responds in natural language
  • Max turns: configurable (default: 3); auto-completes if limit reached
  • Can be disabled: enable_clarifier: false

2. Plan approval (optional, within clarifier)

  • Fires: after clarification dialog completes, when enable_plan_approval: true
  • Mechanism: agent presents structured plan (title + sections), user approves/rejects/provides feedback
  • Max feedback iterations: 10 before auto-approve
  • CIO-level relevance: plan approval gives stakeholders visibility into what the agent will research before compute is committed. For sensitive research tasks (competitive analysis, legal review), this is a meaningful governance gate.

3. Model promotion (Data Flywheel, separate system)

  • Described in the data-flywheel research file. The flywheel explicitly keeps model promotion as a human decision — no automatic promotion from candidate to production.

HITL vs. HOTL distinction: AI-Q implements HITL (human-in-the-loop) for clarification and plan approval — synchronous, blocking checkpoints. It does not implement HOTL (human-on-the-loop) monitoring of research execution. If an operator wants visibility into intermediate research steps, they must use the SSE stream (asynchronous, non-blocking observation).

Async Job Architecture and API

Deep research runs as async jobs. The synchronous /chat endpoint is appropriate for shallow research; deep research should use the async job API to avoid HTTP timeout.

Job lifecycle:

POST /v1/jobs/async/submit → 202 Accepted {job_id}
GET  /v1/jobs/async/job/{id}/stream → SSE stream
POST /v1/jobs/async/job/{id}/cancel → interrupt running job
GET  /v1/jobs/async/job/{id}/report → retrieve final report

State machine: SUBMITTED → RUNNING → SUCCESS | FAILURE | INTERRUPTED

A background reaper task marks stale RUNNING jobs as FAILURE if they exceed a configured timeout. This prevents ghost jobs from crashed Dask workers from occupying state forever.

SSE stream events (selected):

Event Description
llm.start / llm.chunk / llm.end Token-level streaming from each LLM call, including reasoning/thinking tokens
tool.start / tool.end Search tool invocations with query and result; tool.end emits citation_source artifacts
artifact.update File updates, draft sections, citation sources, todo list updates
job.heartbeat Every 30 seconds from Dask worker; aids ghost job detection
job.cancelled Emitted when user-requested cancellation completes

Reconnection: SSE stream supports seamless reconnection via GET /stream/{last_event_id}. The stream enters polling mode, replays all events after the last seen ID in batches (up to 10,000 for completed jobs, 1,000 for running), then transitions back to live streaming. This enables frontend reconnection without losing research progress.

Distributed execution: Async jobs run on a Dask cluster. The default Docker Compose setup runs Dask locally. Kubernetes/Helm deployment scales Dask workers horizontally. Dask worker count determines parallel deep research job capacity.

Citation Verification Architecture

Every research response — shallow and deep — passes through a deterministic post-processing pipeline before delivery. This is always enabled; it cannot be disabled via config.

Source Registry: A SourceRegistryMiddleware intercepts every tool call during research and records all URLs and citation keys returned by search tools into a per-session SourceRegistry. This creates a ground-truth record of what was actually retrieved — separate from what the LLM claims it retrieved.

Five-level URL matching strategy:

  1. Exact match — raw or normalized URL
  2. Truncation match — report URL is a prefix of exactly one registry URL
  3. Prefix match — normalized report URL is a prefix of a registry URL
  4. Child-path match — report URL path is a subpath of a registry URL (requires 2+ path segments)
  5. Query-subset match — same host and path; report query parameters are a subset of registry parameters

Citations not matched by any level are removed. Knowledge-layer citations (e.g., report.pdf, p.15) are matched against citation keys with lenient page-number comparison.

Sanitization: The pipeline also removes:

  • Shortened URLs (bit.ly, t.co, tinyurl.com, and 13 other domains)
  • Truncated/garbled URLs ending in ... or ellipsis characters
  • IP-address URLs
  • Non-HTTP schemes (javascript:, data:, vbscript:, file:)

Audit trail: Every verification decision is logged: which citations were kept, which were removed, and why (url_not_in_registry, citation_key_not_in_registry, unverifiable). This is the minimum viable citation governance for regulated-industry use — the audit trail can be stored and reviewed without re-running the research.

Enterprise implication: Citation verification addresses one of the primary failure modes of LLM research agents — hallucinated citations that look real. By verifying against the actual retrieval record rather than asking the LLM to self-check, the system provides deterministic citation accuracy independent of model behavior.

Benchmark Methodology

DeepResearch Bench (DRB)

Source: Published in “DeepResearch Bench: A Comprehensive Benchmark for Deep Research Agent” (arxiv 2506.11763). Third-party evaluation hosted on HuggingFace leaderboard.

Dataset: 100 research tasks — 50 English, 50 Chinese — across 22 domains.

Metrics:

RACE (report generation quality across 4 dimensions):

  • Comprehensiveness
  • Insight
  • Instruction Following
  • Readability

FACT (retrieval and citation system):

  • Average Effective Citations: average number of valuable, verifiably supported information items retrieved and presented per task
  • Citation Accuracy: precision of citations — measures the agent’s ability to ground statements with appropriate sources correctly

Reproducibility: NVIDIA maintains tagged branches drb1 and drb2 corresponding to the two leaderboard versions. Operators must use these branches to reproduce published scores — the main branch may differ.

W&B tracking: Evaluation runs are tracked in the nvidia-aiq/deep-researcher-v2 Weights & Biases Weave project, enabling reproducibility verification and cross-run comparison.

FreshQA

Source: FreshLLMs benchmark (arxiv 2310.03214). Evaluates factual accuracy on questions requiring up-to-date world knowledge.

Methodology: FreshEval Relaxed — credits responses where the primary answer is accurate even if hallucinations, outdated information, or ill-formed framing are also present. This is intentionally permissive: it isolates factual correctness from formatting quality.

Question taxonomy (3 dimensions):

  • Fact type: never-changing / slow-changing / fast-changing
  • Reasoning depth: one-hop / multi-hop
  • False premise: present / absent (false-premise questions require the agent to explicitly identify the false premise to receive credit)

Scoring rules (strict):

  • Confident, definitive answers required — hedged responses do not receive credit
  • Complete or commonly recognized names required for entity answers
  • Approximate numbers generally not accepted unless explicitly in ground truth

Judge model: Default is OpenAI GPT-4o. Operators can substitute any LLM registered in the config.

What this measures for AI-Q: FreshQA primarily exercises the Shallow Researcher and the orchestration node. It validates that the routing logic correctly classifies factual questions and that the tool-calling loop returns current, accurate answers.

DeepSearchQA (DeepMind)

Source: DeepMind dataset on Kaggle. Official evaluation methodology from DeepMind starter code.

Dataset: 900 problems across 11 categories (Politics & Government, Media & Entertainment, Education, Geography, Health, Science, Finance & Economics, Sports, Travel, History, Other). Answer types: Single Answer, Set Answer.

Metrics:

  • Precision: Correct answers / (Correct + Excessive answers)
  • Recall: Correct answers / Expected answers
  • F1: Harmonic mean of Precision and Recall
  • Accuracy: Percentage of problems with all correct answers and no excessive answers

Scoring scale:

  • 100 points: All expected answers correct, no excessive answers
  • 75 points: All expected answers correct but includes excessive answers
  • 0–50 points: Partial correctness (scaled)
  • 0 points: No correct answers or empty response

What this measures: Tests the deep research path’s ability to enumerate complete answer sets — relevant for research tasks that require comprehensive coverage rather than a single best answer.

Agent Skills Integration

AI-Q ships two portable Agent Skills for coding harnesses (Claude Code, Codex, OpenCode, LangChain):

aiq-deploy: Handles install, setup, and health validation. Knows how to read available YAML configs, select appropriate deployment mode, validate the backend and async API are reachable.

aiq-research: Handles research-shaped requests. Checks AIQ_SERVER_URL environment variable first, then defaults to http://localhost:8000. Manages the full async job lifecycle: submit, stream, poll, retrieve report, cancel.

Canonical install paths:

skills/aiq-deploy/     # repo-local
skills/aiq-research/
.agents/skills/        # compatibility symlink → ../skills (for AgentSkills-compatible harnesses)
.claude/skills/        # compatibility symlink for Claude Code

Recommended flow: aiq-research handles research intent; aiq-deploy handles setup intent. The skill descriptions include intent routing examples to prevent users from asking the deploy skill to do research.

aiq-research async API wrapper: The skill ships scripts/aiq.py — a Python script that wraps the async job lifecycle (submit → stream → report) into a simple CLI interface. This eliminates the need for each harness to implement SSE polling.

Enterprise relevance: The Agent Skills pattern means AI-Q’s deep research capability can be consumed as a tool by other agents — an AI-Q server becomes a specialized research microservice callable from Claude Code, Codex, or any LangChain agent. This is the natural architecture for multi-agent enterprise systems where a generalist orchestrator delegates research tasks to a specialized research agent.

Deployment Architecture

Docker Compose (Development / Small Production)

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

No-auth local setup. Set BACKEND_CONFIG env var to switch YAML configs without rebuilding. The backend runs on port 8000; the UI on port 3000.

For Agent Skill use (backend only, no UI):

./scripts/start_as_skill.sh --config_file configs/config_web_default_llamaindex.yml --port 8000

Kubernetes / Helm (Production)

Helm deployment in deploy/helm/deployment-k8s/. Scales Dask workers horizontally. Requires cluster-admin permissions, persistent storage configuration, and registry access for NIM containers.

Air-Gapped / Data Sovereignty Deployment

All inference can run on self-hosted NVIDIA NIM containers — no external API calls required. Configuration:

  1. Replace all nvidia/... and openai/... model refs in YAML configs with NIM endpoint URLs
  2. Set NVIDIA_API_KEY to internal NIM API key (or disable key requirement)
  3. Replace TAVILY_API_KEY web search with a self-hosted search service or internal knowledge layer
  4. Deploy with config_web_frag.yml pointing to internal RAG Blueprint server

Knowledge layer options for air-gapped: LlamaIndex (built-in, config_web_default_llamaindex.yml) or Foundational RAG Blueprint (config_web_frag.yml). The RAG Blueprint is a separate NVIDIA open-source repo deployable on-premises.

Dell AI Factory validation: NVIDIA documentation references Dell AI Factory as a validated reference architecture for regulated-industry deployment. The Dell AI Factory packages NVIDIA NIM, AI-Q, and Dell PowerEdge infrastructure into a validated stack with documented support paths. This is the path for regulated industries (financial services, healthcare, government) that need vendor-backed support for air-gapped deployment rather than a self-supported open-source stack.

Authentication Architecture

Default: Auth disabled. Appropriate for internal/development use.

Enabling auth:

  1. Add OAuth/OIDC provider to frontend NextAuth (frontends/ui/src/adapters/auth/providers/)
  2. Set REQUIRE_AUTH=true and AIQ_EXTERNAL_HOSTNAMES on backend
  3. Register a JWT validator via Python entry point (aiq_api.validators group)
  4. Mark data sources with requires_auth: true as appropriate

The auth system is designed for SSO integration with enterprise identity providers (Okta, Azure AD, Ping). The provider adapter pattern means adding a new identity provider is a ~50-line TypeScript file plus environment variable configuration.

Configuration System

All agent behavior is defined in YAML — no code changes required to switch models, add tools, adjust routing, or change research depth.

Config File Use Case
config_cli_default.yml CLI; web search; Nemotron Nano + GPT-OSS
config_web_default_llamaindex.yml Web UI; LlamaIndex knowledge retrieval; web search
config_web_frag.yml Web + external RAG Blueprint server; Helm default
config_frontier_models.yml GPT-5.2 orchestrator/planner; Nemotron Nano researcher; requires OpenAI key

What YAML controls:

  • LLM assignments per subagent role
  • Tool and data source registration
  • Research loop count (max_loops)
  • Clarifier behavior (enable_clarifier, enable_plan_approval, max_turns)
  • Escalation behavior (enable_escalation)
  • Benchmark evaluation parameters
  • Telemetry and tracing (Phoenix, W&B Weave)

Operational implication: Different teams within an enterprise can run different configs against the same AI-Q deployment by setting BACKEND_CONFIG — a legal team config with plan approval enabled and conservative loop counts, an analyst team config with frontier models and higher loop counts, a batch processing config with clarifier disabled.

Observability

Phoenix tracing: Optional Arize Phoenix integration for LLM call tracing. Start Phoenix server separately; AI-Q connects via config.

W&B Weave: Default for evaluation run tracking. All benchmark runs log to nvidia-aiq/deep-researcher-v2 project.

SSE as observability: The SSE event stream is not just for frontend UX — it is also the primary observability channel for deep research execution. Every tool call, LLM invocation, citation discovery, and intermediate draft update emits an SSE event. Operators can tap the stream for logging without instrumenting the agent code.

Enterprise Constraints and Known Limitations

Nemotron Super availability: The nvidia/nemotron-3-super-120b-a12b model endpoint on NVIDIA Build returns HTTP 429/503 under high demand. NVIDIA’s documentation explicitly acknowledges this. Production deployments should self-host via NIM or use Nemotron Nano as the default with Super as a fallback.

Dask single-node default: The default Docker Compose runs Dask on a single node. Horizontal scaling requires Kubernetes. There is no managed cloud-hosted version of AI-Q — operators own the infrastructure.

No PII handling in base implementation: The base AI-Q blueprint does not include PII redaction for queries or research results. Enterprises processing regulated data must add PII handling upstream.

MCP server dependency: Web search requires either Tavily or Serper API keys. The agent continues without search capability if neither is provided, but this removes the primary research mechanism. Air-gapped deployments must substitute with internal search services.

Research quality vs. speed tradeoff: FreshQA evaluates the shallow path; DeepResearch Bench evaluates the deep path. There is no single benchmark that measures both simultaneously. Operators choosing between shallow-only and full-pipeline deployments should run both evaluations against their target query distribution.

Single-tenant session state: The InMemorySaver checkpoint backend does not persist across restarts. For production use, operators must configure SQLite or PostgreSQL as the checkpoint backend to preserve conversation context across pod restarts.

Decision Framework for Enterprise Adopters

Use AI-Q if:

  • You need a research agent with citation verification (regulated industries)
  • You want a configurable HITL gate before expensive compute is committed
  • You require air-gapped deployment with NVIDIA NIM
  • You want a pre-built agent skill that other agents can call as a tool
  • Your team lacks the bandwidth to build multi-agent orchestration from scratch

Build custom if:

  • Your research task requires domain-specific tools not available as MCP servers
  • Your query distribution is 95%+ shallow — a simpler tool-calling loop will suffice
  • You need multi-modal research (AI-Q handles text and web; image/chart extraction via VLM is optional and limited)
  • You require fine-grained cost control per research job (AI-Q does not expose per-job token budgets in the base config)