Skill de Recherche AIQ

Objectif

Utilisez ce skill pour appeler un serveur NVIDIA AI-Q Blueprint s'exécutant localement via le script d'aide disponible à scripts/aiq.py.

Utilisez ce skill pour les demandes de recherche, notamment :

• « recherche approfondie sur ... »
• « recherche AIQ ... »
• « recherche ... »
• « utiliser AI-Q pour répondre à ... »
• « poser une question à AI-Q sur ... »

N'utilisez pas ce skill pour les demandes d'installation, déploiement, démarrage, arrêt, interface utilisateur, CLI, Docker, Helm ou dépannage. Celles-ci relèvent de aiq-deploy.

Prérequis

Les utilisateurs ont besoin de :

• Python 3.11+ disponible en tant que python3.
• Un backend NVIDIA AI-Q Blueprint local ou auto-hébergé accessible.
• AIQ_SERVER_URL défini si le backend ne s'exécute pas à http://localhost:8000 ; les valeurs non locales doivent être approuvées par l'utilisateur avant tout envoi de requête.
• Un backend configuré avec l'authentification désactivée pour cet aide public, ou un skill AIQ distinct pour les environnements authentifiés.
• Un accès réseau de la machine locale vers l'URL du backend AIQ.
• Les identifiants configurés dans l'environnement du backend, pas dans ce skill. Cet aide public ne collecte ni ne gère les clés API.

Le script d'aide n'a aucune dépendance de package Python tiers ; il utilise les modules HTTP de la bibliothèque standard Python.

Instructions

1. Résolvez l'URL du backend cible.
2. Exécutez health avant d'envoyer les demandes de recherche.
3. Si aucun backend n'est accessible, demandez une URL de backend ou renvoyez vers aiq-deploy.
4. Avant d'envoyer toute requête utilisateur, indiquez l'URL exacte du backend AIQ qui la recevra. Pour les URLs non locales, continuez uniquement si l'utilisateur a explicitement confirmé que cette URL est approuvée dans la conversation en cours.
5. Interrogez les jobs de recherche approfondie asynchrone quand AIQ retourne un ID de job.
6. Présentez les rapports retournés avec les citations et les URLs source intactes.
7. Arrêtez les jobs échoués et affichez l'erreur retournée ; ne réessayez pas automatiquement.
8. Après la présentation d'un rapport, prenez en charge les suivis : répondez aux questions à ce sujet (ask) ou exécutez une passe de recherche affinée (redo) avec les mêmes commandes.

Étape 1 - Résoudre le backend

Utilisez AIQ_SERVER_URL s'il est défini. Sinon, essayez le backend local par défaut :

python3 $SKILL_DIR/scripts/aiq.py health

Sortie attendue : JSON depuis un endpoint de santé AIQ accessible.

Si health échoue et qu'aucun AIQ_SERVER_URL explicite n'a été défini, demandez :

Je ne vois pas de backend AIQ local accessible. Avez-vous déjà une URL de backend AIQ que vous souhaitez utiliser, ou dois-je déployer un backend local de Skill ?

• Si l'utilisateur fournit une URL, définissez AIQ_SERVER_URL pour les appels d'aide suivants et réexécutez health.
• Si l'utilisateur souhaite un déploiement local, renvoyez vers aiq-deploy et conservez la demande de recherche initiale.
• Si un backend accessible retourne 401 ou 403, arrêtez et expliquez que ce skill public ne gère pas l'authentification. Demandez à l'utilisateur d'utiliser un skill AIQ authentifié ou de configurer l'authentification pour son environnement.
• Si health réussit mais que /chat ou /v1/jobs/async/agents échoue, signalez que le backend est accessible mais incompatible avec ce flux de recherche public, puis proposez d'exécuter la validation aiq-deploy.

Étape 2 - Envoyer la demande de recherche routée

Avant d'envoyer la requête, indiquez l'endpoint résolu :

Je vais envoyer cette requête à <AIQ_SERVER_URL>. Assurez-vous que cet endpoint est approuvé avant d'envoyer des informations sensibles.

N'envoyez pas d'identifiants, cookies, bearer tokens ou valeurs secrètes dans le texte de la requête.

Exécutez :

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

Sortie attendue :

• Une réponse JSON normale pour les réponses superficielles ou directes.
• Ou un JSON structuré contenant {"status": "deep_research_running", "job_id": "<JOB_ID>"} pour la recherche approfondie asynchrone.

Si la réponse est un JSON normal, présentez le résultat immédiatement. N'imposez pas l'interrogation s'il n'y a pas de job_id.

Étape 3 - Interroger les jobs asynchrone

Si la réponse inclut deep_research_running, extrayez le job_id et interrogez avec le même chemin de script absolu :

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

Sortie attendue : le JSON du rapport final quand le job se termine avec succès.

Utilisez le mécanisme d'exécution non-bloquante ou en arrière-plan du runtime quand disponible. Si la méthode d'exécution choisie nécessite des permissions élevées, demandez d'abord l'approbation explicite de l'utilisateur et expliquez pourquoi. Dites à l'utilisateur que la recherche approfondie s'exécute en arrière-plan.

Étape 4 - Reprendre après les interruptions

Si l'interrogation est interrompue, le job continue côté serveur. Reprenez avec :

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>

Utilisez status pour inspecter l'état du job et les artefacts sauvegardés. Utilisez report quand le job s'est déjà terminé et que vous avez seulement besoin du résultat final. Utilisez research_poll pour continuer à attendre la fin.

Le rapport final peut référencer des artefacts générés (graphiques, CSV) en tant que liens artifact://<id>. Pour les matérialiser sous forme de fichiers locaux, exécutez python3 $SKILL_DIR/scripts/aiq.py artifacts <JOB_ID> --download-dir ./aiq-artifacts ; cela télécharge chaque artefact et affiche le chemin local. N'attendez pas de données d'image en base64 dans le rapport lui-même.

Pour un rapport autonome et partageable, exécutez python3 $SKILL_DIR/scripts/aiq.py report <JOB_ID> --out-dir ./my-report. Cela écrit report.md plus un dossier artifacts/ et réécrit chaque lien artifact://<id> sur le fichier local correspondant, afin que le rapport s'affiche (graphiques et tout) dans n'importe quel lecteur markdown sans un backend en cours d'exécution.

Étape 5 - Présenter le rapport

Quand research_poll se termine avec succès, récupérez et présentez le rapport complet. Conservez les citations et les URLs source intactes. Si l'état du job est failed, failure ou cancelled, affichez l'erreur de la réponse d'état et demandez si l'utilisateur souhaite réessayer avec une requête plus étroite ou une approche différente.

Étape 6 - Suivi : poser des questions ou refaire un rapport

Après la présentation d'un rapport, l'utilisateur souhaite souvent approfondir ou ajuster la portée. Réutilisez le flux de backend existant — la même limite d'authentification, l'interrogation et la récupération de rapport des étapes 1-5 s'appliquent ; il n'y a pas d'endpoint de suivi distinct.

Ask — une question de suivi sur un rapport en main :

• Pour une question répondable à partir du rapport que vous avez déjà, répondez directement à partir de son contenu et de ses citations ; n'appelez pas le backend à nouveau.

• Pour une question qui nécessite une nouvelle investigation, envoyez une nouvelle requête qui porte le contexte nécessaire de la question et du rapport précédents dans le nouveau texte de requête, puis présentez le nouveau résultat :

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

  Si cela retourne un ID de job deep_research_running, interrogez-le avec research_poll exactement comme à l'étape 3.

Redo — réexécutez la recherche avec une portée ajustée (une requête plus étroite, une question corrigée, ou une profondeur différente) :

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

• Choisissez agent_type pour correspondre à la profondeur souhaitée (par exemple un deep agent pour une passe approfondie, ou shallow_researcher pour une passe rapide) ; listez les options avec agents en cas de doute.
• Traitez un redo comme un nouveau job : indiquez à nouveau l'endpoint cible avant l'envoi (étape 2), puis interrogez et présentez comme aux étapes 3-5.

N'envoyez pas d'identifiants ou de valeurs secrètes dans le texte de la requête de suivi, et conservez les citations et les URLs source intactes dans chaque réponse de suivi.

Compatibilité des versions

IMPORTANT : Ce skill est conçu pour NVIDIA AI-Q Blueprint version 2.1.0.

Règles de compatibilité du versioning sémantique :

Version du skill : X.Y.Z
Version du Blueprint ou de l'endpoint : A.B.C

Compatible SI :
1. A == X (Les versions majeures DOIVENT correspondre)
2. B >= Y (La version mineure doit être égale ou supérieure)
3. C peut être n'importe quoi (La version patch n'affecte pas la compatibilité)

Exemples :

• La version du skill 2.1.0 est compatible avec la version du Blueprint 2.1.0.
• La version du skill 2.1.0 est compatible avec la version du Blueprint 2.2.0.
• La version du skill 2.1.0 est compatible avec la version du Blueprint 2.1.5.
• La version du skill 2.1.0 n'est pas compatible avec la version du Blueprint 3.0.0.
• La version du skill 2.1.0 n'est pas compatible avec la version du Blueprint 2.0.0.

Si votre version du Blueprint n'est pas compatible :

1. Recherchez une version mise à jour du skill correspondant à votre version du Blueprint.
2. Utilisez une version du Blueprint compatible avec ce skill.
3. Procédez avec prudence seulement si l'utilisateur accepte le risque de compatibilité ; les routes API ou les formes de réponse peuvent avoir changé.

Scripts disponibles

Quand l'hôte prend en charge un aide run_script(), appelez-le avec scripts/aiq.py et les arguments ci-dessus. Sinon, exécutez la commande shell équivalente, comme python3 $SKILL_DIR/scripts/aiq.py health.

Variables d'environnement

Bonnes pratiques de sécurité

• Ne mettez pas les clés API, bearer tokens, cookies ou identifiants basic-auth dans AIQ_SERVER_URL.
• Stockez les identifiants du backend dans l'environnement de déploiement AIQ, pas dans ce skill ou les exemples de commande.
• Le texte de la requête utilisateur est transmis à l'AIQ_SERVER_URL configurée. Confirmez que l'endpoint est approuvé avant d'envoyer des informations sensibles ou confidentielles.
• Traitez les rapports retournés comme potentiellement sensibles si le backend utilise des sources de données privées.
• Ne tronquez pas les citations ou les URLs source des rapports retournés.

Limitations

• Ce skill nécessite un backend AIQ s'exécutant ; il n'en déploie pas un.
• L'aide public ne gère pas les tokens d'authentification ou les cookies.
• Les endpoints AIQ_SERVER_URL distants peuvent journaliser les prompts, les réponses et les métadonnées.
• Si le backend retourne HTTP 500 ou manque d'agents asynchrone, signalez l'échec au lieu de fabriquer une réponse de recherche.

Exemples

Exemple 1 : Exécuter une requête de chat routée ou de recherche

python3 $SKILL_DIR/scripts/aiq.py health
python3 $SKILL_DIR/scripts/aiq.py chat "Comparer la recherche approfondie AIQ locale avec un flux de recherche web standard"

Sortie attendue :

<JSON de santé d'AIQ>
<réponse JSON de chat ou {"status": "deep_research_running", "job_id": "<JOB_ID>"}>

Si AIQ retourne un ID de job, continuez avec research_poll.

Exemple 2 : Reprendre un job existant

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

Remplacez <JOB_ID> par l'UUID retourné par AIQ. Sortie attendue : JSON d'état suivi du JSON du rapport quand le job se termine. Si le job a échoué, affichez l'état retourné et ne réessayez pas automatiquement.

Exemple 3 : Poser un suivi ou refaire avec une requête affinée

# Ask : un suivi qui nécessite une nouvelle investigation, portant le contexte précédent.
python3 $SKILL_DIR/scripts/aiq.py chat "Comment cela se compare-t-il en coût ? (context: recherche approfondie AIQ locale vs recherche web)"

# Redo : réexécuter la recherche avec une requête plus étroite et une profondeur explicite.
python3 $SKILL_DIR/scripts/aiq.py research "Coût de la recherche approfondie AIQ sur une seule station de travail" shallow_researcher

Sortie attendue : une réponse de chat routée ou un nouvel ID de job deep_research_running à interroger avec research_poll. Présentez la réponse de suivi avec les citations et les URLs source intactes.

Références

Problèmes courants

Problème : Aucun backend n'est accessible

Symptômes :

• health échoue avec connexion refusée.
• L'URL http://localhost:8000 par défaut ne répond pas.

Causes :

• AIQ ne s'exécute pas.
• AIQ s'exécute sur un hôte ou un port différent.
• Un pare-feu local ou un paramètre réseau bloque la connexion.

Solutions :

1. Demandez si l'utilisateur dispose d'une URL de backend AIQ existante.
2. S'il en fournit une, définissez-la et réexécutez health :

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

3. S'il souhaite un backend local, renvoyez vers aiq-deploy et conservez la demande de recherche initiale.

Problème : Le backend nécessite une authentification

Symptômes :

• Les requêtes échouent avec HTTP 401 ou HTTP 403.
• Le backend est accessible mais rejette les appels /chat ou job asynchrone.

Causes :

• Le backend a été déployé avec l'authentification activée.
• L'aide public n'attache pas les tokens ou cookies utilisateur.

Solutions :

1. Arrêtez et expliquez que ce skill public ne gère pas l'authentification.
2. Demandez à l'utilisateur d'utiliser un skill AIQ authentifié ou de configurer son backend pour ce flux public local.
3. Réexécutez health et la requête initiale seulement après que la limite d'authentification soit résolue.

Problème : Health réussit mais les routes de recherche échouent

Symptômes :

• health retourne avec succès.
• /chat, /v1/jobs/async/agents ou les commandes d'interrogation échouent.

Causes :

• Le backend n'utilise pas une config AIQ activée pour l'API.
• Le registre de jobs asynchrone n'est pas disponible dans le backend sélectionné.
• La version du backend est incompatible avec ce skill.

Solutions :

1. Exécutez :

   python3 $SKILL_DIR/scripts/aiq.py agents

2. Si les agents ne sont pas disponibles, signalez l'échec de compatibilité et proposez d'exécuter la validation aiq-deploy.
3. Confirmez que la version du Blueprint déployée est compatible avec la version du skill 2.1.0.

Problème : Le job est interrompu ou semble bloqué

Symptômes :

• L'interrogation locale est interrompue.
• Le job continue d'afficher running.
• La sortie de l'interrogation affiche running, mais un rapport est retourné ou l'annulation dit que le job est déjà success.

Causes :

• La recherche approfondie est asynchrone et continue côté serveur.
• La sortie de l'interrogation locale peut être en retard par rapport à l'état du serveur terminal.

Solutions :

1. Vérifiez l'état actuel :

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

2. Si has_report: true ou job_status.status: success, récupérez le rapport :

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

3. Si le job s'exécute toujours, continuez l'interrogation :

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