Réponses à des questions sur des vidéos via VLM à travers VSS Agent

Utilisez cette compétence quand vous avez besoin de détails sur la vidéo qui nécessitent qu'un VLM examine les images vidéo — par exemple l'agent n'a aucune réponse préalable utilisable et a besoin d'un regard nouveau sur les pixels pour un clip spécifique.

Quand utiliser

• L'utilisateur demande ce qui se passe dans la vidéo, quels objets / personnes / actions apparaissent, couleurs, timing, sécurité, ou autres faits visuels qui nécessitent de regarder le clip.
• L'utilisateur demande des détails qui ne peuvent pas être répondus à partir des messages existants, résumés, résultats Elasticsearch/MCP, ou noms de fichiers seuls — vous avez besoin d'une inférence du modèle sur la vidéo.
• Questions de suivi sur les détails du contenu après un résumé grossier ou après génération de rapport.

N'utilisez pas cette compétence quand une base de données / MCP / sortie d'outil antérieur répond déjà à la question, à moins que l'utilisateur ne demande explicitement une vérification contre la vidéo.

Prérequis de déploiement

Cette compétence nécessite un profil VSS qui servit l'outil video_understanding — typiquement base (recommandé) ou lvs. Avant toute demande :

1. Sondez l'agent VSS :

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

2. Si le sondage échoue, demandez à l'utilisateur :

   "Aucun profil VSS n'est exécuté sur $HOST_IP. Dois-je déployer base (recommandé pour Q&A VLM par clip) en utilisant la compétence /vss-deploy-profile ? Si vous préférez lvs, dites-le."

   • Si oui → transférez vers /vss-deploy-profile -p base (ou -p lvs si l'utilisateur préfère). Revenez ici une fois que c'est réussi.
   • Si non → arrêtez.

3. Si le sondage réussit, continuez.

Prérequis capteur

Vous DEVEZ lister les capteurs VST avant tout appel /generate. Ceci est obligatoire même quand l'utilisateur nomme le capteur explicitement, même quand l'utilisateur affirme que la vidéo est déjà téléchargée, et même quand un tour antérieur semblait utiliser la même vidéo. Ne sautez pas cette étape.

1. Listez les capteurs :

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

2. Comparez les valeurs name retournées contre l'<sensor-id> fourni par l'utilisateur (ou nom de fichier sans extension, p. ex. warehouse_safety_0001).

3. Si un capteur correspondant est présent → passez au workflow Agent ci-dessous.

4. Si aucun capteur correspondant n'est présent — téléchargez d'abord la vidéo, puis relister pour confirmer que le nouveau capteur apparaît :

   # filename: ne doit pas contenir d'espaces
   # timestamp: ISO 8601 UTC — par défaut 2025-01-01T00:00:00.000Z si l'utilisateur n'a pas spécifié
   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 .

   Consultez /vss-manage-video-io-storage pour la sémantique complète du téléchargement (v1 vs v2, gestion des conflits, flux de suppression). Dans les exécutions interactives, confirmez avec l'utilisateur avant de télécharger. Ne lancez jamais un PUT sans condition sans d'abord exécuter la vérification de la liste des capteurs ci-dessus — c'est exactement le mode d'échec que ce prérequis est destiné à prévenir.

Workflow Agent

Le prérequis Capteur ci-dessus doit avoir déjà confirmé (ou créé) que le capteur existe sur VST. Ensuite :

1. Clip — Identifiez l'id du capteur, nom de fichier, ou URL pour un segment vidéo. Si c'est ambigu, demandez à l'utilisateur.
2. Appelez l'agent vss avec l'id du capteur et demandez-lui d'appeler l'outil video_understanding pour répondre à la question de l'utilisateur.
3. Retournez la réponse de l'agent vss à l'utilisateur.

Interroger l'agent VSS (/generate)

# Définir à partir du déploiement (compose / .env / hôte où vss-agent écoute)
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 .

Contrat de réponse et extraction

/generate retourne un objet JSON avec la sortie de l'assistant dans value, par exemple :

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

Il n'y a pas de champ de réponse nettoyée séparé. La réponse consommable est le texte dans .value après suppression de tout bloc <agent-think>...</agent-think>.

Gestion requise pour cette compétence (et tout appelant en aval) :

1. Lisez .value de la réponse JSON.
2. Supprimez les sections <agent-think>...</agent-think> partout où elles apparaissent.
3. Retournez uniquement le texte de réponse finale restant à l'utilisateur.

Exemple d'extraction :

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())'

Références croisées

• vss-manage-video-io-storage — URLs de stockage/relecture VST pour que VIDEO_URL soit valide pour le VLM.
• vss-generate-video-report — rapports horodatés via Mode A (VLM direct) ou Mode B (incidents video-analytics) ; cette compétence est /generate d'agent VSS pour Q&A vidéo ad hoc.