Aiq Research
OpenAIOfficialCreated by NVIDIA AI-Q Blueprint TeamDistributed by OpenAI
- Skill
- Tool integration
- Data and AI
- Apache-2.0
- Medium risk
- Has scripts
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
The aiq-research skill provides a standardized interface for interacting with a running NVIDIA AI-Q Blueprint server. It enables users to execute research queries, manage asynchronous deep research jobs, and retrieve final reports directly through a helper script. The skill is designed for environments where a local or self-hosted AI-Q backend is already operational, focusing on research-oriented tasks while maintaining clear boundaries regarding authentication and deployment.
What it does
- Checks the health and connectivity of a configured AI-Q Blueprint backend.
- Routes research queries to the AI-Q server for processing.
- Polls and monitors the status of asynchronous deep research jobs.
- Retrieves and presents final research reports with original citations and source URLs.
- Supports job management actions including status checks, state inspection, and job cancellation.
When to use it
- When you need to perform deep research or AI-Q specific queries.
- When you have a running NVIDIA AI-Q Blueprint backend available.
- When you need to resume or check the status of a previously initiated research job.
- When you require structured research output including source citations.
Advantages
- Provides a consistent interface for interacting with AI-Q Blueprint services.
- Handles asynchronous job polling automatically to ensure report retrieval.
- Maintains transparency by requiring explicit trust for non-local backend URLs.
- Separates research execution from deployment and authentication concerns.
Usage examples
- “Run deep research on the impact of AI-Q Blueprints in enterprise environments.”
- The agent verifies the AI-Q backend health, submits the query, and polls the resulting job ID until the final research report is retrieved and displayed.
- “Check the status of my previous research job with ID 12345.”
- The agent uses the status script to report the current progress of the job and provides the final report if the job has completed.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/openai/aiq-research/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip aiq-research.zip -d .agents/skills
Documentation by NVIDIA AI-Q Blueprint Team
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 healthExpected 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 healthIf 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 agentsIf 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>
Files
- ATTRIBUTION.mdAdded by AutoGineer1023 B
- BENCHMARK.md3.7 KiB
- LICENSEAdded by AutoGineer10.0 KiB
- SKILL.md12.5 KiB
- agents/openai.yaml169 B
- evals/evals.json2.3 KiB
- scripts/aiq.pyScript18.0 KiB
- skill-card.md3.7 KiB
- skill.oms.sig4.7 KiB
LICENSE
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Requirements and compatibility
Written for: OpenAI Codex, Claude Code, OpenCode
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Declares allowed tools, Needs an API key, Needs Python
The author says: 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.
Security
What our scanner noticed· Medium risk
- Large base64-encoded blobs
- Scripts that your agent may run
This skill includes scripts that your agent may run. Read them before you use it.
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Created by
- NVIDIA AI-Q Blueprint Team
- Publisher
- OpenAI (Official)
- Distributed by
- OpenAI
- Source
- openai/plugins · plugins/nvidia/skills/aiq-research · commit d420d13
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (written by AutoGineer)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by NVIDIA AI-Q Blueprint Team or OpenAI.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aiq-research.zip