From 37e881bc39faf3a3c32299bcf3acbbe2f0f1c4d1 Mon Sep 17 00:00:00 2001 From: sylvain Date: Sun, 8 Mar 2026 15:45:08 +0000 Subject: [PATCH] =?UTF-8?q?README=20:=20documentation=20compl=C3=A8te=20de?= =?UTF-8?q?=20toutes=20les=20commandes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 250 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 196 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index bcdf2b7..c562ee8 100644 --- a/README.md +++ b/README.md @@ -2,38 +2,210 @@ Agent principal du réseau. Il reçoit les instructions de l'utilisateur (via XMPP ou CLI MQTT), les analyse avec un LLM, et délègue les tâches aux agents spécialisés. -## Rôle +--- -- Point d'entrée unique pour l'utilisateur (`sylvain@xmpp.ovh`) -- Délègue aux agents spécialisés via MQTT (`DELEGATE: | `) -- Planifie des tâches récurrentes (`SCHEDULE:`) -- Centralise les rapports et erreurs des agents -- Maintient un registre des agents disponibles +## Commandes XMPP (sylvain@xmpp.ovh → agent1) -## Skills disponibles +### Contrôle des agents -| Trigger | Description | +| Commande | Effet | |---|---| -| `SEARCH: ` | Recherche DuckDuckGo | -| `READ: ` | Lecture de page web | -| `REMEMBER: \| ` | Mémoire SQLite | -| `RECALL: ` | Récupération mémoire | -| `MQTT_PUBLISH: \| ` | Publication MQTT | -| `DELEGATE: \| ` | Délégation à un agent spécialisé | -| `PLAN: \| ;; \|` | Plan multi-étapes | -| `SCHEDULE: \| \| ` | Planification | -| `PLAN_LIST:` | Lister les tâches planifiées | -| `PLAN_CANCEL: ` | Annuler une planification | -| `REPORT:` | Rapport d'exécutions | -| `REPORT_ERRORS:` | Rapport des erreurs | +| `!agentsOFF` | Agent1 en veille + pause de tous les agents | +| `!agentsON` | Agent1 actif + reprise de tous les agents | +| `!agentOFF ` | Pause d'un agent spécifique (ex: `!agentOFF agent2_debian13`) | +| `!agentON ` | Reprise d'un agent spécifique | +| `!agentOFF agent1` | Agent1 en veille uniquement (les autres agents continuent) | +| `!agentON agent1` | Agent1 sort de veille | + +> En mode veille, agent1 reste connecté XMPP et répond uniquement aux commandes `!agentON`. + +### Affichage des configurations + +| Commande | Effet | +|---|---| +| `!reports` | Afficher `reports_schedule.json` (horaires des rapports) | +| `!tasks` | Afficher `tasks_schedule.json` (tâches planifiées) | +| `!blackout` | Afficher `blackout_hours.json` (plages d'inactivité) | + +### Divers + +| Commande | Effet | +|---|---| +| `!reset` | Réinitialiser l'historique de conversation | + +--- + +## Skills LLM (utilisables en XMPP ou CLI) + +Ces commandes sont générées par le LLM en réponse à une instruction en langage naturel. + +### Délégation et planification + +| Trigger | Syntaxe | Description | +|---|---|---| +| `DELEGATE:` | `DELEGATE: \| ` | Délègue une tâche à un agent (avec vérif. plage horaire + blackout) | +| `PLAN:` | `PLAN: \| ;; \|` | Exécute plusieurs tâches en séquence | +| `SCHEDULE:` | `SCHEDULE: \| \| ` | Planifie une tâche récurrente | +| `PLAN_LIST:` | `PLAN_LIST:` | Lister les tâches planifiées | +| `PLAN_CANCEL:` | `PLAN_CANCEL: ` | Annuler une planification | + +**Expressions cron supportées :** +``` +daily 03:00 → tous les jours à 03h00 +every 6h → toutes les 6 heures +every 30min → toutes les 30 minutes +weekly lun 08:00 → chaque lundi à 08h00 +``` + +### Rapports + +| Trigger | Syntaxe | Description | +|---|---|---| +| `REPORT:` | `REPORT: [agent]` | Rapport des 20 dernières exécutions | +| `REPORT_ERRORS:` | `REPORT_ERRORS: [agent]` | Rapport des 20 dernières erreurs | +| `DAILY_REPORT:` | `DAILY_REPORT: [agent]` | Rapport journalier compilé (stats de tous les agents) | + +### Mémoire et recherche + +| Trigger | Syntaxe | Description | +|---|---|---| +| `SEARCH:` | `SEARCH: ` | Recherche DuckDuckGo | +| `READ:` | `READ: ` | Lecture de page web | +| `REMEMBER:` | `REMEMBER: \| ` | Mémoriser une information (SQLite) | +| `RECALL:` | `RECALL: ` | Récupérer une information mémorisée | + +### MQTT direct + +| Trigger | Syntaxe | Description | +|---|---|---| +| `MQTT_PUBLISH:` | `MQTT_PUBLISH: \| ` | Publier un message MQTT | +| `MQTT_SUBSCRIBE:` | `MQTT_SUBSCRIBE: ` | Écouter un topic MQTT | + +--- + +## CLI (`cli.py`) + +```bash +python3 /opt/agent/cli.py # parler à agent1 +python3 /opt/agent/cli.py agent2_debian13 # accès direct à un agent +python3 /opt/agent/cli.py --plans # voir les planifications +``` + +**Commandes dans la CLI :** + +| Commande | Effet | +|---|---| +| `/reset` | Réinitialiser la conversation | +| `/plans` | Lister les tâches planifiées | +| `/report` | Rapport des dernières exécutions | +| `/errors` | Rapport des erreurs | +| `/agent ` | Basculer vers un autre agent | +| `/quit` | Quitter la CLI | + +--- + +## Fichiers de configuration + +| Fichier | Rôle | Modifié par | +|---|---|---| +| `config/config.json` | Paramètres XMPP, MQTT, Ollama | Utilisateur | +| `config/agents_registry.json` | Registre des agents (auto-mis à jour) | Agent1 au démarrage des agents | +| `config/blackout_hours.json` | Plages horaires d'inactivité totale | **Utilisateur directement** | +| `config/reports_schedule.json` | Horaires de sollicitation des rapports | Agent1 (avec confirmation) | +| `config/tasks_schedule.json` | Tâches planifiées par agent | Agent1 (avec confirmation) | + +### `blackout_hours.json` +Aucun agent ne travaille pendant ces plages, quelle que soit la planification : +```json +[ + { "start": "02:00", "end": "05:00", "label": "maintenance nuit", "enabled": true } +] +``` + +### `reports_schedule.json` +```json +{ + "agents": { + "agent2_debian13": { "report_time": "22:00", "enabled": true }, + "agent2_ansible": { "report_time": "22:05", "enabled": true }, + "agent2_deploy": { "report_time": "22:10", "enabled": true } + }, + "daily_report_time": "22:30", + "daily_report_enabled": true +} +``` + +### `tasks_schedule.json` +```json +{ + "tasks": [ + { + "agent": "agent2_debian13", + "task": "apt update && apt upgrade -y", + "cron": "weekly lun 03:00", + "enabled": true + } + ] +} +``` + +### `agents_registry.json` — champ `work_hours` +Plage horaire de travail par agent (vérifiée avant chaque DELEGATE) : +```json +"work_hours": { + "start": "07:00", + "end": "23:00", + "days": ["mon","tue","wed","thu","fri","sat","sun"], + "enabled": true +} +``` + +--- + +## Topics MQTT + +| Topic | Direction | Rôle | +|---|---|---| +| `agents/agent1/inbox` | CLI / agents → agent1 | Tâches pour agent1 | +| `agents//inbox` | Agent1 → agent2_* | Tâches pour les agents | +| `agents//control` | Agent1 → agent2_* | Pause / Resume / Report | +| `agents/daily_report` | Agent2_* → agent1 | Rapports journaliers | +| `agents/errors` | Agent2_* → agent1 | Erreurs (notif XMPP) | +| `agents/register` | Agent2_* → agent1 | Enregistrement au démarrage | +| `agents/status/` | Agent2_* → agent1 | Statut en ligne / hors ligne (LWT) | +| `agents/cli/outbox` | Agent1 → CLI | Réponses vers la CLI | +| `agents/scheduler/notifications` | Scheduler → agent1 | Notifications planificateur | + +--- + +## Lancer les agents + +```bash +# Agent1 +python3 /opt/agent/agent1.py > /tmp/agent1.log 2>&1 & + +# Agents spécialisés +python3 /opt/agent2_debian13/agent2_debian13.py > /tmp/agent2_debian13.log 2>&1 & +python3 /opt/agent2_ansible/agent2_ansible.py > /tmp/agent2_ansible.log 2>&1 & +python3 /opt/agent2_deploy/agent2_deploy.py > /tmp/agent2_deploy.log 2>&1 & + +# Via systemd +systemctl start agent agent2_debian13 agent2_ansible agent2_deploy +``` + +## Logs + +```bash +journalctl -u agent -f +journalctl -u agent2_debian13 -f +``` + +--- ## Déploiement manuel ```bash -# Prérequis apt-get install -y python3 python3-pip python3-venv git mosquitto - -# Cloner et installer git clone https://git.piaf.im/sylvain/agent1.git /opt/agent cd /opt/agent python3 -m venv venv @@ -44,35 +216,5 @@ cp config/config.json.example config/config.json # adapter les valeurs # Service systemd cp agent.service /etc/systemd/system/ -systemctl daemon-reload -systemctl enable agent -systemctl start agent -``` - -## Configuration (`config/config.json`) - -```json -{ - "ollama_url" : "http://:11434/api/chat", - "model" : "qwen3:8b", - "xmpp_jid" : "agent1@xmpp.ovh", - "xmpp_pass" : "", - "admin_jid" : "sylvain@xmpp.ovh", - "mqtt_host" : "localhost", - "mqtt_port" : 1883 -} -``` - -## CLI - -```bash -python3 /opt/agent/cli.py # parler à agent1 -python3 /opt/agent/cli.py agent2_debian13 # accès direct à un agent -python3 /opt/agent/cli.py --plans # voir les planifications -``` - -## Logs - -```bash -journalctl -u agent -f +systemctl daemon-reload && systemctl enable agent && systemctl start agent ```