Compétence AIQ Research

Objectif

Utilisez cette compétence pour appeler un serveur NVIDIA AI-Q Blueprint s'exécutant localement via le script d'aide scripts/aiq.py.

Utilisez cette compétence pour les demandes de recherche, notamment :

• « deep research on ... »
• « AIQ research ... »
• « research ... »
• « use AI-Q to answer ... »
• « ask AI-Q about ... »

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

Prérequis

Les utilisateurs ont besoin de :

• Python 3.11+ disponible sous le nom python3.
• Un backend NVIDIA AI-Q Blueprint local ou auto-hébergé accessible.
• AIQ_SERVER_URL définie si le backend ne s'exécute pas sur http://localhost:8000.
• Un backend configuré avec l'authentification désactivée pour cet aide public, ou une compétence AI-Q authentifiée distincte pour les environnements authentifiés.
• Un accès réseau de la machine locale vers l'URL du backend AI-Q.
• Les informations d'identification configurées dans l'environnement du backend, et non dans cette compétence. 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. Informez l'utilisateur que la requête sera envoyée au backend AI-Q configuré avant de l'envoyer.
5. Interrogez les tâches de recherche profonde asynchrones quand AI-Q retourne un ID de tâche.
6. Présentez les rapports retournés avec les citations et les URL sources intactes.
7. Arrêtez en cas d'échec de tâche et affichez l'erreur retournée ; ne relancez pas automatiquement.

Étape 1 - Résoudre le backend

Utilisez AIQ_SERVER_URL quand elle est définie. Sinon, essayez le backend local par défaut :

python3 $SKILL_DIR/scripts/aiq.py health

Sortie attendue : JSON d'un endpoint health AI-Q accessible.

Si health échoue et qu'aucune AIQ_SERVER_URL explicite n'a été définie, posez la question :

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?

• 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 d'origine.
• Si un backend accessible retourne 401 ou 403, arrêtez et expliquez que cette compétence publique ne gère pas l'authentification. Demandez à l'utilisateur d'utiliser une compétence AI-Q authentifiée ou de configurer l'authentification pour son environnement.
• Si health réussit mais /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 demande, indiquez l'endpoint résolu :

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

N'envoyez pas les informations d'identification, les cookies, les bearer tokens ou les valeurs secrètes via 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 JSON structuré contenant {"status": "deep_research_running", "job_id": "<JOB_ID>"} pour la recherche profonde asynchrone.

Si la réponse est un JSON normal, présentez le résultat immédiatement. Ne forcez pas l'interrogation en l'absence de job_id.

Étape 3 - Interroger les tâches asynchrones

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 à la fin de la tâche.

Utilisez le mécanisme d'exécution non-bloquant 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. Informez l'utilisateur que la recherche profonde s'exécute en arrière-plan.

Étape 4 - Reprendre après une interruption

Si l'interrogation est interrompue, la tâche 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 examiner l'état de la tâche et les artefacts sauvegardés. Utilisez report quand la tâche est déjà terminée et que vous avez besoin uniquement de la sortie finale. Utilisez research_poll pour continuer à attendre l'achèvement.

Étape 5 - Présenter le rapport

Quand research_poll se termine correctement, récupérez et présentez le rapport complet. Gardez les citations et les URL sources intactes. Si l'état de la tâche est failed, failure ou cancelled, affichez l'erreur de la réponse d'état et demandez si l'utilisateur souhaite relancer avec une requête plus étroite ou une approche différente.

Compatibilité de version

IMPORTANT : Cette compétence est conçue pour NVIDIA AI-Q Blueprint version 2.1.0.

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

Version de la compétence : X.Y.Z
Version Blueprint ou 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 de compétence 2.1.0 est compatible avec la version Blueprint 2.1.0.
• La version de compétence 2.1.0 est compatible avec la version Blueprint 2.2.0.
• La version de compétence 2.1.0 est compatible avec la version Blueprint 2.1.5.
• La version de compétence 2.1.0 n'est pas compatible avec la version Blueprint 3.0.0.
• La version de compétence 2.1.0 n'est pas compatible avec la version Blueprint 2.0.0.

Si votre version Blueprint n'est pas compatible :

1. Vérifiez la présence d'une version de compétence à jour correspondant à votre version Blueprint.
2. Utilisez une version Blueprint compatible avec cette compétence.
3. Procédez avec prudence uniquement 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 supporte 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

Meilleures pratiques de sécurité

• Ne mettez pas les clés API, les bearer tokens, les cookies ou les informations d'identification basic-auth dans AIQ_SERVER_URL.
• Stockez les informations d'identification du backend dans l'environnement de déploiement AI-Q, et non dans cette compétence ou les exemples de commande.
• Le texte de la requête utilisateur est transmis vers AIQ_SERVER_URL configurée. Confirmez que l'endpoint est digne de confiance 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 URL sources des rapports retournés.

Limitations

• Cette compétence nécessite un backend AI-Q en cours d'exécution ; elle 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 ne dispose pas d'agents asynchrones, signalez l'échec au lieu de fabriquer une réponse de recherche.

Exemples

Exemple 1 : Exécuter une demande de chat ou de recherche routée

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"

Sortie attendue :

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

Si AI-Q retourne un ID de tâche, continuez avec research_poll.

Exemple 2 : Reprendre une tâche existante

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 AI-Q. Sortie attendue : JSON d'état suivi du JSON du rapport à la fin de la tâche. Si la tâche a échoué, affichez l'état retourné et ne relancez pas automatiquement.

Références

Problèmes courants

Problème : Aucun backend n'est accessible

Symptômes :

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

Causes :

• AI-Q n'est pas en cours d'exécution.
• AI-Q 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 AI-Q 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 d'origine.

Problème : Le backend nécessite une authentification

Symptômes :

• Les demandes échouent avec HTTP 401 ou HTTP 403.
• Le backend est accessible mais rejette /chat ou les appels de tâche asynchrone.

Causes :

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

Solutions :

1. Arrêtez et expliquez que cette compétence publique ne gère pas l'authentification.
2. Demandez à l'utilisateur d'utiliser une compétence AI-Q authentifiée ou de configurer son backend pour ce flux local public.
3. Réexécutez health et la requête d'origine uniquement après la résolution de la frontière d'authentification.

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

Symptômes :

• health retourne correctement.
• /chat, /v1/jobs/async/agents ou les commandes d'interrogation échouent.

Causes :

• Le backend n'utilise pas une config AI-Q compatible avec l'API.
• Le registre de tâches asynchrones n'est pas disponible dans le backend sélectionné.
• La version du backend est incompatible avec cette compétence.

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 Blueprint déployée est compatible avec la version de compétence 2.1.0.

Problème : La tâche est interrompue ou semble bloquée

Symptômes :

• L'interrogation locale est interrompue.
• La tâche continue à afficher running.
• La sortie d'interrogation montre running, mais un rapport est retourné ou l'annulation indique que la tâche est déjà success.

Causes :

• La recherche profonde est asynchrone et continue côté serveur.
• La sortie d'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 la tâche est toujours en cours d'exécution, continuez l'interrogation :

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