mirror of
https://github.com/Alkatrazz24/Funk-lab.git
synced 2026-07-08 18:04:43 +02:00
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>
This commit is contained in:
alkatrazz
parent
515933c949
commit
9f027cb833
4 changed files with 275 additions and 9 deletions
226
admin/ask-agent.md
Normal file
226
admin/ask-agent.md
Normal file
|
|
@ -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 |
|
||||
Loading…
Add table
Add a link
Reference in a new issue