aiq-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AIQ Research Skill

Purpose

用途

Use this skill to call a locally running NVIDIA AI-Q Blueprint server through the helper script at

scripts/aiq.py

Use this skill for research-shaped requests, including:

"deep research on ..."
"AIQ research ..."
"research ..."
"use AI-Q to answer ..."
"ask AI-Q about ..."

Do not use this skill for install, deploy, start, stop, UI, CLI, Docker, Helm, or troubleshooting requests. Those belong to

aiq-deploy

使用本Skill通过

scripts/aiq.py

辅助脚本调用本地运行的NVIDIA AI-Q Blueprint服务器。

当收到以下类型的研究类请求时使用本Skill：

"对……进行深度研究"
"AIQ研究……"
"研究……"
"使用AI-Q回答……"
"向AI-Q咨询……"

请勿将本Skill用于安装、部署、启动、停止、UI、CLI、Docker、Helm或故障排查请求，这些请求属于

aiq-deploy

的范畴。

Prerequisites

前提条件

Users need:

Python 3.11+ available as
```
python3
```
.
A reachable local or self-hosted AI-Q Blueprint backend.
```
AIQ_SERVER_URL
```
set when the backend is not running at
```
http://localhost:8000
```
.
A backend configured with authentication disabled for this public helper, or a separate authenticated AI-Q skill for authenticated environments.
Network access from the local machine to the AI-Q backend URL.
Credentials configured in the backend environment, not in this skill. This public helper does not collect or manage API keys.

The helper script has no third-party Python package dependencies; it uses Python standard-library HTTP modules.

用户需要满足：

可通过
```
python3
```
调用Python 3.11+版本。
可访问本地或自托管的AI-Q Blueprint后端。
当后端未运行在
```
http://localhost:8000
```
时，需设置
```
AIQ_SERVER_URL
```
环境变量。
本公共辅助工具对应的后端需配置为禁用认证，或者在认证环境中使用单独的带认证AI-Q Skill。
本地机器需具备访问AI-Q后端URL的网络权限。
凭证需配置在后端环境中，而非本Skill内。本公共辅助工具不收集或管理API密钥。

该辅助脚本无第三方Python包依赖，仅使用Python标准库中的HTTP模块。

Instructions

操作步骤

Resolve the target backend URL.
Run
```
health
```
before sending research requests.
If no backend is reachable, ask for a backend URL or hand off to
```
aiq-deploy
```
.
Tell the user the query will be sent to the configured AI-Q backend before sending it.
Poll asynchronous deep research jobs when AI-Q returns a job ID.
Present returned reports with citations and source URLs intact.
Stop on failed jobs and show the returned error; do not retry automatically.

解析目标后端URL。
在发送研究请求前运行
```
health
```
检查。
若无法访问后端，询问用户是否提供后端URL，或转交至
```
aiq-deploy
```
处理。
在发送请求前告知用户查询将被发送至已配置的AI-Q后端。
当AI-Q返回任务ID时，轮询异步深度研究任务。
完整呈现返回的报告，保留引用和源URL。
任务失败时停止操作并显示返回的错误；请勿自动重试。

Step 1 - Resolve the backend

步骤1 - 解析后端

Use

AIQ_SERVER_URL

when set. Otherwise try the default local backend:

bash

python3 $SKILL_DIR/scripts/aiq.py health

Expected output: JSON from a reachable AI-Q health endpoint.

health

fails and no explicit

AIQ_SERVER_URL

was set, ask:

text

I do not see a reachable local AI-Q backend. Do you already have an AI-Q backend URL you want to use, or should I deploy a local Skill backend?

If the user provides a URL, set
```
AIQ_SERVER_URL
```
for subsequent helper calls and rerun
```
health
```
.
If the user wants local deployment, hand off to
```
aiq-deploy
```
and preserve the original research request.
If a reachable backend returns
```
401
```
or
```
403
```
, stop and explain that this public skill does not manage authentication. Ask the user to use an authenticated AI-Q skill or configure authentication for their environment.
If
```
health
```
succeeds but
```
/chat
```
or
```
/v1/jobs/async/agents
```
fails, report that the backend is reachable but not compatible with this public research flow, then offer to run
```
aiq-deploy
```
validation.

若已设置

AIQ_SERVER_URL

则使用该地址，否则尝试默认本地后端：

bash

python3 $SKILL_DIR/scripts/aiq.py health

预期输出：可访问的AI-Q健康检查端点返回的JSON数据。

若

health

检查失败且未设置明确的

AIQ_SERVER_URL

，请询问：

text

未检测到可访问的本地AI-Q后端。您是否已有要使用的AI-Q后端URL，还是需要部署本地Skill后端？

若用户提供URL，为后续辅助工具调用设置
```
AIQ_SERVER_URL
```
并重新运行
```
health
```
检查。
若用户需要本地部署，转交至
```
aiq-deploy
```
处理并保留原始研究请求。
若可访问的后端返回
```
401
```
或
```
403
```
状态码，停止操作并说明本公共Skill不管理认证。请用户使用带认证的AI-Q Skill或为其环境配置认证。
若
```
health
```
检查成功但
```
/chat
```
或
```
/v1/jobs/async/agents
```
请求失败，报告后端可访问但与本公共研究流程不兼容，然后提供运行
```
aiq-deploy
```
验证的选项。

Step 2 - Send the routed research request

步骤2 - 发送路由后的研究请求

Before sending the request, state the resolved endpoint:

text

I will send this query to <AIQ_SERVER_URL>. Make sure this endpoint is trusted before sending sensitive information.

Do not send credentials, cookies, bearer tokens, or secret values through the query text.

Run:

bash

python3 $SKILL_DIR/scripts/aiq.py chat "<USER_QUESTION>"

Expected output:

A normal JSON response for shallow or direct answers.
Or structured JSON containing
```
{"status": "deep_research_running", "job_id": "<JOB_ID>"}
```
for asynchronous deep research.

If the response is normal JSON, present the result immediately. Do not force polling when there is no

job_id

发送请求前，告知用户已解析的端点：

text

我将把该查询发送至<AIQ_SERVER_URL>。在发送敏感信息前，请确保该端点是可信的。

请勿通过查询文本发送凭证、Cookie、Bearer令牌或机密值。

运行：

bash

python3 $SKILL_DIR/scripts/aiq.py chat "<USER_QUESTION>"

预期输出：

针对浅层或直接问题的常规JSON响应。
或者包含
```
{"status": "deep_research_running", "job_id": "<JOB_ID>"}
```
的结构化JSON，代表异步深度研究任务。

若响应为常规JSON，立即呈现结果。当无

job_id

时，无需强制轮询。

Step 3 - Poll asynchronous jobs

步骤3 - 轮询异步任务

If the response includes

deep_research_running

, extract the

job_id

and poll with the same absolute script path:

bash

python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

Expected output: the final report JSON when the job completes successfully.

Use the runtime's non-blocking or background execution mechanism when available. If the chosen execution method requires escalated permissions, request explicit user approval first and explain why. Tell the user that deep research is running in the background.

若响应包含

deep_research_running

，提取

job_id

并使用相同的绝对脚本路径进行轮询：

bash

python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

预期输出：任务成功完成时的最终报告JSON数据。

若运行环境支持非阻塞或后台执行机制，请使用该机制。若所选执行方法需要提升权限，需先请求用户明确批准并说明原因。告知用户深度研究任务正在后台运行。

Step 4 - Resume after interruptions

步骤4 - 中断后恢复

If polling is interrupted, the job continues server-side. Resume with:

bash

python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

Use

status

to inspect job status and saved artifacts. Use

report

when the job has already finished and you only need the final output. Use

research_poll

to keep waiting for completion.

若轮询被中断，任务仍会在服务器端继续运行。使用以下命令恢复：

bash

python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

使用

status

查看任务状态和已保存的产物。当任务已完成且仅需最终输出时，使用

report

。使用

research_poll

继续等待任务完成。

Step 5 - Present the report

步骤5 - 呈现报告

When

research_poll

completes successfully, fetch and present the full report. Keep citations and source URLs intact. If the job status is

failed

failure

, or

cancelled

, show the error from the status response and ask whether the user wants to retry with a narrower query or different approach.

当

research_poll

成功完成后，获取并完整呈现报告。保留引用和源URL不变。若任务状态为

failed

、

failure

或

cancelled

，显示状态响应中的错误，并询问用户是否需要使用更具体的查询或其他方法重试。

Version Compatibility

版本兼容性

IMPORTANT: This skill is designed for NVIDIA AI-Q Blueprint version 2.1.0.

Semantic Versioning Compatibility Rules:

text

Skill version: X.Y.Z
Blueprint or endpoint version: A.B.C

Compatible IF:
1. A == X (Major versions MUST match)
2. B >= Y (Minor version must be equal or greater)
3. C can be anything (Patch version does not affect compatibility)

Examples:

Skill version 2.1.0 is compatible with Blueprint version 2.1.0.
Skill version 2.1.0 is compatible with Blueprint version 2.2.0.
Skill version 2.1.0 is compatible with Blueprint version 2.1.5.
Skill version 2.1.0 is not compatible with Blueprint version 3.0.0.
Skill version 2.1.0 is not compatible with Blueprint version 2.0.0.

If your Blueprint version is not compatible:

Check for an updated skill version matching your Blueprint version.
Use a Blueprint version compatible with this skill.
Proceed with caution only when the user accepts the compatibility risk; API routes or response shapes may have changed.

重要提示： 本Skill专为NVIDIA AI-Q Blueprint 2.1.0版本设计。

语义化版本兼容性规则：

text

Skill版本: X.Y.Z
Blueprint或端点版本: A.B.C

兼容条件：
1. A == X（主版本必须匹配）
2. B >= Y（次版本必须大于或等于）
3. C无限制（补丁版本不影响兼容性）

示例：

Skill 2.1.0版本兼容Blueprint 2.1.0版本。
Skill 2.1.0版本兼容Blueprint 2.2.0版本。
Skill 2.1.0版本兼容Blueprint 2.1.5版本。
Skill 2.1.0版本不兼容Blueprint 3.0.0版本。
Skill 2.1.0版本不兼容Blueprint 2.0.0版本。

若您的Blueprint版本不兼容：

检查是否有与您的Blueprint版本匹配的更新版Skill。
使用与本Skill兼容的Blueprint版本。
仅当用户接受兼容性风险时才可继续操作；API路由或响应格式可能已更改。

Available Scripts

可用脚本

Script	Purpose	Arguments
`scripts/aiq.py health`	Check whether the configured server responds	none
`scripts/aiq.py chat`	POST `/chat` ; may return inline output or a deep-research job ID	`<query>`
`scripts/aiq.py agents`	List available async agent types	none
`scripts/aiq.py submit`	Submit an explicit async job	`<query> [agent_type]`
`scripts/aiq.py research`	Submit an async job, poll, and print the final report JSON	`<query> [agent_type]`
`scripts/aiq.py research_poll`	Resume polling an existing async job	`<job_id>`
`scripts/aiq.py status`	Fetch job status plus `/state` artifacts	`<job_id>`
`scripts/aiq.py state`	Fetch event-store artifacts only	`<job_id>`
`scripts/aiq.py report`	Fetch the final report for a completed job	`<job_id>`
`scripts/aiq.py stream`	Stream SSE events from a job	`<job_id>`
`scripts/aiq.py cancel`	Cancel a running job	`<job_id>`

When the host supports a

run_script()

helper, call it with

scripts/aiq.py

and the arguments above. Otherwise, run the equivalent shell command, such as

python3 $SKILL_DIR/scripts/aiq.py health

脚本	用途	参数
`scripts/aiq.py health`	检查配置的服务器是否响应	无
`scripts/aiq.py chat`	POST请求 `/chat` ；可能返回内联输出或深度研究任务ID	`<query>`
`scripts/aiq.py agents`	列出可用的异步Agent类型	无
`scripts/aiq.py submit`	提交显式异步任务	`<query> [agent_type]`
`scripts/aiq.py research`	提交异步任务、轮询并打印最终报告JSON	`<query> [agent_type]`
`scripts/aiq.py research_poll`	恢复轮询现有异步任务	`<job_id>`
`scripts/aiq.py status`	获取任务状态及 `/state` 产物	`<job_id>`
`scripts/aiq.py state`	仅获取事件存储产物	`<job_id>`
`scripts/aiq.py report`	获取已完成任务的最终报告	`<job_id>`
`scripts/aiq.py stream`	流式获取任务的SSE事件	`<job_id>`
`scripts/aiq.py cancel`	取消运行中的任务	`<job_id>`

若宿主环境支持

run_script()

辅助函数，调用时传入

scripts/aiq.py

及上述参数。否则，运行等效的Shell命令，例如

python3 $SKILL_DIR/scripts/aiq.py health

。

Environment Variables

环境变量

Variable	Required	Default	Description
`AIQ_SERVER_URL`	No	`http://localhost:8000`	Local or self-hosted AI-Q server base URL

变量	是否必填	默认值	描述
`AIQ_SERVER_URL`	否	`http://localhost:8000`	本地或自托管AI-Q服务器的基础URL

Security Best Practices

安全最佳实践

Do not put API keys, bearer tokens, cookies, or basic-auth credentials in
```
AIQ_SERVER_URL
```
.
Store backend credentials in the AI-Q deployment environment, not in this skill or command examples.
User query text is transmitted to the configured
```
AIQ_SERVER_URL
```
. Confirm the endpoint is trusted before sending sensitive or confidential information.
Treat returned reports as potentially sensitive if the backend uses private data sources.
Do not truncate citations or source URLs from returned reports.

请勿在
```
AIQ_SERVER_URL
```
中包含API密钥、Bearer令牌、Cookie或基础认证凭证。
后端凭证需存储在AI-Q部署环境中，而非本Skill或命令示例内。
用户查询文本将被传输至已配置的
```
AIQ_SERVER_URL
```
。发送敏感或机密信息前，请确认该端点是可信的。
若后端使用私有数据源，返回的报告需视为潜在敏感信息。
请勿截断返回报告中的引用或源URL。

Limitations

局限性

This skill requires a running AI-Q backend; it does not deploy one.
The public helper does not manage authentication tokens or cookies.
Remote
```
AIQ_SERVER_URL
```
endpoints may log prompts, responses, and metadata.
If the backend returns HTTP 500 or lacks async agents, report the failure instead of fabricating a research answer.

本Skill需要运行中的AI-Q后端；不提供部署功能。
公共辅助工具不管理认证令牌或Cookie。
远程
```
AIQ_SERVER_URL
```
端点可能记录提示词、响应及元数据。
若后端返回HTTP 500状态码或无可用异步Agent，需报告失败，而非生成虚假的研究答案。

Examples

示例

Example 1: Run a routed chat or research request

示例1：运行路由后的聊天或研究请求

bash

python3 $SKILL_DIR/scripts/aiq.py health
python3 $SKILL_DIR/scripts/aiq.py chat "Compare local AIQ deep research with a standard web search workflow"

Expected output:

text

<health JSON from AI-Q>
<JSON chat response or {"status": "deep_research_running", "job_id": "<JOB_ID>"}>

If AI-Q returns a job ID, continue with

research_poll

bash

python3 $SKILL_DIR/scripts/aiq.py health
python3 $SKILL_DIR/scripts/aiq.py chat "对比本地AIQ深度研究与标准网络搜索流程"

预期输出：

text

<AI-Q返回的健康检查JSON>
<JSON聊天响应或{"status": "deep_research_running", "job_id": "<JOB_ID>"}>

若AI-Q返回任务ID，继续使用

research_poll

。

Example 2: Resume an existing job

示例2：恢复现有任务

bash

python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

Replace

<JOB_ID>

with the UUID returned by AI-Q. Expected output: status JSON followed by the report JSON when the job completes. If the job failed, show the returned status and do not retry automatically.

bash

python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>
python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

将

<JOB_ID>

替换为AI-Q返回的UUID。预期输出：状态JSON，任务完成后显示报告JSON。若任务失败，显示返回的状态且不自动重试。

References

参考资料

Topic	Documentation
Helper script	`scripts/aiq.py`
Deployment and backend validation	`../aiq-deploy/SKILL.md`

主题	文档
辅助脚本	`scripts/aiq.py`
部署与后端验证	`../aiq-deploy/SKILL.md`

Common Issues

常见问题

Issue: No backend is reachable

问题：无法访问后端

Symptoms:

```
health
```
fails with connection refused.
The default
```
http://localhost:8000
```
URL does not respond.

Causes:

AI-Q is not running.
AI-Q is running on a different host or port.
A local firewall or network setting blocks the connection.

Solutions:

Ask whether the user has an existing AI-Q backend URL.

If they provide one, set it and rerun health:

bash

export AIQ_SERVER_URL="http://localhost:<PORT>"
python3 $SKILL_DIR/scripts/aiq.py health

If they want a local backend, hand off to
```
aiq-deploy
```
and preserve the original research request.

症状：

```
health
```
检查因连接被拒绝而失败。
默认
```
http://localhost:8000
```
URL无响应。

原因：

AI-Q未运行。
AI-Q运行在其他主机或端口。
本地防火墙或网络设置阻止了连接。

解决方案：

询问用户是否已有现有AI-Q后端URL。

若用户提供URL，设置该地址并重新运行健康检查：

bash

export AIQ_SERVER_URL="http://localhost:<PORT>"
python3 $SKILL_DIR/scripts/aiq.py health

若用户需要本地后端，转交至
```
aiq-deploy
```
处理并保留原始研究请求。

Issue: Backend requires authentication

问题：后端需要认证

Symptoms:

Requests fail with HTTP 401 or HTTP 403.
The backend is reachable but rejects
```
/chat
```
or async job calls.

Causes:

The backend was deployed with authentication enabled.
The public helper does not attach user tokens or cookies.

Solutions:

Stop and explain that this public skill does not manage authentication.
Ask the user to use an authenticated AI-Q skill or configure their backend for this public local workflow.
Rerun
```
health
```
and the original query only after the authentication boundary is resolved.

症状：

请求因HTTP 401或HTTP 403状态码而失败。
后端可访问但拒绝
```
/chat
```
或异步任务调用。

原因：

后端部署时启用了认证。
公共辅助工具不附加用户令牌或Cookie。

解决方案：

停止操作并说明本公共Skill不管理认证。
请用户使用带认证的AI-Q Skill或为其后端配置适配本公共本地流程的设置。
仅在认证问题解决后重新运行
```
health
```
检查和原始查询。

Issue: Health succeeds but research routes fail

问题：健康检查成功但研究路由失败

Symptoms:

```
health
```
returns successfully.
```
/chat
```
,
```
/v1/jobs/async/agents
```
, or polling commands fail.

Causes:

The backend is not using an API-enabled AI-Q config.
The async job registry is not available in the selected backend.
The backend version is incompatible with this skill.

Solutions:

Run:

bash

python3 $SKILL_DIR/scripts/aiq.py agents

If agents are unavailable, report the compatibility failure and offer to run
```
aiq-deploy
```
validation.
Confirm the deployed Blueprint version is compatible with skill version 2.1.0.

症状：

```
health
```
检查返回成功。
```
/chat
```
、
```
/v1/jobs/async/agents
```
或轮询命令失败。

原因：

后端未使用启用API的AI-Q配置。
所选后端中无可用的异步任务注册表。
后端版本与本Skill不兼容。

解决方案：

运行：

bash

python3 $SKILL_DIR/scripts/aiq.py agents

若Agent不可用，报告兼容性失败并提供运行
```
aiq-deploy
```
验证的选项。
确认已部署的Blueprint版本与Skill 2.1.0版本兼容。

Issue: Job is interrupted or appears stuck

问题：任务被中断或看似停滞

Symptoms:

Local polling is interrupted.
The job keeps showing
```
running
```
.
Poll output shows
```
running
```
, but a report is returned or cancel says the job is already
```
success
```
.

Causes:

Deep research is asynchronous and continues server-side.
Local polling output can lag behind terminal server state.

Solutions:

Check current state:

bash

python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>

has_report: true

job_status.status: success

, fetch the report:

bash

python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID>

If the job is still running, continue polling:

bash

python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>

症状：

本地轮询被中断。
任务持续显示
```
running
```
状态。
轮询输出显示
```
running
```
，但已返回报告或取消操作提示任务已
```
success
```
。

原因：

深度研究为异步任务，会在服务器端继续运行。
本地轮询输出可能滞后于服务器端实际状态。

解决方案：

检查当前状态：

bash

python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>

若

has_report: true

或

job_status.status: success

，获取报告：

bash

python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID>

若任务仍在运行，继续轮询：

bash

python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>