Generated banner for Aiq Research
Generated logo for Aiq Research

Aiq Research

OpenAIOfficialCreated by NVIDIA AI-Q Blueprint TeamDistributed by OpenAI

  • Skill
  • Tool integration
  • Data and AI
  • Apache-2.0
  • Medium risk
  • Has scripts

From the author

Use when asked to run deep research or AI-Q research through a reachable NVIDIA AI-Q Blueprint backend.
— the description by NVIDIA AI-Q Blueprint Team

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/openai/aiq-research/download
  2. Unzip 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_URL set when the backend is not running at http://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

  1. Resolve the target backend URL.

  2. Run health before sending research requests.

  3. If no backend is reachable, ask for a backend URL or hand off to aiq-deploy.

  4. 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.

  5. Poll asynchronous deep research jobs when AI-Q returns a job ID.

  6. Present returned reports with citations and source URLs intact.

  7. 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_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.

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:

  1. Check for an updated skill version matching your Blueprint version.

  2. Use a Blueprint version compatible with this skill.

  3. Proceed with caution only when the user accepts the compatibility risk; API routes or response shapes may have changed.

Available Scripts

ScriptPurposeArguments
scripts/aiq.py healthCheck whether the configured server respondsnone
scripts/aiq.py chatPOST /chat; may return inline output or a deep-research job ID<query>
scripts/aiq.py agentsList available async agent typesnone
scripts/aiq.py submitSubmit an explicit async job<query> [agent_type]
scripts/aiq.py researchSubmit an async job, poll, and print the final report JSON<query> [agent_type]
scripts/aiq.py research_pollResume polling an existing async job<job_id>
scripts/aiq.py statusFetch job status plus /state artifacts<job_id>
scripts/aiq.py stateFetch event-store artifacts only<job_id>
scripts/aiq.py reportFetch the final report for a completed job<job_id>
scripts/aiq.py streamStream SSE events from a job<job_id>
scripts/aiq.py cancelCancel 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

VariableRequiredDefaultDescription
AIQ_SERVER_URLNohttp://localhost:8000Local 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_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.

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

TopicDocumentation
Helper scriptscripts/aiq.py
Deployment and backend validation../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:

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

  2. If they provide one, set it and rerun health:

    export AIQ_SERVER_URL="http://localhost:<PORT>"
    python3 $SKILL_DIR/scripts/aiq.py health
  3. If they want a local backend, hand off to aiq-deploy and preserve the original research request.

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:

  1. Stop and explain that this public skill does not manage authentication.

  2. Ask the user to use an authenticated AI-Q skill or configure their backend for this public local workflow.

  3. Rerun health and the original query only after the authentication boundary is resolved.

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:

  1. Run:

    python3 $SKILL_DIR/scripts/aiq.py agents
  2. If agents are unavailable, report the compatibility failure and offer to run aiq-deploy validation.

  3. 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 already success.

Causes:

  • Deep research is asynchronous and continues server-side.

  • Local polling output can lag behind terminal server state.

Solutions:

  1. Check current state:

    python3 $SKILL_DIR/scripts/aiq.py status <JOB_ID>
  2. If has_report: true or job_status.status: success, fetch the report:

    python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID>
  3. If the job is still running, continue polling:

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

Files

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