docs: ask-agent + skills Hermes — documentation complète

- admin/ask-agent.md (nouveau) : doc détaillée ask-agent CLI, architecture 4 agents, skill agent-delegation, gestion skills dans les profils Hermes, dépannage, points d'attention - admin/hermes.md : section Skills avec point d'attention double emplacement (skills/ + profiles/<profil>/skills/), tableau skills custom Funk, restart obligatoire après modif skill - admin/litellm.md : flux et modèles mis à jour (qwen3-8b, qwen3-1.7b-system/monitor), lien vers ask-agent.md - admin/README.md : entrée ask-agent.md ajoutée Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-07-08 14:24:42 +02:00 · 2026-05-13 16:37:36 +02:00 · 2026-05-13 16:37:36 +02:00 · 9f027cb833
commit 9f027cb833
parent 515933c949
4 changed files with 275 additions and 9 deletions
--- a/admin/README.md
+++ b/admin/README.md
@ -22,7 +22,8 @@
 | [nfs.md](nfs.md) | NFS + RAID5 — exports, montages, automount, ajout de partages |
 | [systeme.md](systeme.md) | Services, logs, ressources, NetworkManager, dnf |
 | [litellm.md](litellm.md) | LiteLLM Proxy — routage Qwen local + Claude API, config, validation |
-| [hermes.md](hermes.md) | Hermes Agent — service, config, modèle, API, debug |
+| [hermes.md](hermes.md) | Hermes Agent — service, profils, skills, config, debug |
+| [ask-agent.md](ask-agent.md) | Délégation inter-agents — ask-agent CLI + skill agent-delegation |
 | [talos.md](talos.md) | Talos Linux — administration quotidienne du cluster k8s |
 | [incidents.md](incidents.md) | Incidents passés — causes, résolutions, fixes permanents |
 | **Gestion cluster** | |
--- a/admin/ask-agent.md
+++ b/admin/ask-agent.md
@ -0,0 +1,226 @@
+# Délégation inter-agents — ask-agent + skill agent-delegation
+
+Le cluster Funk dispose de 4 agents spécialisés accessibles via la commande `ask-agent`.
+Le skill `funk/agent-delegation` enseigne à Hermes (profil `funk-ai`) comment et quand
+les utiliser pour décomposer des tâches.
+
+---
+
+## Architecture
+
+```
+funk-ai (Qwen3-8B GPU — profil principal)
+    │
+    │  Terminal: ask-agent <agent> "question"
+    ▼
+ask-agent  (/usr/local/bin/ask-agent)
+    │  POST http://127.0.0.1:4000/v1/chat/completions
+    ▼
+LiteLLM Proxy (:4000)
+    ├── ask-agent system  →  qwen3-1.7b-system  (CPU :1236)
+    ├── ask-agent monitor →  qwen3-1.7b-monitor (CPU :1237)
+    ├── ask-agent brain   →  claude-sonnet-4-6  (API Anthropic)
+    └── ask-agent funk-ai →  qwen3-8b           (GPU :1234)
+```
+
+---
+
+## Agents disponibles
+
+| Agent | Modèle | Vitesse | Coût | Usage idéal |
+|---|---|---|---|---|
+| `system` | Qwen3-1.7B CPU (:1236) | ~21 tok/s | Gratuit | Calculs, formatage, parsing, résumés courts |
+| `monitor` | Qwen3-1.7B CPU (:1237) | ~21 tok/s | Gratuit | Analyse métriques, logs, santé système |
+| `brain` | Claude Sonnet 4.6 (API) | Variable | Payant | Raisonnement complexe, architecture, revue |
+| `funk-ai` | Qwen3-8B GPU (:1234) | ~35 tok/s | Gratuit | Tâches générales (agent principal lui-même) |
+
+---
+
+## Commande ask-agent
+
+```bash
+# Syntaxe
+ask-agent <agent> "<question>"
+ask-agent <agent> "<question>" [--max-tokens N] [--system "<prompt système>"]
+
+# Exemples
+ask-agent system "quelle commande pour lister les ports en écoute ?"
+ask-agent monitor "analyse ces logs systemd : <coller logs>"
+ask-agent brain "architecture optimale pour ce schéma k8s : <contexte>"
+ask-agent system "calcule la taille totale en Go de ces fichiers : <ls -lh output>"
+
+# Avec prompt système personnalisé
+ask-agent monitor "est-ce que ces métriques sont normales ?" \
+  --system "Tu es expert Linux AlmaLinux, réponds en 1 phrase max."
+
+# Max tokens (défaut : 1000)
+ask-agent brain "revois ce manifest k8s" --max-tokens 3000
+```
+
+---
+
+## Skill Hermes — agent-delegation
+
+Le skill `funk/agent-delegation` est installé dans le profil `funk-ai`.
+Il charge automatiquement le contexte suivant dans chaque session Hermes :
+- La liste des 4 agents et leurs spécialités
+- Le pattern "collecter localement → déléguer"
+- La règle "tu tournes sur storage-01, ne pas SSH vers toi-même"
+
+### Localisation du skill
+
+```
+/srv/data/hermes/skills/funk/agent-delegation/SKILL.md          ← source (Git)
+/srv/data/hermes/profiles/funk-ai/skills/funk/agent-delegation/SKILL.md  ← profil actif
+```
+
+Le fichier source est versionné dans le repo lab :
+```
+hermes-skills/funk/agent-delegation/SKILL.md
+```
+
+### Utilisation depuis Hermes TUI
+
+Hermes utilise `ask-agent` via l'outil Terminal — pas un appel API direct.
+Le skill lui indique d'utiliser exactement :
+
+```
+Terminal: ask-agent system "ta question"
+Terminal: ask-agent monitor "ta question"
+Terminal: ask-agent brain "ta question"
+```
+
+Pattern typique (Hermes collecte en local, délègue l'analyse) :
+
+```
+Terminal: systemctl --state=failed --no-pager
+Terminal: ask-agent monitor "voici les services en erreur : <résultat> — résume les problèmes"
+```
+
+---
+
+## Gestion des skills dans Hermes
+
+### Pourquoi le skill doit être dans le profil
+
+Hermes charge les skills depuis `$HERMES_HOME/profiles/<profil>/skills/`.
+Un skill placé uniquement dans `$HERMES_HOME/skills/` **n'est pas chargé** par le profil.
+
+```bash
+# Vérifier les skills du profil funk-ai
+sudo -u hermes env HERMES_HOME=/srv/data/hermes hermes skills list | grep -i funk
+
+# État attendu :
+# │ agent-delegation │ funk │ local │ local │ enabled │
+```
+
+### Ajouter un skill custom à un profil
+
+```bash
+# 1. Créer le skill dans le repo (versionné)
+mkdir -p hermes-skills/funk/<nom-skill>
+vim hermes-skills/funk/<nom-skill>/SKILL.md
+
+# 2. Déployer dans le répertoire global HERMES_HOME
+sudo mkdir -p /srv/data/hermes/skills/funk/<nom-skill>
+sudo cp hermes-skills/funk/<nom-skill>/SKILL.md /srv/data/hermes/skills/funk/<nom-skill>/
+
+# 3. Copier dans le profil cible
+sudo mkdir -p /srv/data/hermes/profiles/funk-ai/skills/funk/<nom-skill>
+sudo cp /srv/data/hermes/skills/funk/<nom-skill>/SKILL.md \
+        /srv/data/hermes/profiles/funk-ai/skills/funk/<nom-skill>/
+sudo chown -R hermes:hermes /srv/data/hermes/profiles/funk-ai/skills/funk
+
+# 4. Redémarrer le service
+sudo systemctl restart hermes-agent
+
+# 5. Vérifier
+sudo -u hermes env HERMES_HOME=/srv/data/hermes hermes skills list | grep funk
+```
+
+### Mettre à jour un skill existant
+
+```bash
+# Modifier le source dans le repo
+vim hermes-skills/funk/agent-delegation/SKILL.md
+
+# Synchroniser vers les deux emplacements
+sudo cp hermes-skills/funk/agent-delegation/SKILL.md \
+        /srv/data/hermes/skills/funk/agent-delegation/SKILL.md
+sudo cp hermes-skills/funk/agent-delegation/SKILL.md \
+        /srv/data/hermes/profiles/funk-ai/skills/funk/agent-delegation/SKILL.md
+sudo chown hermes:hermes /srv/data/hermes/profiles/funk-ai/skills/funk/agent-delegation/SKILL.md
+
+sudo systemctl restart hermes-agent
+```
+
+---
+
+## Script ask-agent — référence technique
+
+Déployé sur storage-01 : `/usr/local/bin/ask-agent`
+Source versionnée : `ansible/roles/litellm/files/ask-agent`
+
+```bash
+# Déployer manuellement (si pas via Ansible)
+scp ansible/roles/litellm/files/ask-agent s01:/tmp/
+ssh s01 "sudo cp /tmp/ask-agent /usr/local/bin/ask-agent && sudo chmod +x /usr/local/bin/ask-agent"
+
+# Redéployer via Ansible
+ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags litellm
+```
+
+Paramètres hardcodés dans le script :
+
+| Paramètre | Valeur |
+|---|---|
+| LiteLLM URL | `http://127.0.0.1:4000/v1/chat/completions` |
+| API key | `lm-studio` (= master_key LiteLLM) |
+| Timeout | 120s (curl) |
+| stream | false |
+
+---
+
+## Dépannage
+
+### ask-agent retourne du garbage
+
+Le modèle GGUF est peut-être corrompu (signe d'une erreur disque précédente).
+```bash
+ssh g01 "sudo systemctl status llama-server-system"
+ssh g01 "md5sum /mnt/models/<chemin-vers-gguf>"
+```
+
+### ask-agent timeout
+
+LiteLLM ou llama-server ne répond pas.
+```bash
+ssh s01 "curl -s http://localhost:4000/health -H 'Authorization: Bearer lm-studio'"
+ssh g01 "systemctl status llama-server-system llama-server-monitor"
+```
+
+### Le skill n'est pas chargé dans Hermes
+
+Vérifier la présence dans le profil :
+```bash
+sudo ls /srv/data/hermes/profiles/funk-ai/skills/funk/agent-delegation/
+```
+Si absent → copier depuis `/srv/data/hermes/skills/funk/agent-delegation/` et redémarrer.
+
+### Hermes fait du SSH vers storage-01
+
+Le skill lui dit "tu es déjà sur storage-01" — mais si une ancienne session Hermes est
+ouverte, le skill chargé est l'ancienne version. Fermer la session TUI et en ouvrir une
+nouvelle après chaque modification du skill.
+
+---
+
+## Points d'attention
+
+| Sujet | Détail |
+|---|---|
+| Deux emplacements | Modifier le skill dans le repo ET dans le profil — sinon désynchronisé |
+| Restart obligatoire | `systemctl restart hermes-agent` requis après ajout/modif skill |
+| brain coûteux | Claude Sonnet API — réserver aux analyses que system/monitor ne peuvent pas faire |
+| system et monitor isolés | Tournent sur 14 CPUs dédiés — ne bloquent pas le GPU ni Hermes principal |
+| ask-agent est shell | Dans le skill, toujours écrire `Terminal: ask-agent ...` — pas une API interne |
--- a/admin/hermes.md
+++ b/admin/hermes.md
@ -174,7 +174,37 @@ LM_API_KEY=lm-studio    # valeur exacte obligatoire

 ---

-## Skill Qdrant Vector Search
+## Skills
+
+Les skills sont des fichiers `SKILL.md` chargés en contexte dans chaque session Hermes.
+Ils enseignent à l'agent des patterns, commandes et procédures spécifiques.
+
+> **Point d'attention critique** : un skill doit être présent dans **deux endroits** :
+> - `$HERMES_HOME/skills/<cat>/<nom>/SKILL.md` — répertoire global (référence)
+> - `$HERMES_HOME/profiles/<profil>/skills/<cat>/<nom>/SKILL.md` — chargé par le profil
+>
+> Placer un skill uniquement dans le répertoire global ne suffit pas — le profil ne le charge pas.
+
+```bash
+# Lister les skills actifs du profil courant
+sudo -u hermes env HERMES_HOME=/srv/data/hermes hermes skills list
+
+# Vérifier qu'un skill est bien dans le profil funk-ai
+sudo ls /srv/data/hermes/profiles/funk-ai/skills/funk/
+
+# Redémarrer après ajout/modif d'un skill
+sudo systemctl restart hermes-agent
+```
+
+### Skills custom Funk
+
+| Skill | Catégorie | Usage |
+|---|---|---|
+| `agent-delegation` | `funk` | Déléguer des sous-tâches aux agents system/monitor/brain via `ask-agent` |
+
+Documentation complète : [ask-agent.md](ask-agent.md)
+
+### Skill Qdrant Vector Search

 ```bash
 # Vérifier le skill installé
@ -272,3 +302,5 @@ sudo systemctl restart hermes-dashboard
 | Dashboard | Accessible uniquement depuis `192.168.1.10:9119` (restreint nftables) |
 | TUI | `hermes --tui` nécessite un TTY — utiliser `sudo hermes-tui` en SSH interactif |
 | `/opt/hermes` perms | Répertoire en `711` — traversable par tous mais non listable |
+| **Skills double emplacement** | Tout skill custom doit être dans `skills/` ET dans `profiles/funk-ai/skills/` — voir [ask-agent.md](ask-agent.md) |
+| **Restart après skill** | `systemctl restart hermes-agent` obligatoire après ajout ou modification d'un skill |
--- a/admin/litellm.md
+++ b/admin/litellm.md
@ -8,12 +8,14 @@ Il route les requêtes OpenAI-compatibles vers le bon backend selon le modèle d
 ## Flux

 ```
-Hermes / Open WebUI / n8n
+Hermes / ask-agent / Open WebUI / n8n
        │
        ▼  http://127.0.0.1:4000/v1  (Authorization: Bearer lm-studio)
   LiteLLM Proxy
-        ├── hermes-default        →  qwen2.5-14b-instruct  (défaut Hermes)
-        ├── qwen2.5-14b-instruct  →  llama-server gpu-01 :1234  (local, gratuit)
+        ├── hermes-default       →  qwen3-8b            →  llama-server gpu-01 :1234  (GPU)
+        ├── qwen3-8b             →  llama-server gpu-01 :1234  (GPU, gratuit)
+        ├── qwen3-1.7b-system    →  llama-server gpu-01 :1236  (CPU 14 threads, gratuit)
+        ├── qwen3-1.7b-monitor   →  llama-server gpu-01 :1237  (CPU 14 threads, gratuit)
        ├── claude-sonnet-4-6    →  api.anthropic.com           (cloud, payant)
        └── claude-opus-4-7      →  api.anthropic.com           (cloud, payant)
 ```
@ -36,11 +38,16 @@ sudo journalctl -u litellm -n 50

 | Nom dans l'API | Backend | Coût |
 |---|---|---|
-| `hermes-default` | Alias switchable (Qwen par défaut) | Selon backend actif |
-| `qwen2.5-14b-instruct` | llama-server gpu-01 (ROCm 7.x) | Gratuit |
+| `hermes-default` | qwen3-8b sur gpu-01 :1234 (GPU) | Gratuit |
+| `qwen3-8b` | llama-server gpu-01 :1234 (ROCm 7.x) | Gratuit |
+| `qwen3-1.7b-system` | llama-server gpu-01 :1236 (CPU, 14 threads) | Gratuit |
+| `qwen3-1.7b-monitor` | llama-server gpu-01 :1237 (CPU, 14 threads) | Gratuit |
 | `claude-sonnet-4-6` | Anthropic API | ~$3/$15 par million tokens in/out |
 | `claude-opus-4-7` | Anthropic API | Plus cher, meilleur raisonnement |

+> `qwen3-1.7b-system` et `qwen3-1.7b-monitor` sont utilisés par `ask-agent system` et
+> `ask-agent monitor` — voir [ask-agent.md](ask-agent.md).
+
 ---

 ## Switch rapide avec hermes-switch