Skills (outils)

Un skill est une capacité auto-contenue que le LLM peut invoquer. Le framework de skills auto-dérive l'enregistrement de l'outil LLM, l'API HTTP, le formulaire UI, le gate de permission et le log d'audit depuis une seule struct de métadonnées — ajouter un nouveau skill signifie écrire un fichier et appeler Register dans init().

Les skills sont L2 (device-direct) quand ils tournent sur un agent edge, L3 (intelligence) quand ils tournent sur le manager. Les deux sont de première classe.

Anatomie

Chaque skill livre :

// internal/skill/types.go:99
type Metadata struct {
    Key          string   // lower_snake — id in dedupe keys, audit logs, LLM tool names
    Name         string   // human label
    Description  string   // shown to humans AND to the LLM
    Class        Class    // safe | mutating | dangerous
    Scope        Scope    // host (default) | manager
    Category     string   // free-form group label
    Params       ParamSchema
    ResultPreview string
}

Plus un Executor :

type Executor interface {
    Metadata() Metadata
    Execute(ctx context.Context, params json.RawMessage) (json.RawMessage, error)
}

Le framework dispatche en fonction de Scope :

• ScopeHost — le manager enveloppe l'appel dans un RPC de tunnel (Caller.Call(ctx, edgeID, "execute_skill", body)), le handler execute_skill unique de l'agent edge dispatche par clé. Le wrapper d'outil LLM injecte une propriété edge_id entier requise dans le schéma.
• ScopeManager — tourne in-process. Pas d'edge_id ; utile pour les appels d'internet public (web_search), les APIs externes, les skill packs en sous-processus.

Classes de permission

Intégrées dans les métadonnées pour que le gate tourne à chaque invocation, pas comme un bolt-on :

Class	Exemples	Qui peut invoquer
safe	probe_*, read_file, tail_file, query_promql	LLM, tout rôle
mutating	restart_service, kill_process	Nécessite approbation human-in-the-loop (parquée, mais le gate existe)
dangerous	rm, reboot, drop_table	Nécessite SOP signé RSA + double approbation (parquée)

La classe par défaut est safe — mais le framework logge un warning au moment de l'enregistrement quand un auteur oublie de poser le champ, donc ça ne peut pas glisser silencieusement. Voir types.go:205.

Le skill_bridge.go dans le registre des outils aiops n'expose actuellement que les skills ClassSafe au LLM — voir skill_bridge.go. Les classes mutating et dangerous attendent le workflow d'approbation PR-G4.

Les trois populations de skills

Builtins Go (edge)

Écrits à la main dans internal/skill/builtin/ :

Clé	Quoi
probe_http, probe_dns, probe_tcp	Joignabilité réseau lecture seule
tail_file, read_journal	Surface de logs
host_netns_inspect	Inventaire de namespace réseau
web_search	Côté manager ; SearXNG par défaut, configurable
restart_service	Mutant ; gaté

Chacun est un fichier Go avec init() appelant skill.Register. Le binaire edge livre chaque builtin cuit dedans — pas d'installation de plugin, pas de surface d'exécution de code distant.

Skill packs en sous-processus

Pour les capacités que vous voulez déposer sans rebuilder l'agent edge, livrez un répertoire avec un manifeste skill.json et un exécutable. Le loader dans internal/skill/subprocess.go lit le manifeste, enregistre le skill, dispatche Execute au binaire avec les params en stdin.

Utilisés pour : outils de recherche réseau (ovs-vsctl, nft, bpftool, ethtool, ip netns), helpers d'inspect Kubernetes — tout ce où le binaire existe déjà et où shell out bat la réécriture en Go.

BaseTools côté manager

La plus grosse population. Vivent sous internal/manager/biz/aiops/tools/ comme fichiers *_basetool.go. Chacun porte son propre JSON Schema écrit à la main (nécessaire pour les formes que le ParamSchema déclaratif ne peut pas exprimer : arrays, objets imbriqués, oneOf).

BaseTools sélectionnés :

Outil	Ce que ça fait
bash	Shell sur un edge cible (gaté ; enregistré)
query_promql, query_logql, query_traceql	Les trois backends d'observabilité
query_incidents, get_incident_detail, query_alert_rules	Surface d'alerting
query_edges, query_change_events	Inventaire + audit
correlate_incident	Fan-out composite vers prom + log + trace
expand_topology, find_topology_node, get_topology	Graphe
query_knowledge	RAG
find_outlier_edges, rank_edges	Comparaison multi-host
host_load, host_processes, host_files	Outils batch d'état host
get_edge_summary	Snapshot one-shot de santé edge
restart_service	Wrapper côté manager autour du skill restart edge
send_message	Comms coordinator → agent specialist
task_stop, agent_tool	Cycle de vie de worker

Environ 30+ au total. La liste complète est ce qui est enregistré dans BuildBaseTools dans cmd/ongrid/main.go.

L'inventory bridge

Deux registres parallèles existaient avant le bridge :

• Le registre de skills — builtins Go ScopeHost + skill packs subprocess. Présent sur la page /skills de la SPA avec audit + gate de classe.
• Le sac de BaseTools — outils côté manager écrits à la main. Présent au LLM mais PAS à /skills.

Les opérateurs ne pouvaient pas voir quelles capacités côté cloud l'agent avait réellement sans lire les sources. L'inventory_bridge.go parcourt le sac de BaseTools et enregistre chaque outil comme skill avec Scope=ScopeManager. L'interface opt-in RawSchemaProvider sert à préserver le JSON Schema écrit à la main de chaque BaseTool verbatim.

Selon le mémo du 2026-05-08, 18 BaseTools sont pontés via ce chemin — la page /skills liste maintenant chaque capacité côté cloud avec un chip de scope indiquant edge vs manager.

Le bridge inverse est aussi câblé : skill_bridge.go prend chaque skill safe et l'enregistre comme outil présenté au LLM, pour que le LLM voie les skills comme des outils de function-calling avec un paramètre edge_id auto-préfixé pour ceux en ScopeHost.

Audit

Chaque invocation d'outil écrit une ligne dans chat_tool_calls :

• session_id — la session chatruntime qui a appelé.
• tool_name, args_json, result_json, error.
• device_id — quand l'outil ciblait un host spécifique (le champ EdgeID sur ExecuteResult).
• started_at, finished_at, duration_ms.
• caller_user_id + caller_role — pour les appels originant du LLM, le framework utilise UserID=0 / Role="system".

Le log d'audit HLD-010 prend appui sur la même table ; la page admin /admin/audit la rend avec timeline + filtres par outil.

Voir aussi

• WebShell — le skill bash exprimé comme terminal interactif plutôt que comme appel d'outil one-shot.
• Base de connaissances — plongée profonde dans query_knowledge.
• Topologie — expand_topology / find_topology_node.
• Manifeste de skill — format wire pour les skill packs en sous-processus.