Funk-lab/admin/ask-agent.md

# 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 |