aiq-research
Use when asked to run deep research or AI-Q research through a reachable NVIDIA AI-Q Blueprint backend.
- License 许可
- Apache-2.0
- 最近更新
- 2026-08-25
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- aiq-research
- license
- Apache-2.0
- metadata
- { "tags": [ "nvidia", "aiq", "blueprint", "deep-research", "research-agents", "agent-skills" ], "author": "NVIDIA AI-Q Blueprint Team <aiq-blueprint@nvidia.com>", "domain": "research-agents", "version": "2.1.0", "languages": [ "python", "bash" ], "github-url": "https://github.com/NVIDIA-AI-Blueprints/aiq" }
- description
- Use when asked to run deep research or AI-Q research through a reachable NVIDIA AI-Q Blueprint backend.
- permissions
- { "env": [ "AIQ_SERVER_URL" ], "network": [ "http://localhost:8000" ] }
- allowed-tools
- Read Bash
- compatibility
- Designed for Claude Code, OpenCode, Codex, and Agent Skills-compatible tools. Requires Python 3.11+ and network access to a running local AI-Q Blueprint server at `http://localhost:8000` by default. Non-local backends must be explicitly trusted by the user and granted by the host tool outside this public skill.
02 资源文件 6
- 参考文档agents/openai.yaml169 B
- 参考文档BENCHMARK.md3.7 KB
- 参考文档evals/evals.json2.3 KB
- 脚本scripts/aiq.py18.0 KB
- 参考文档skill-card.md3.7 KB
- 其他skill.oms.sig4.7 KB
03 SKILL.md 正文
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.
Prerequisites
Users need:
- Python 3.11+ available as
python3. - A reachable local or self-hosted AI-Q Blueprint backend.
AIQ_SERVER_URLset when the backend is not running athttp://localhost:8000; non-local values must be trusted by the user before any query is sent.- 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.
Instructions
- Resolve the target backend URL.
- Run
healthbefore sending research requests. - If no backend is reachable, ask for a backend URL or hand off to
aiq-deploy. - Before sending any user query, state the exact AI-Q backend URL that will receive it. For non-local URLs, continue only if the user has explicitly confirmed that URL is trusted in the current conversation.
- 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.
Step 1 - Resolve the backend
Use AIQ_SERVER_URL when set. Otherwise try the default local backend:
python3 $SKILL_DIR/scripts/aiq.py health
Expected output: JSON from a reachable AI-Q health endpoint.
If health fails and no explicit AIQ_SERVER_URL was set, ask:
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_URLfor subsequent helper calls and rerunhealth. - If the user wants local deployment, hand off to
aiq-deployand preserve the original research request. - If a reachable backend returns
401or403, 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
healthsucceeds but/chator/v1/jobs/async/agentsfails, report that the backend is reachable but not compatible with this public research flow, then offer to runaiq-deployvalidation.
Step 2 - Send the routed research request
Before sending the request, state the resolved endpoint:
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:
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.
Step 3 - Poll asynchronous jobs
If the response includes deep_research_running, extract the job_id and poll with the same absolute script path:
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.
Step 4 - Resume after interruptions
If polling is interrupted, the job continues server-side. Resume with:
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.
Step 5 - Present the report
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.
Version Compatibility
IMPORTANT: This skill is designed for NVIDIA AI-Q Blueprint version 2.1.0.
Semantic Versioning Compatibility Rules:
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.
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.
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
AIQ_SERVER_URL |
No | http://localhost:8000 |
Local or self-hosted AI-Q server base 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.
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_URLendpoints 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.
Examples
Example 1: Run a routed chat or research request
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:
<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.
Example 2: Resume an existing job
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.
References
| Topic | Documentation |
|---|---|
| Helper script | scripts/aiq.py |
| Deployment and backend validation | ../aiq-deploy/SKILL.md |
Common Issues
Issue: No backend is reachable
Symptoms:
healthfails with connection refused.- The default
http://localhost:8000URL 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:
export AIQ_SERVER_URL="http://localhost:<PORT>" python3 $SKILL_DIR/scripts/aiq.py health - If they want a local backend, hand off to
aiq-deployand preserve the original research request.
Issue: Backend requires authentication
Symptoms:
- Requests fail with HTTP 401 or HTTP 403.
- The backend is reachable but rejects
/chator 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
healthand the original query only after the authentication boundary is resolved.
Issue: Health succeeds but research routes fail
Symptoms:
healthreturns 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:
python3 $SKILL_DIR/scripts/aiq.py agents - If agents are unavailable, report the compatibility failure and offer to run
aiq-deployvalidation. - Confirm the deployed Blueprint version is compatible with skill version 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 alreadysuccess.
Causes:
- Deep research is asynchronous and continues server-side.
- Local polling output can lag behind terminal server state.
Solutions:
- Check current state:
python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID> - If
has_report: trueorjob_status.status: success, fetch the report:python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID> - If the job is still running, continue polling:
python3 $SKILL_DIR/scripts/aiq.py research_poll <JOB_ID>
04 同仓库更多 Skills
syllabus
Generates a curated supplementary reading list from any course syllabus using Consensus academic search. Grill-me intake (syllabus input format + course audience + year range) plus a grouping forcing-options checkpoint before any search runs — so the reading list matches the course's level and recency need. Parses the syllabus to extract topics and learning outcomes, searches Consensus for recent peer-reviewed papers per topic, and produces a professionally formatted .docx with clickable Consensus links, plain-language summaries calibrated to audience level, and Bloom-higher-order discussion questions tied to course learning goals. Use when the user uploads a syllabus, course outline, or curriculum document and wants supplementary readings (e.g., 'create a reading list from this syllabus', 'find recent papers for my course') — even casual mentions with a syllabus attached should trigger this skill.
pulse
Multi-source recency research skill that takes the pulse of any topic across Reddit, Hacker News, the open web, and optionally X/Twitter within a configurable recent window (default 30 days). Forcing intake clarifies topic specificity, angle (trend/sentiment/problems/opportunities/comparison), time window, and platform scope before searching. Returns a synthesized briefing with citations, engagement metrics, and cross-platform pattern analysis. Use when the user requests multi-source recency intelligence on a topic (e.g., 'pulse on [topic]', 'what's happening with [topic]', 'what are people saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]'), and for competitor research, trend discovery, tool comparisons, and audience sentiment analysis.
patent
Patent prior-art and landscape intelligence skill — not generic patent help. Commits to one of five sub-use-cases via forcing intake (novelty search / freedom-to-operate / competitive landscape / acquisition diligence / litigation prior-art) before any search runs. Searches Google Patents, Espacenet, USPTO, and optionally Lens.org for citation-graph signals. Output is an editable Word document (.docx) with verdict, ranked closest art (claim-text extracted), CPC-class-aware landscape, family-resolved hits, geographic coverage, FTO flags where applicable, strategy recommendations, and full audit log. Use when the user asks for patent searching or analysis (e.g., 'prior art search for [invention]', 'freedom to operate analysis for [product]'). Produces search signal, not legal advice — always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope.
notebooklm
Browser automation skill for controlling Google's NotebookLM. Use when the user wants anything done in NotebookLM (e.g., 'open NotebookLM', 'check my [name] notebook', 'ask my notebook about X', 'add [source] to NotebookLM', 'generate a Video Overview from my notebook', 'use NotebookLM Studio'). Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio/Video Overviews, Mind Maps, Reports incl. Briefing Doc/Study Guide/FAQ, Flashcards, Quiz, slide decks, infographics — discover the exact set from the live Studio panel; the UI evolves fast), and creating new notebooks. Requires browser automation environment — fails gracefully when unavailable.
litreview
Academic literature orientation skill that searches papers via free keyless APIs (PubMed E-utilities + OpenAlex) by default — with the Consensus MCP as an optional enhancement lane when connected — builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a formatted Word (.docx) research guide. Grill-me intake (research question specificity + framework hint + tentative depth) before the recon search; a second forcing checkpoint after Phase 2 confirms framework + sub-areas + depth before searches consume budget. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' — an orientation guide that lets a researcher dive in confidently, not a finished review. Use when the user starts literature-oriented research (e.g., 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'). Do NOT use for single one-off paper searches wanting a quick list — that's a plain PubMed/OpenAlex (or Consensus) query.
grants
NIH grant research skill for clinical researchers. Grill-me intake (research idea + career stage + preliminary data + environment + submission posture + known institute targets) locks down the funding strategy before any search runs. Runs a 5-facet Consensus positioning analysis (with draft Significance/Innovation language), maps the research to the right NIH institutes and study sections via RePORTER, finds NOSIs and funded overlap, and produces an editable Word document (.docx) with budget/scope-aware mechanism recommendations, submission timelines, and a mandatory program officer recommendation. Use when the user asks about research funding or makes any grant-related request (e.g., 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research'). NIH-only scope — non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake.