把 Deep Research 做成可插拔能力：NVIDIA AI-Q Skill 对企业级 Agent 架构的启发

2026 年 5 月 20 日，NVIDIA 发布了一篇技术文章，介绍如何把 AI-Q 的深度研究能力包装成一个可被 Claude Code、Codex、OpenCode 等 agent harness 调用的“专用技能”。这篇文章的关键点不只是“又多了一个 AI 工具”，而是提出了一种更清晰的企业级 Agent 分层方式：让通用 agent harness 负责会话、工具编排、代码执行和用户交互，让专门的 research backend 负责多源检索、规划、综合、引用、评估和企业数据治理。(NVIDIA Developer)

1. 问题背景：为什么通用 Agent 不适合直接承担 Deep Research？

Claude Code、Codex、LangChain Deep Agents 这类 harness 很适合做开发者交互入口：它们能维护会话、调用工具、执行代码，并把用户意图转化为行动链。但当任务变成“基于多份企业文档、内部数据库、外部资料和合规数据源生成一份带引用的研究报告”时，复杂度会迅速从“调用几个工具”升级为“构建一条完整研究流水线”。NVIDIA 原文明确指出，企业团队需要处理数据接入、认证、查询路由、prompt 调优、输出评估和引用保真等问题，而这些不应该在每个 harness 里重复实现。(NVIDIA Developer)

这正是 AI-Q Skill 的定位：把 Deep Research 封装成一个可移植的 agent skill。harness 只需要把研究任务提交给本地或托管的 AI-Q server，然后等待结构化、带引用的报告返回；研究流水线本身仍然运行在企业可控环境内，敏感原始数据不必暴露给外部 agent harness。(NVIDIA Developer)

这背后有一个重要的工程判断：Deep Research 不是“更长的 prompt”，而是一套系统工程。它需要任务分类、澄清、检索、计划、迭代、综合、引用验证、权限控制、异步任务管理、可观测性和评估闭环。把它当作一个专门后端，而不是让通用 Agent 临时拼装，是企业级落地更稳妥的路线。

2. 核心概念：Harness、Skill、Research Backend 的职责边界

在这套架构里，agent harness 是入口层。它面向开发者或业务用户，负责理解请求、管理上下文、调用工具和展示结果。Skill 是能力声明层，通常由 SKILL.md 和辅助脚本组成，告诉 harness 什么时候、如何调用某个能力。Research backend 则是执行层，负责真正的研究流程、数据访问和报告生成。

NVIDIA AI-Q 的 skill 包位于 .agents/skills/aiq-research/，要求安装目录根部包含 SKILL.md，同时提供 scripts/aiq.py 辅助脚本，用于路由 /chat 请求、提交异步 deep research job、轮询状态并取回报告。AI-Q 文档中也明确列出了 Claude Code、Codex 和 OpenCode 的安装路径示例。(GitHub)

这种分层有几个好处。第一，harness 不需要知道企业检索、RAG、MCP、认证和引用验证的细节。第二，同一个 AI-Q server 可以被多个 harness 复用。第三，企业可以把数据访问、审计和模型路由集中在受控后端里，而不是散落到每个开发者工具或 IDE 插件中。

可以把它理解成如下调用链：

User / Developer
    ↓
Agent Harness: Claude Code / Codex / OpenCode / Deep Agents
    ↓
AI-Q Research Skill: SKILL.md + scripts/aiq.py
    ↓
AI-Q Server: /chat + async deep research jobs
    ↓
Research Pipeline: intent → clarify → shallow/deep research → citation-backed report
    ↓
Structured report with citations

3. AI-Q 的研究流水线：不是一个 Agent，而是一组可评估的 Agent

AI-Q 不是把一个大模型接到搜索工具上，而是一个多阶段研究系统。NVIDIA 的 AI-Q Blueprint 说明中提到，它基于 NVIDIA NeMo Agent Toolkit，并使用 LangChain Deep Agents，既可以生成快速的、带引用的回答，也可以生成更深入的报告式研究输出；它还内置 benchmark 和 evaluation harness，方便团队持续衡量质量。(GitHub)

从架构上看，AI-Q 使用基于 LangGraph 的状态机，核心组件包括 intent classifier、shallow researcher 和 deep researcher。intent classifier 负责判断请求是 meta 类问题还是 research 类问题，并进一步决定走 shallow research 还是 deep research。shallow researcher 适合快速、有边界的工具增强检索；deep researcher 则用于多阶段、长周期、带规划和引用管理的研究任务。(GitHub)

更细一点，AI-Q 的架构文档把核心组件拆成四类：Intent Classifier、Clarifier Agent、Shallow Researcher、Deep Researcher，以及负责协调这些组件的 Chat Researcher Orchestrator。Clarifier Agent 的价值尤其值得注意：它会在 deep research 开始前进行 human-in-the-loop 的计划生成和确认，避免 agent 在问题尚不清晰时直接进入高成本检索和长报告生成。(GitHub)

Deep Researcher 内部则进一步采用 orchestrator、planner、researcher subagent 的结构。NVIDIA 文档描述的流程是：orchestrator 调用 planner 生成研究计划，planner 执行搜索并构建有证据支撑的大纲，然后 orchestrator 在默认两轮研究循环中调度 researcher 执行查询、综合相关内容、更新草稿、识别缺口，最后进行 citation catalog 和报告生成。(NVIDIA Docs)

这意味着 AI-Q 的“深度研究”更像一个小型研究团队：有人判断任务类型，有人澄清需求，有人快速查证，有人做系统性计划，有人执行分主题检索，有人整合报告和引用。这种结构比“单 Agent + 搜索工具 + 长上下文”更容易做质量控制和故障定位。

4. 关键创新：把 Deep Research 暴露成 Agent Skill

原文的最重要创新，是把 AI-Q 的完整研究流水线暴露成一个 portable agent skill。NVIDIA 文章指出，这个 skill 让 Claude Code、Codex 或其他通用 agent 可以向运行中的 AI-Q server 提交研究任务，并收到格式化、详细、带引用的报告；skill 本身包含 SKILL.md 和一个 helper script，后者负责请求路由、任务提交、轮询和结果获取。(NVIDIA Developer)

这比单纯提供一个 REST API 更进一步。REST API 面向程序员，skill 面向 agent harness。SKILL.md 不只是接口文档，它还承担“能力说明书”的角色：告诉 Agent 什么时候应该使用这个能力、如何调用、返回结果是什么、有哪些限制。这使得 AI-Q 可以被自然语言触发，例如“研究某监管主题，并基于我们的内部政策文档生成 memo”，harness 会把任务交给 AI-Q，而不是自己拼装搜索和报告流程。(NVIDIA Developer)

从工程角度看，skill 是一种很轻量但很关键的“能力治理边界”。企业可以规定：凡是涉及内部知识库、多源事实核验、合规引用和长报告生成的任务，都必须通过 AI-Q research skill，而不是让任意 agent 直接读取原始数据源。这样做可以把权限、审计、成本控制和质量评估集中起来。

5. 企业数据接入：MCP 让 AI-Q 连接到已有系统

NVIDIA 原文特别强调了 MCP 集成。AI-Q 新版本支持作为 MCP client 连接到经过认证的 MCP server，从而把企业已有系统暴露为 research pipeline 的数据源，而不是为 AI-Q 单独搭建一套并行检索栈。文章还列出了三种认证模式：无逐用户认证的 MCP server、使用后端或应用凭证的 MCP server、以及下游 API 信任 AI-Q 用户 bearer token 的自定义 AI-Q tool。(NVIDIA Developer)

MCP，即 Model Context Protocol，是一个开源标准，用于让 AI 应用连接外部系统，包括本地文件、数据库、搜索引擎、工具和工作流。官方文档把 MCP 类比为“AI 应用的 USB-C 接口”，目的是减少 AI 应用和外部系统之间的集成复杂度。(Model Context Protocol)

MCP 目前定义了 stdio 和 Streamable HTTP 两类标准传输机制。对于企业场景，Streamable HTTP 更适合远程服务、认证和多客户端连接；MCP 规范也要求实现 Streamable HTTP 时校验 Origin header、本地服务尽量绑定到 localhost，并对连接实施合适的认证，以降低 DNS rebinding 等风险。(Model Context Protocol)

认证方面，MCP 的 HTTP 授权规范基于 OAuth 2.1、OAuth 2.0 Authorization Server Metadata、Dynamic Client Registration 和 Protected Resource Metadata。规范要求受保护的 MCP server 使用 Protected Resource Metadata 声明授权服务器位置，MCP client 则应使用这些元数据完成授权服务器发现。(Model Context Protocol)

NVIDIA 原文中还有一个容易被忽略但非常现实的限制：当 AI-Q 转发已登录用户的 bearer token 给下游 API 或 MCP gateway 时，token 会在 job 提交时捕获，并在异步 Dask worker 中恢复；当前版本不会在 job 中途刷新 token，因此如果研究任务运行时间超过 access token 的 TTL，后续需要认证的 tool call 会失败。(NVIDIA Developer)

这对企业落地非常重要。Deep Research 往往是长任务，可能持续数分钟甚至更久。如果企业的 access token TTL 很短，就需要在设计阶段处理 token refresh、job timeout、失败重试、权限降级和用户重新授权，否则系统会在最关键的异步阶段出现不稳定。

6. 部署模式：让研究系统跑在数据所在的位置

NVIDIA 原文的另一个重点是“researcher deployed where your data lives”。AI-Q Blueprint 提供 Docker Compose 和 Helm charts，因此同一套 blueprint 可以跑在开发者笔记本、本地或云上的 Kubernetes 集群，甚至 air-gapped 数据中心。(NVIDIA Developer)

这对医疗、金融、政府、制造等行业尤其关键。原始文档和企业数据可以留在受控环境内，AI-Q 在内部完成检索、综合和报告生成，agent harness 只接收带引用的输出，而不是直接拿到原始数据。NVIDIA 文章还指出，Nemotron 等开放模型可以通过 NVIDIA NIM 在本地部署，同时也可以配置云端 frontier model，企业可以根据成本、合规和性能需求选择模型路径。(NVIDIA Developer)

AI-Q GitHub 文档显示，它支持 CLI、Web UI 和异步 job 等多种运行方式；Web 模式可启动后端 API server 和前端 UI，Docker Compose 也可以用于本地 no-auth setup。(GitHub)

AI-Q API 还提供异步 job 能力，包含 job tracking、Dask scheduling、SQLite/PostgreSQL job store、SSE streaming、event replay、job cancellation 和 final report retrieval 等机制。API 路由包括 /v1/jobs/async/submit、/v1/jobs/async/job/{id}/stream、/v1/jobs/async/job/{id}/cancel 和 /v1/jobs/async/job/{id}/report。(GitHub)

这说明 AI-Q 的定位不是 demo chatbot，而是一个可被产品系统集成的后端服务。它具备长任务、异步执行、事件流、结果持久化和生产数据库支持，这些都是企业级 agent workflow 必须具备的能力。

7. 与 LangChain Deep Agents 的关系

AI-Q 不是要替代 LangChain Deep Agents，而是把它用于更专门的研究后端中。LangChain Deep Agents 官方文档把 deepagents 描述为构建长任务 agent 的 harness，内置任务规划、文件系统上下文管理、subagent spawning 和长期记忆等能力，并基于 LangGraph runtime 提供 durable execution、streaming 和 human-in-the-loop 等能力。(LangChain Docs)

AI-Q 的 Deep Researcher 文档也明确提到，它通过 create_deep_agent 构造 agent，并使用 deepagents library 管理 subagent coordination。换句话说，LangChain Deep Agents 提供可组合的 agent runtime 能力，而 AI-Q 把这些能力放进了一个面向“企业深度研究”的完整 blueprint 中。(NVIDIA Docs)

这给开发者的启发是：不要把 agent framework、agent harness 和业务能力混为一谈。LangGraph、Deep Agents、NeMo Agent Toolkit 解决的是构建和运行 agent workflow 的问题；AI-Q Research Skill 解决的是“如何把企业级 Deep Research 作为一个可复用能力暴露给其他 agent”的问题。

8. 一个最小可落地的 AI-Q Skill 集成流程

下面是一个简化版落地流程，适合团队做 POC。具体命令以官方仓库为准。

首先，准备 AI-Q server：

git clone https://github.com/NVIDIA-AI-Blueprints/aiq.git
cd aiq

./scripts/setup.sh

cp deploy/.env.example deploy/.env
# 编辑 deploy/.env，填入 NVIDIA_API_KEY、TAVILY_API_KEY、SERPER_API_KEY 等

./scripts/start_e2e.sh

AI-Q README 中说明，./scripts/setup.sh 会创建 Python 虚拟环境、安装核心依赖、frontends、benchmarks 和 data sources；Web UI 模式可通过 ./scripts/start_e2e.sh 启动后端 API server 和前端 UI。(GitHub)

然后，把 AI-Q skill 安装到 harness 的 skills 目录。以 Claude Code repo-local skill 为例：

mkdir -p .claude/skills
ln -s ../../.agents/skills/aiq-research .claude/skills/aiq-research

OpenCode 的用户级目录则是：

mkdir -p ~/.config/opencode/skills
cp -R .agents/skills/aiq-research ~/.config/opencode/skills/aiq-research

AI-Q 的 agent skills 文档说明，Claude Code 支持 .claude/skills/，OpenCode 使用 ~/.config/opencode/skills/，Codex 或其他兼容 Agent Skills 的工具则需要把 aiq-research 安装到对应 runtime 的 skills 目录，并确保目录内包含 SKILL.md 和 scripts/aiq.py。(GitHub)

如果直接通过 API 测试 deep research job，可以使用类似下面的调用：

curl -X POST http://localhost:8000/v1/jobs/async/submit \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "deep_researcher",
    "input": "Research the regulatory landscape for AI agents in financial services and produce a cited executive memo."
  }'

curl http://localhost:8000/v1/jobs/async/job/{job_id}/stream

curl http://localhost:8000/v1/jobs/async/job/{job_id}/report

AI-Q API 文档显示，deep_researcher 用于 comprehensive multi-loop deep research，shallow_researcher 用于 quick single-turn research；job stream 会输出 job.status、workflow.start、llm.chunk、tool.start、artifact.update、job.error 等事件。(GitHub)

9. 工程延伸：企业应该如何把它产品化？

第一，建立统一的 Research Skill Gateway。不要让每个团队各自把 Claude Code、Cursor、内部 chatbot、Slack bot 直接连到不同数据源，而是让所有“需要企业数据的深度研究任务”先进入统一 gateway。Gateway 负责认证、权限映射、租户隔离、限流、审计、模型路由和成本记录，AI-Q server 则作为核心 research runtime。

第二，建立 Data Source Registry。AI-Q 已经支持 data source registry，request payload 可以选择 web、paper、enterprise、collaboration 和 knowledge-layer 等来源；Knowledge Layer 也提供可插拔的 document ingestion 和 retrieval 抽象，支持在不改变应用代码的情况下替换后端。(GitHub)

第三，把 MCP server 当作企业系统的“受控工具层”。MCP 很适合连接 issue tracker、wiki、代码仓库、文档库、CRM、BI 系统和内部 API，但不要把所有工具描述一次性塞进模型上下文。MCP client best practices 指出，当 host 连接很多 server、拥有数百上千个工具时，天真地把所有 tool definitions 一开始就放进上下文会浪费 token、增加延迟并降低模型表现；progressive discovery 和 programmatic tool calling 是更可扩展的模式。(Model Context Protocol)

第四，把评估纳入 CI/CD。AI-Q README 提到，它内置 Deep Research Bench 和 FreshQA 等 evaluation pipelines；Deep Researcher 文档也说明它使用 Deep Research Bench 的 RACE 和 FACT metrics 评估研究报告。(GitHub)

企业可以在此基础上增加自己的 golden set，例如“过去 12 个月法规变更总结”“竞品招股书分析”“内部事故复盘报告”“客户 SLA 风险判断”等。评估指标不应只有模型打分，还应包括 source recall、citation precision、unsupported claim ratio、freshness、latency、cost、auth failure rate 和 human override rate。

第五，优先做可观测性。NVIDIA 原文提到 NeMo Agent Toolkit 会发出 OpenTelemetry traces，使合规团队能够检查检索了哪些源、如何使用这些源，以及最终答案如何生成。OpenTelemetry 官方也将其定义为云原生软件的开源可观测性框架，可用于采集 traces、metrics 和 logs。(NVIDIA Developer)

对于 Agent 系统，trace 不只是排障工具，而是治理基础。一次 deep research 至少应该能追踪：用户是谁、任务是什么、走了 shallow 还是 deep、调用了哪些 MCP server、使用了哪些 credentials、读取了哪些文档、哪些来源进入了引用、哪些来源被拒绝、每轮 planner/researcher 的 token 和 latency、最终报告是否通过引用校验。

10. 常见风险与设计建议

第一类风险是权限泄露。AI-Q 的优势是让原始数据留在企业环境内，但如果 MCP server 权限过宽、service account 无法区分用户、或者 downstream API 忽略 row-level security，agent 仍然可能越权读取数据。生产环境应尽量采用 per-user authorization 或严格 scoped service account，并在返回给模型前做字段级过滤。

第二类风险是引用幻觉。AI-Q 文档强调 citation management 和 citation-backed report，但企业仍应建立 post-processing 检查：每条引用是否真的来自检索结果、引用段落是否支持对应结论、是否出现模型生成的伪 URL、是否引用了过期文档。AI-Q 架构文档也提到，研究响应会经过确定性后处理管道，对引用和实际检索来源做校验，并生成审计轨迹。(GitHub)

第三类风险是长任务不稳定。Deep Research 是异步、长周期、多工具调用任务，容易受到 token TTL、网络超时、搜索 API 限流、模型临时失败和 worker 重启影响。AI-Q API 中的 job status、SSE stream、event replay、cancel 和 final report endpoint 是基础能力，但企业还需要补上 job idempotency、checkpoint restore、dead-letter queue、retry budget 和 user-facing progress summary。(GitHub)

第四类风险是成本失控。Deep Research 可能触发多轮搜索、多模型调用、长上下文综合和 citation verification。建议在 request 层配置 task class、max loops、tool-call budget、source whitelist、模型路由策略和 cost ceiling；在评估层观察“每份可接受报告的平均成本”，而不是只看单次 token 消耗。

第五类风险是 tool/context 膨胀。随着 MCP server 和工具数增长，agent 会面对越来越复杂的 action surface。解决方式不是继续扩大上下文，而是做工具分层、按需发现、任务路由和 skill 化，把“何时使用什么能力”显式编码进 Skill 或 Gateway 策略中。

11. 推荐的企业落地路线图

第一阶段是本地 POC。目标不是接入全部企业数据，而是验证 AI-Q server、skill 调用、shallow/deep routing、异步 job、报告生成和引用展示。可以先使用 web search、paper search 和少量脱敏文档。

第二阶段是受控数据接入。选择一个低风险但真实的业务知识库，例如公开政策、产品文档、历史 FAQ 或研发 RFC。通过 Knowledge Layer 或 MCP server 接入，验证权限、引用、更新频率和检索质量。

第三阶段是评估闭环。建立 50 到 200 个代表性任务，覆盖事实问答、对比分析、趋势总结、合规 memo 和内部文档综合。每次 prompt、模型、retriever 或数据源调整后都跑评估，并记录质量、延迟、成本和失败类型。

第四阶段是生产化。引入 Kubernetes/Helm、PostgreSQL job store、集中日志、OpenTelemetry traces、secret management、tenant isolation、RBAC、DLP、审计报表和人工审批流程。此时 AI-Q 不再只是一个研究 demo，而是企业内部的“Research Capability Service”。

第五阶段是多 harness 复用。让 Claude Code、Codex、OpenCode、内部 Web Chat、Slack bot 或 IDE 插件都通过同一个 Research Skill Gateway 调用 AI-Q。这样，企业的 deep research 能力只需治理一次，就可以在多个开发和业务入口复用。

结论：Agent 的未来不是“一个全能大脑”，而是“可治理的能力网络”

NVIDIA 这篇文章的价值在于，它没有把 Deep Research 描述成一个更强的聊天机器人，而是把它拆成了一个可复用、可部署、可认证、可审计、可评估的企业能力。通用 agent harness 负责交互和编排，AI-Q skill 负责能力暴露，AI-Q server 负责深度研究流水线，MCP 负责连接企业数据源，OpenTelemetry 和 evaluation harness 负责治理闭环。

对工程团队来说，最重要的启发是：不要在每个 Agent 项目里重复造一个不完整的 research pipeline。把 Deep Research 做成专门的 backend skill，再通过标准化 skill、MCP、异步 API 和统一治理层暴露出去，才是更接近生产级 Agent 系统的架构方向。