From 9f027cb833ceec6b83a8d1ff1a3937152f9cc32b Mon Sep 17 00:00:00 2001 From: alkatrazz Date: Wed, 13 May 2026 16:37:36 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20ask-agent=20+=20skills=20Hermes=20?= =?UTF-8?q?=E2=80=94=20documentation=20compl=C3=A8te?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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//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 --- admin/README.md | 3 +- admin/ask-agent.md | 226 +++++++++++++++++++++++++++++++++++++++++++++ admin/hermes.md | 34 ++++++- admin/litellm.md | 21 +++-- 4 files changed, 275 insertions(+), 9 deletions(-) create mode 100644 admin/ask-agent.md diff --git a/admin/README.md b/admin/README.md index 032678d..5b0645b 100644 --- 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** | | diff --git a/admin/ask-agent.md b/admin/ask-agent.md new file mode 100644 index 0000000..a0d31db --- /dev/null +++ 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 "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 "" +ask-agent "" [--max-tokens N] [--system ""] + +# Exemples +ask-agent system "quelle commande pour lister les ports en écoute ?" +ask-agent monitor "analyse ces logs systemd : " +ask-agent brain "architecture optimale pour ce schéma k8s : " +ask-agent system "calcule la taille totale en Go de ces fichiers : " + +# 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é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//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/ +vim hermes-skills/funk//SKILL.md + +# 2. Déployer dans le répertoire global HERMES_HOME +sudo mkdir -p /srv/data/hermes/skills/funk/ +sudo cp hermes-skills/funk//SKILL.md /srv/data/hermes/skills/funk// + +# 3. Copier dans le profil cible +sudo mkdir -p /srv/data/hermes/profiles/funk-ai/skills/funk/ +sudo cp /srv/data/hermes/skills/funk//SKILL.md \ + /srv/data/hermes/profiles/funk-ai/skills/funk// +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/" +``` + +### 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 | diff --git a/admin/hermes.md b/admin/hermes.md index e9755fd..1f55080 100644 --- 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///SKILL.md` — répertoire global (référence) +> - `$HERMES_HOME/profiles//skills///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 | diff --git a/admin/litellm.md b/admin/litellm.md index f4d6c54..22e89de 100644 --- a/admin/litellm.md +++ b/admin/litellm.md @@ -8,14 +8,16 @@ 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) - ├── claude-sonnet-4-6 → api.anthropic.com (cloud, payant) - └── claude-opus-4-7 → api.anthropic.com (cloud, payant) + ├── 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