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。

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

ステップ 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 を使います。

ステップ 5 - レポートを提示する

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

ステップ 6 - フォローアップ：レポートについて質問する、またはやり直す

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

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

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

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

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

  これが deep_research_running のジョブ ID を返した場合は、ステップ 3 とまったく同じように research_poll でポーリングします。

やり直す — 範囲を調整して調査を再実行する（クエリを絞り込む、質問を修正する、または深度を変える）：

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

• 希望する深度に合わせて agent_type を選択します（たとえば、徹底的に調査する場合は deep agent、素早く調査する場合は shallow_researcher）。不明な場合は、agents で選択肢を一覧表示します。
• やり直しは新しいジョブとして扱います。送信前に対象のエンドポイントを再度指定し（ステップ 2）、ステップ 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	完了したジョブの最終レポートを取得します	<job_id>
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 が提示された場合は、それを設定して health を再実行します：

   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 は成功するが、リサーチのルートが失敗する

症状：

• 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>