aiq-research

AIQ Research スキル

目的

このスキルは、scripts/aiq.py のヘルパースクリプトを通じて、ローカルで実行中の NVIDIA AI-Q Blueprint サーバーを呼び出すために使用します。

次のようなリサーチ形式のリクエストに使用してください。

• 「…について詳しく調査して」
• 「AIQ リサーチ …」
• 「…を調査して」
• 「AI-Q を使って…に回答して」
• 「…について AI-Q に尋ねて」

インストール、デプロイ、起動、停止、UI、CLI、Docker、Helm、トラブルシューティングのリクエストには、このスキルを使用しないでください。それらには aiq-deploy を使用します。

前提条件

ユーザーには次のものが必要です。

• python3 として利用可能な Python 3.11 以降。
• 接続可能なローカルまたはセルフホスト型の AI-Q Blueprint バックエンド。
• バックエンドが http://localhost:8000 以外で実行されている場合は、AIQ_SERVER_URL が設定されていること。ローカル以外の値を使用する場合、クエリを送信する前にユーザーがその値を信頼できることを確認する必要があります。
• このパブリックヘルパーを使う場合は認証が無効に設定されたバックエンド、または認証が必要な環境向けの別の認証済み AI-Q スキル。
• ローカルマシンから AI-Q バックエンド URL へのネットワークアクセス。
• このスキルではなく、バックエンド環境で設定された認証情報。このパブリックヘルパーは API キーを収集または管理しません。

このヘルパースクリプトにサードパーティ製の Python パッケージ依存関係はありません。Python 標準ライブラリの HTTP モジュールを使用します。

手順

1. 対象のバックエンド URL を解決します。
2. リサーチリクエストを送信する前に health を実行します。
3. 接続可能なバックエンドがない場合は、バックエンド URL を尋ねるか、aiq-deploy に引き継ぎます。
4. ユーザーのクエリを送信する前に、そのクエリを受け取る AI-Q バックエンドの正確な URL を伝えます。ローカル以外の URL の場合は、現在の会話でユーザーがその URL を信頼できると明示的に確認した場合にのみ続行します。
5. AI-Q がジョブ ID を返した場合は、非同期の深層リサーチジョブの状態をポーリングします。
6. 返されたレポートは、引用とソース URL をそのまま保持して提示します。
7. ジョブが失敗した場合は処理を停止し、返されたエラーを表示します。自動的に再試行しないでください。
8. レポートを提示した後も、フォローアップに対応します。レポートについての質問に回答する（ask）か、同じコマンドを使って条件を調整したリサーチを実行する（redo）ことができます。

ステップ 1 - バックエンドを解決する

AIQ_SERVER_URL が設定されている場合はそれを使用します。設定されていない場合は、デフォルトのローカルバックエンドを試します。

python3 $SKILL_DIR/scripts/aiq.py health

期待される出力：接続可能な AI-Q ヘルスエンドポイントからの JSON。

health が失敗し、明示的な AIQ_SERVER_URL も設定されていない場合は、次のように尋ねます。

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?

• ユーザーが URL を指定した場合は、以降のヘルパー呼び出し用に AIQ_SERVER_URL を設定し、health を再実行します。
• ユーザーがローカルへのデプロイを希望する場合は、元のリサーチリクエストを引き継いで aiq-deploy に引き継ぎます。
• 接続可能なバックエンドが 401 または 403 を返した場合は、処理を停止し、このパブリックスキルでは認証を管理しないことを説明します。認証済み AI-Q スキルを使用するか、環境の認証を設定するようユーザーに依頼します。
• health は成功するものの、/chat または /v1/jobs/async/agents が失敗する場合は、バックエンドには接続できるものの、このパブリックなリサーチフローには対応していないことを報告し、aiq-deploy による検証を提案します。

ステップ 2 - 振り分けられたリサーチリクエストを送信する

リクエストを送信する前に、解決されたエンドポイントを伝えます。

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

クエリのテキストに認証情報、Cookie、ベアラートークン、または秘密の値を含めないでください。

次を実行します。

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

期待される出力：

• 簡易な回答または直接的な回答の場合は、通常の JSON レスポンス。
• または、非同期の深層リサーチの場合は、{"status": "deep_research_running", "job_id": "<JOB_ID>"} を含む構造化 JSON。

レスポンスが通常の JSON の場合は、結果をすぐに提示します。job_id がないときは、無理にポーリングしないでください。

ステップ 3 - 非同期ジョブをポーリングする

レスポンスに deep_research_running が含まれている場合は、job_id を取り出し、同じ絶対パスのスクリプトでポーリングします。

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

期待される出力：ジョブが正常に完了したときの最終レポート JSON。

利用可能な場合は、ランタイムのノンブロッキングまたはバックグラウンド実行の仕組みを使用します。選択した実行方法に昇格された権限が必要な場合は、その理由を説明し、先にユーザーの明示的な承認を求めます。深層リサーチをバックグラウンドで実行中であることをユーザーに伝えます。

Step 4 - 中断後の再開

ポーリングが中断されても、ジョブはサーバー側で継続します。次のようにして再開してください。

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 を使います。

最終レポートでは、生成されたアーティファクト（グラフ、CSV など）が artifact://<id> リンクとして参照される場合があります。ローカルファイルとして保存するには、python3 $SKILL_DIR/scripts/aiq.py artifacts <JOB_ID> --download-dir ./aiq-artifacts を実行します。各アーティファクトがダウンロードされ、ローカルパスが出力されます。レポート内に base64 形式の画像データが含まれるとは限りません。

自己完結型で共有可能なレポートを作成するには、python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID> --out-dir ./my-report を実行します。report.md と artifacts/ フォルダーが作成され、各 artifact://<id> リンクが対応するローカルファイルへのリンクに書き換えられます。そのため、バックエンドが稼働していなくても、あらゆる Markdown ビューアーでレポート（グラフを含むすべて）が表示されます。

Step 5 - レポートの提示

research_poll が正常に完了したら、レポート全体を取得して提示します。引用とソース URL はそのまま保持してください。 ジョブのステータスが failed、failure、または cancelled の場合は、ステータス応答に含まれるエラーを表示し、より絞り込んだクエリや別の方法で再試行するかユーザーに確認します。

Step 6 - フォローアップ：レポートについて質問、編集、または再実行する

レポートを提示した後、ユーザーはさらに詳しく調べたり、対象範囲を調整したりすることがよくあります。 既存のバックエンドフローを再利用します。Steps 1-5 と同じ認証境界、ポーリング、レポート取得が適用されます。フォローアップ専用のエンドポイントはありません。

質問 — すでに取得したレポートについてのフォローアップ質問：

• すでに取得したレポートの内容から回答できる質問には、その内容と引用に基づいて直接回答します。バックエンドを再度呼び出してはいけません。

• 新たな調査が必要な質問には、以前の質問とレポートから必要なコンテキストを新しいクエリテキストに含めて、新しいリクエストを送信してから新しい結果を提示します。

  python3 $SKILL_DIR/scripts/aiq.py chat "<FOLLOW_UP_QUESTION> (context: <PRIOR_TOPIC>)"
  

  これにより deep_research_running のジョブ ID が返された場合は、Step 3 と同じ手順で research_poll を使ってポーリングします。

編集 — 表面的な変更を加えてレポートを書き直します。このスキルがアクセスできるのは、最初のレポートの生成に使用したデータのみです。利用可能なツールはありません。

python3 $SKILL_DIR/scripts/aiq.py report_edit <JOB_ID> "<EDIT_INSTRUCTIONS>"

再実行 — 対象範囲を調整して（より絞り込んだクエリ、修正した質問、または異なる深さで）調査を再実行します。

python3 $SKILL_DIR/scripts/aiq.py research "<REFINED_QUERY>" [agent_type]

• 希望する調査の深さに合わせて agent_type を選択します（たとえば、徹底的に調査するには deep agent、素早く調査するには shallow_researcher）。選択肢が不明な場合は、agents で一覧を確認します。
• 再実行は新しいジョブとして扱います。送信前に対象エンドポイントを改めて指定し（Step 2）、Steps 3-5 と同じ手順でポーリングして結果を提示します。

フォローアップのクエリテキストに認証情報や秘密の値を含めないでください。また、すべてのフォローアップ回答で引用とソース URL をそのまま保持してください。

バージョン互換性

重要： このスキルは NVIDIA AI-Q Blueprint バージョン 2.1.0 向けに設計されています。

セマンティックバージョニングの互換性ルール：

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)

例：

• スキルバージョン 2.1.0 は Blueprint バージョン 2.1.0 と互換性があります。
• スキルバージョン 2.1.0 は Blueprint バージョン 2.2.0 と互換性があります。
• スキルバージョン 2.1.0 は Blueprint バージョン 2.1.5 と互換性があります。
• スキルバージョン 2.1.0 は Blueprint バージョン 3.0.0 と互換性がありません。
• スキルバージョン 2.1.0 は Blueprint バージョン 2.0.0 と互換性がありません。

Blueprint のバージョンに互換性がない場合：

1. Blueprint のバージョンに対応する更新済みのスキルバージョンがあるか確認します。
2. このスキルと互換性のある Blueprint のバージョンを使用します。
3. ユーザーが互換性のリスクを受け入れた場合に限り、注意して続行します。API ルートや応答形式が変更されている可能性があります。

利用可能なスクリプト

スクリプト	目的	引数
scripts/aiq.py health	設定されたサーバーが応答するか確認します	なし
scripts/aiq.py chat	/chat に POST します。インライン出力またはディープリサーチのジョブ ID が返される場合があります	<query>
scripts/aiq.py agents	利用可能な非同期エージェントの種類を一覧表示します	なし
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	最終レポートを取得します。--out-dir DIR を指定すると、リンクをローカルファイルに書き換えた、持ち運び可能な report.md と artifacts/ フォルダーをエクスポートします	<job_id> [--out-dir DIR]
scripts/aiq.py report_edit	完了したレポートを見た目の変更のみ編集します	<job_id> <edit_instructions>
scripts/aiq.py artifacts	永続的なアーティファクトを一覧表示します。--download-dir DIR を指定すると、ダウンロードしてローカルパスを出力します	<job_id> [--download-dir DIR]
scripts/aiq.py stream	ジョブの SSE イベントをストリームします	<job_id>
scripts/aiq.py cancel	実行中のジョブをキャンセルします	<job_id>

ホストが run_script() ヘルパーに対応している場合は、scripts/aiq.py と上記の引数を指定して呼び出します。そうでない場合は、python3 $SKILL_DIR/scripts/aiq.py health のような同等のシェルコマンドを実行します。

環境変数

変数	必須	デフォルト	説明
AIQ_SERVER_URL	いいえ	http://localhost:8000	ローカルまたはセルフホスト可能な AI-Q サーバーのベース URL

セキュリティのベストプラクティス

• API キー、ベアラートークン、Cookie、または基本認証の認証情報を AIQ_SERVER_URL に設定しないでください。
• バックエンドの認証情報は、このスキルやコマンド例ではなく、AI-Q のデプロイ環境に保存してください。
• ユーザーのクエリテキストは、設定された AIQ_SERVER_URL に送信されます。機密情報や秘密情報を送信する前に、エンドポイントが信頼できることを確認してください。
• バックエンドが非公開データソースを使用している場合、返されたレポートには機密情報が含まれている可能性があるものとして扱ってください。
• 返されたレポートから引用やソース URL を省略しないでください。

制限事項

• このスキルを使用するには、実行中の AI-Q バックエンドが必要です。このスキルはバックエンドをデプロイしません。
• 公開ヘルパーは認証トークンや Cookie を管理しません。
• リモートの AIQ_SERVER_URL エンドポイントでは、プロンプト、応答、メタデータがログに記録される場合があります。
• バックエンドが HTTP 500 を返す場合、または非同期エージェントがない場合は、調査結果を作り上げずに失敗を報告してください。

例

例 1：ルーティングされたチャットまたは調査リクエストを実行する

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"

予想される出力：

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

AI-Q からジョブ ID が返された場合は、research_poll を続けて実行してください。

例 2：既存のジョブを再開する

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 が続きます。ジョブが失敗した場合は、返されたステータスを表示し、自動で再試行しないでください。

例 3：追加の質問をする、またはクエリを調整してやり直す

# Ask: a follow-up that needs new investigation, carrying prior context.
python3 $SKILL_DIR/scripts/aiq.py chat "How does that compare on cost? (context: local AIQ deep research vs web search)"

# Redo: re-run research with a narrower query and explicit depth.
python3 $SKILL_DIR/scripts/aiq.py research "AIQ deep research cost on a single workstation" shallow_researcher

予想される出力：ルーティングされたチャット応答、または research_poll でポーリングする新しい deep_research_running ジョブ ID。引用とソース URL を保持したまま、追加の質問への回答を提示してください。

参考資料

トピック	ドキュメント
ヘルパースクリプト	scripts/aiq.py
デプロイとバックエンドの検証	../aiq-deploy/SKILL.md

よくある問題

問題：到達可能なバックエンドがありません

症状：

• health が接続拒否で失敗します。
• デフォルトの http://localhost:8000 URL が応答しません。

原因：

• AI-Q が実行されていません。
• AI-Q が別のホストまたはポートで実行されています。
• ローカルのファイアウォールまたはネットワーク設定が接続をブロックしています。

解決策：

1. ユーザーに既存の AI-Q バックエンド URL があるか確認します。
2. URL が提供された場合は、設定してヘルスチェックを再実行します：

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

3. ローカルバックエンドを希望する場合は、元の調査リクエストを保持したまま aiq-deploy に引き継ぎます。

問題：バックエンドで認証が必要です

症状：

• リクエストが HTTP 401 または HTTP 403 で失敗します。
• バックエンドには到達できますが、/chat または非同期ジョブの呼び出しが拒否されます。

原因：

• バックエンドで認証を有効にしてデプロイされています。
• パブリックヘルパーはユーザートークンや Cookie を付加しません。

解決策：

1. 処理を中止し、このパブリックスキルでは認証を管理できないことを説明します。
2. 認証済みの AI-Q スキルを使用するか、このパブリックなローカルワークフロー向けにバックエンドを設定するようユーザーに依頼します。
3. 認証の境界が解決してから health と元のクエリを再実行します。

問題：ヘルスチェックは成功するが、調査ルートが失敗します

症状：

• health は正常に応答します。
• /chat、/v1/jobs/async/agents、またはポーリングコマンドが失敗します。

原因：

• バックエンドが API 対応の AI-Q 設定を使用していません。
• 選択したバックエンドで非同期ジョブレジストリを利用できません。
• バックエンドのバージョンがこのスキルと互換性がありません。

解決策：

1. 次を実行します：

   python3 $SKILL_DIR/scripts/aiq.py agents
   

2. エージェントを利用できない場合は、互換性の問題を報告し、aiq-deploy による検証を提案します。
3. デプロイされた Blueprint のバージョンがスキルバージョン 2.1.0 と互換性があることを確認します。

問題：ジョブが中断された、または停止しているように見えます

症状：

• ローカルのポーリングが中断されます。
• ジョブが running のまま表示されます。
• ポーリング出力には running と表示されますが、レポートが返されるか、キャンセル時にジョブはすでに success であると表示されます。

原因：

• 詳細な調査は非同期で、サーバー側で継続されます。
• ローカルのポーリング出力が、サーバーの最終状態より遅れることがあります。

解決策：

1. 現在の状態を確認します：

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

2. has_report: true または job_status.status: success の場合は、レポートを取得します：

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

3. ジョブがまだ実行中の場合は、ポーリングを続けます：

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