Gabarits d'agents : onglet Agents et registre

Les produits Navin (Navin Enterprise RAG Agent d'abord, puis Compliance & Audit, Customer Operations, Fraud et Business Analytics) sont livrés au Manager sous forme de gabarits d'agents (Service Templates). Un gabarit décrit un produit : son nom, son éditeur, sa version, son statut et le service du catalogue qui l'installera une fois publié. Il n'est pas lui-même un service du catalogue. Le registre liste aussi les agents qui n'ont pas encore de gabarit (prévus ou en développement), pour que l'avancement de toute la plateforme soit visible.

L'onglet Agents de la page Services

La page Services d'un cluster affiche l'onglet Agents dès que le registre contient au moins un agent (adresse /services?tab=agents). L'onglet liste tous les agents de la plateforme, construits ou non, sous forme de cartes groupées par secteur : Banque, Assurance, Transverse, Industrie et Commerce. Dans un groupe, les agents qui ont un gabarit viennent d'abord, puis les agents en développement, puis les agents prévus.

• En-tête : une recherche (sans accents, elle lit aussi le libellé du statut), un filtre par secteur avec son effectif, et trois compteurs : agents, gabarits prêts à valider, publiés.
• Carte : icône et couleur du secteur, nom court (jamais la marque), une phrase, la version (dès que l'agent a un gabarit), un statut (Publié, En attente de validation, En développement ou Prévu) et le bouton Déployer. Détails ouvre la description complète, la raison pour laquelle l'agent ne se déploie pas, puis les composants, le service du catalogue et la documentation que l'agent possède. La carte d'un agent prévu est en pointillés.
• Agent publié : le bouton Déployer ouvre l'assistant d'installation du cluster avec le service du catalogue déjà sélectionné (/clusters/<cluster>/install?service=<service>). L'installation suit ensuite le parcours habituel (machines, paramètres, revue des dépendances).
• Agent en attente de validation : un administrateur voit le bouton Valider et publier à côté de Déployer (voir ci-dessous). Les autres utilisateurs voient Déployer désactivé avec la raison.
• Tout autre agent : le bouton est désactivé et la raison est affichée dans l'infobulle du bouton et dans les détails. Rien ne peut être installé avant que le gabarit soit construit, validé et publié.

Les agents sont préparés par Navin et ne peuvent être déployés qu'une fois validés et publiés. Tout utilisateur connecté voit l'onglet ; déployer exige la permission services:install sur le cluster, comme toute installation ; valider et publier exige agent_templates:publish (rôle administrateur).

Valider et publier un gabarit

La publication est la décision du client : elle se prend dans l'onglet Agents, jamais par une copie manuelle dans le catalogue. Sur la carte d'un agent En attente de validation, l'administrateur clique Valider et publier ; une boîte de dialogue rappelle le service du catalogue, la version et les composants, puis Publier :

1. Le Manager lit les sources du gabarit (le manifeste du produit nommé par source dans le registre, relatif à agent_sources_dir, et la définition de service qu'il désigne).
2. Il charge le catalogue complet avec cette définition sur une copie de travail : tous les contrôles du chargeur du catalogue (schéma, licence, modes, composants, gabarits Jinja présents, dépendances). Un seul problème refuse la publication (422 agent_template_invalid) et la boîte de dialogue affiche la liste ; rien n'est écrit.
3. Il copie services/<service>.yaml et templates/<service>/ dans published_templates_dir (/var/lib/navin-manager/published-templates dans un paquet), enregistre la publication (version, auteur, date) et l'audite (agent_template.publish). Le catalogue de catalog_dir n'est jamais modifié.

La carte passe aussitôt à Publié et Déployer devient actif pour tous les clusters. Les détails indiquent qui a publié le gabarit et quand, et offrent Retirer la publication : le service quitte le catalogue de ce Manager et l'agent revient en attente de validation (agent_template.unpublish). Le retrait est refusé tant qu'une instance du service est installée dans un cluster (409 agent_template_in_use).

Le bouton n'apparaît pas quand la publication est impossible, et les détails en donnent la raison : agent prévu ou en développement (pas encore de gabarit), sources absentes de ce Manager, définition de service non conforme au schéma du catalogue (le produit doit la corriger ; le nombre de problèmes est indiqué), ou service déjà livré avec le catalogue.

Le registre

Le registre est le répertoire navin-manager/agent-templates d'un dépôt, ou /usr/share/navin-manager/agent-templates dans un paquet (réglage agent_templates_dir, variable NM_AGENT_TEMPLATES_DIR). Il contient un fichier YAML par agent, validé par son schema.json au chargement : identifiant (égal au nom du fichier), nom et description en français et en anglais, éditeur, secteur, nom court et résumé (recopiés du manifeste du produit) et un statut.

Statut	Libellé	Sens	Champs
planned	Prévu	Spécifié, rien de construit	ni version, ni service du catalogue, ni composants
in_development	En développement	En construction, pas encore de gabarit	comme planned
prepared	En attente de validation	Gabarit construit, jamais déployable	version, service du catalogue, documentation, sources et composants obligatoires
published	Publié	Validé par le client	comme prepared

Le schéma refuse une version, un service ou des composants sur un agent sans gabarit, et les exige tous sur un agent préparé ou publié. Un descripteur invalide empêche le chargement du registre et le problème est listé dans l'erreur. Le serveur relit le registre dès qu'un de ses fichiers change : un agent ajouté ou modifié apparaît sans redémarrage.

Le Manager ne marque un agent published que si deux conditions sont réunies : son service existe dans le catalogue chargé (catalogue livré plus gabarits publiés sur ce Manager) et le gabarit a été publié, soit par la version livrée (statut published du registre), soit par un administrateur depuis l'onglet Agents. Tout autre agent porte la raison de son statut (« Non publié, en attente de validation », « En cours de développement, pas encore de gabarit à valider » ou « Agent prévu, pas encore développé »). La publication d'un gabarit est une décision explicite du client : rien n'est copié dans le catalogue avant cette validation.

L'API

Lecture ouverte à tout utilisateur connecté comme le catalogue de la pile ; publication réservée à la permission agent_templates:publish :

Opération	Rôle
GET /api/v1/agent-templates	Liste des gabarits (items, count), avec published, reason, publication, publishable et publish_blocker
GET /api/v1/agent-templates/{template_id}	Un gabarit par identifiant ; 404 (agent_template_unknown) s'il est inconnu
POST /api/v1/agent-templates/{template_id}/publish	Valide et publie le gabarit sur ce Manager ; 409 (agent_template_not_publishable, agent_template_sources_missing, agent_template_already_published) ou 422 (agent_template_invalid, problèmes dans details.problems)
DELETE /api/v1/agent-templates/{template_id}/publication	Retire la publication ; 404 (agent_template_not_published) ou 409 (agent_template_in_use)

Les SDK Python, TypeScript, Go et Java exposent ces opérations dans le groupe agent_templates / agentTemplates. Les erreurs suivent le format normalisé du Manager (error.code, error.message, error.message_i18n).