vss-ask-video

VSS Agent を介した VLM による動画 Q&A

VLM で動画フレームを確認する必要がある動画について詳しく知りたい場合に、このスキルを使用します。たとえば、エージェントに利用可能な過去の回答がなく、特定のクリップのピクセルを改めて確認する必要がある場合です。

---

使用するタイミング

• ユーザーが、動画で何が起きているか、どのような物体／人物／動作が映っているか、色、タイミング、安全性、その他、クリップを視聴しないとわからない視覚的な事実を尋ねている場合。
• ユーザーが、既存のメッセージ、要約、Elasticsearch/MCP の結果、またはファイル名だけでは回答できない詳細を尋ねており、動画に対するモデルの推論が必要な場合。
• 大まかな要約の後、またはレポート生成後に、内容の詳細について追加で質問された場合。

データベース／MCP／以前のツール出力ですでに質問への回答が得られている場合は、ユーザーが動画との照合を明示的に求めていない限り、このスキルを使用しないでください。

---

デプロイの前提条件

このスキルを使用するには、video_understanding ツールを提供する VSS プロファイルが必要です。通常は base（推奨）または lvs を使用します。リクエストを処理する前に、次の手順を実行してください。

1. VSS エージェントを確認します。

   curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null
   

2. 確認に失敗した場合は、ユーザーに尋ねます。

   "$HOST_IP で VSS プロファイルが実行されていません。クリップ単位の VLM Q&A に推奨される base を /vss-deploy-profile スキルでデプロイしますか？lvs を希望する場合は、そのようにお知らせください。"

   • はいの場合 → /vss-deploy-profile -p base（ユーザーが希望する場合は -p lvs）に引き継ぎます。デプロイが成功したら、ここに戻ります。
   • いいえの場合 → 停止します。

3. 確認に成功した場合は、続行します。

---

センサーの前提条件

/generate を呼び出す前に、必ず VST センサーを一覧表示してください。 ユーザーがセンサーを明示的に指定している場合、動画がすでにアップロード済みだと主張している場合、または前のターンで同じ動画を使用したように見える場合でも、必ず実行してください。この手順を省略しないでください。

1. センサーを一覧表示します。

   curl -sf --max-time 5 "http://${HOST_IP}:30888/vst/api/v1/sensor/list" | jq '.[].name'
   

2. 返された name の値を、ユーザーが指定した <sensor-id>（またはファイル名の拡張子を除いた部分。例：warehouse_safety_0001）と照合します。

3. 一致するセンサーがある場合 → 以下のエージェントワークフローに進みます。

4. 一致するセンサーがない場合 — 先に動画をアップロードし、新しいセンサーが表示されることを再度一覧表示して確認します。

   # filename: must not contain whitespace
   # timestamp: ISO 8601 UTC — default 2025-01-01T00:00:00.000Z if user did not specify
   curl -s -X PUT "http://${HOST_IP}:30888/vst/api/v1/storage/file/<filename>?timestamp=<timestamp>" \
     -H "Content-Type: application/octet-stream" \
     -H "Content-Length: <file_size_in_bytes>" \
     --upload-file /path/to/<filename> | jq .
   

アップロードの完全な仕様（v1 と v2、競合処理、削除の流れ）については、/vss-manage-video-io-storage を参照してください。対話形式で実行する場合は、アップロード前にユーザーに確認してください。上記のセンサー一覧の確認を先に実行せず、無条件の PUT を決して実行しないでください。この前提条件は、まさにその失敗を防ぐためのものです。

---

エージェントワークフロー

上記のセンサーの前提条件で、センサーが VST に存在することを確認（または作成）してから、次の手順を実行してください。

1. クリップ — 1 つの動画セグメントを特定するためのセンサー ID、ファイル名、またはURLを確認します。曖昧な場合は、ユーザーに尋ねてください。
2. センサー ID を指定して VSS エージェントを呼び出し、video_understanding ツールを呼び出してユーザーの質問に回答するよう依頼します。
3. VSS エージェントの回答をユーザーに返します。

VSS エージェントへの問い合わせ（/generate）

# Set from deployment (compose / .env / host where vss-agent listens)
export VSS_AGENT_BASE_URL="http://localhost:8000"

curl -s -X POST "${VSS_AGENT_BASE_URL}/generate" \
  -H "Content-Type: application/json" \
  -d '{"input_message": "Call video_understanding tool to answer the following question about <sensor-id>: <user query>"}' | jq .

レスポンスの仕様と抽出

/generate は、アシスタントの出力を value に含む JSON オブジェクトを返します。例：

{"value":"<agent-think><agent-think-step ...>...</agent-think-step></agent-think>\n\n<final answer>\n\n"}

独立したクリーンな回答フィールドはありません。利用できる回答は、.value から <agent-think>...</agent-think> ブロックを削除した後のテキストです。

このスキルおよび下流の呼び出し元には、次の処理が必要です。

1. JSON レスポンスから .value を読み取ります。
2. <agent-think>...</agent-think> セクションがどこにあっても削除します。
3. 残った最終回答のテキストのみをユーザーに返します。

抽出例：

curl -s -X POST "${VSS_AGENT_BASE_URL}/generate" \
  -H "Content-Type: application/json" \
  -d '{"input_message":"Call video_understanding tool to answer the following question about <sensor-id>: <user query>"}' \
| jq -r '.value' \
| python3 -c 'import re,sys; t=sys.stdin.read(); t=re.sub(r"<agent-think>.*?</agent-think>\s*", "", t, flags=re.S); print(t.strip())'

---

関連項目

• vss-manage-video-io-storage — VLM で VIDEO_URL が有効になる VST のストレージ／再生 URL。
• vss-generate-video-report — Mode A（直接 VLM）またはMode B（video-analytics のインシデント）によるタイムスタンプ付きレポート。このスキルは、アドホックな動画 Q&Aに使用する VSS エージェントの /generate です。