ADR-0184 : Navin Customer Operations Agent, un moteur commun et trois packs sectoriels au-dessus du Control Plane

• Statut : accepté le 2026-11-04 ; trois points tranchés par l'utilisateur le jour même (voir « Décision sur les points à valider »)
• Date : 2026-11-04
• Portée : nouveau projet navin-customer-operations/ (backend FastAPI, workers, écrans dans le frontend commun des agents sectoriels (ADR-0180), intégration Navin, docs), domaine additif du Control Plane services/control-plane/src/eai/domains/customer_ops/ (cycle de vie), migrations V220 à V229, types OpenFGA additifs (deploy/policies/openfga/model.fga), paquet OPA eai.customer_ops (deploy/policies/opa/customer_ops.rego), écrans d'activation du portail Enterprise, gabarit de service préparé mais non publié
• Documents liés : ADR-0101 (politique de licences), ADR-0103 (vLLM et LiteLLM), ADR-0108 (Opik), ADR-0166 (analyse ClamAV et YARA-X), ADR-0173 (téléphonie Asterisk, Kamailio, LiveKit), ADR-0174 (mémoire Mem0 et Cognee), ADR-0175 (RAG Agent, modèle de référence), audit navin-customer-operations/docs/NAVIN_INTEGRATION_AUDIT.md

Contexte

Le client demande un agent d'opérations clients pour la banque, l'assurance et le commerce de détail : réception multicanale, identification des clients, compréhension et routage des demandes, dossiers et SLA, workflows, recherche documentaire, mémoire contrôlée, consultation des systèmes métiers, actions autorisées, transfert vers un conseiller, console et copilote, tableaux de bord et qualité.

L'audit du 2026-11-04 montre que Navin fournit déjà le runtime d'agents (exécutions, sous-agents, approbations, reprise), la passerelle de modèles devant LiteLLM, les bases de connaissances (V206, V207), la mémoire par le contrat Navin Memory Provider avec Cognee, l'analyse des fichiers, le stockage SeaweedFS, Presidio, l'évaluation (Ragas, Promptfoo), le domaine channels (réception seulement), un domaine connectors générique avec Connector Broker et webhooks dédupliqués, la plateforme de téléphonie et, dans le RAG Agent, une couche produit complète (BFF, SSE avec reprise, citations, cycle de vie, gabarit non publié). Il manque l'identité des clients externes, l'envoi sortant sur les canaux, tout connecteur d'éditeur (Shopify, Salesforce, transporteurs, paiement : absents du Control Plane), un temps réel générique pour une console et un moteur de workflows métier.

Le cahier des charges détaillé cité par les tâches (sections numérotées) n'est pas disponible dans le dépôt : l'utilisateur a choisi le 2026-11-04 de poursuivre avec les descriptions des tâches du board. Les listes (événements, contrat d'outil, décisions de politique, scénarios) sont donc définies par cette ADR et par les contrats v1, et pourront être réalignées sur le cahier des charges quand il sera fourni.

Décision

1. Une couche produit sur le Control Plane, comme l'ADR-0175

Qui	Fait quoi
Navin Manager	installe et exploite le runtime du produit (API, workers, web), ses dépendances, TLS, santé, sauvegardes, mises à jour
Control Plane	tenants, projets, rôles, modèles, canaux entrants, bases de connaissances, mémoire, analyse des fichiers, stockage, connecteurs et secrets, quotas, audit, politiques, traces, cycle de vie de l'instance
Backend du produit	conversations, contexte client, intentions et routage, dossiers, SLA, workflows, transferts, console, actions, packs ; il appelle le Control Plane uniquement par le SDK Python enterprise_ai

Le backend n'appelle jamais directement Qdrant, Cognee, LiteLLM, Docling, ClamAV, YARA-X ni Presidio : il passe par les domaines du Control Plane.

2. Un moteur commun et trois packs, pas trois applications

Un seul produit porte le moteur (conversations, dossiers, SLA, workflows, outils, transfert, console). Les secteurs sont des packs versionnés et validés par schéma (contracts/v1) : intentions, connecteurs, workflows, politiques, types de dossiers, formulaires, modèles de réponses, règles d'escalade, indicateurs et SLA par défaut. Trois packs sont livrés : Banque, Assurance, Retail. Aucun délai commun n'est imposé aux trois secteurs.

3. Réutilisation

• Du RAG Agent : structure du projet, authentification, autorisations, Redis éphémère, travaux durables, SSE, rendu Markdown, citations, coque de l'interface, cycle de vie dans le Control Plane, gabarit non publié. Le code est repris dans le nouveau projet et adapté ; aucune importation croisée entre produits.
• Du Compliance & Audit Agent : développé en parallèle, rien n'est repris dans cette version ; une mise en commun éventuelle se fera après fusion, par une décision distincte.
• L'écosystème Guidia n'est pas réutilisé (choix de l'utilisateur du 2026-11-04).

4. Identité des clients externes

• Les clients finaux ne reçoivent aucun compte Keycloak. Leur identité vient d'une des sources configurées par instance : fournisseur OIDC du client (jeton vérifié sur son JWKS, émetteur et audience attendus), fédération (même contrôle), session du portail client existant (assertion signée), ou authentification renforcée déléguée au système métier (le système source confirme et le produit ne voit que le résultat).
• Le résultat est un contexte d'authentification client lié à la conversation : identité vérifiée, périmètre d'accès (références opaques), niveau d'assurance, source, expiration.
• Niveaux : 0 public (informations générales), 1 identifié (identité déclarée et vérifiée par un lien ou un canal), 2 authentifié (jeton OIDC ou session vérifiés), 3 action contrôlée (authentification renforcée récente déléguée). Chaque action déclare son niveau minimal ; la montée de niveau passe par un parcours sécurisé hors du chat.
• Le chat ne demande jamais un mot de passe, un code PIN ou un code d'authentification ; un tel code écrit par un client est masqué avant stockage et n'est jamais transmis au modèle.
• Les utilisateurs internes (conseillers, superviseurs, administrateurs) passent par Keycloak comme dans le RAG.

5. Canaux

• Réception par le domaine channels du Control Plane (email, WhatsApp, web, API) quand ils sont configurés ; chat web, widget intégrable, portail client et console dans le produit.
• Les webhooks de canal portent une signature HMAC avec fenêtre de 5 minutes ; le produit ajoute la déduplication par identifiant de livraison, absente du domaine channels.
• Envoi sortant (choix de l'utilisateur) : adaptateurs du produit (SMTP, WhatsApp Cloud API) par la garde de sortie, secrets dans OpenBao ; un canal sans réglage est signalé « non configuré », jamais simulé.
• Téléphonie facultative sur la plateforme existante (ADR-0173), sans nouveau PBX.
• Chaque canal a un plafond de sensibilité : aucune donnée bancaire ou assurantielle sur un canal dont le niveau ne le permet pas.

6. Connecteurs métier

• Uniquement le domaine connectors du Control Plane et des adaptateurs au contrat de connecteur Navin (manifeste Connector, Connector Broker, garde de sortie, secrets OpenBao).
• Lecture seule par défaut ; écriture seulement avec permission, décision de politique et approbation. Aucune requête SQL générée par un modèle.
• Aucune copie du CRM, du core banking, des polices ou des commandes : le schéma du produit ne garde que des références et des données opérationnelles ; les systèmes métiers restent propriétaires de leurs données.
• Un connecteur n'est déclaré opérationnel qu'après un test réel ou sur un serveur de test local qui suit l'API publiée ; son statut est documenté.

7. Données du produit

• Schéma customer_ops par Alembic dans une base dédiée, SQLAlchemy 2 asynchrone, asyncpg ; RLS forcée sur chaque table portée par un tenant, contexte posé par SET LOCAL à chaque transaction ; index par tenant et projet.
• Travaux durables dans PostgreSQL (FOR UPDATE SKIP LOCKED) avec identité signée, outbox ; Redis seulement pour l'éphémère (cache, débit, verrous, idempotence, coordination du streaming).

8. Workflows et règles

• Pas d'orchestrateur concurrent : les workflows du produit sont des machines à états persistées et exécutées par les travaux durables, avec les exécutions, approbations et reprises du runtime Navin.
• Règles d'éligibilité déterministes (code ou système source) : un modèle ne peut ni les modifier ni les contourner ; il propose, le moteur décide.

9. Modèles, exécution et sous-agents

• Les agents logiques sont des agents du registre Navin exécutés par son runtime ; aucun gain de privilège par délégation ; une demande simple est traitée en un seul appel de modèle.
• Tous les appels de modèles passent par la passerelle /v1/gateway/* devant LiteLLM ; modèles autorisés lus dans Navin ; budgets et quotas Navin.

10. Mémoire

• Contrat Navin Memory Provider, Cognee selon l'essai validé du RAG (navin-enterprise-rag/docs/COGNEE_TRIAL.md : vecteurs pgvector, graphe LadybugDB embarqué, isolation prouvée) ; identifiants sensibles, secrets, codes et données de paiement jamais mémorisés ; graphes jamais substitués à la vérité métier.

11. Sécurité et autorisations

• OpenFGA (types additifs de l'instance, de la conversation, du dossier, de la référence client, de l'outil, du document, de l'équipe, de la file, de l'export et des métriques) et OPA (eai.customer_ops) en fail-closed : refus si un moteur ne répond pas ; 404 pour une ressource d'un autre tenant.
• Presidio par le domaine privacy, analyse ClamAV et YARA-X de toute pièce jointe, contenu des documents et des résultats d'outils traité comme donnée non fiable.

12. Observabilité

Conforme à l'ADR-0101 : OpenTelemetry vers le collecteur Navin, traces IA dans Opik par le Control Plane sans contenu de comptes, contrats, sinistres ou paiements, métriques Prometheus sans label à forte cardinalité, journaux vers Alloy et OpenSearch, alertes par Alertmanager, traces techniques dans Jaeger, analyses dans ClickHouse. Grafana, Loki et Tempo sont refusés (AGPL-3.0).

13. Activation et cycle de vie

Sur le modèle de rag_agent : domaine customer_ops du Control Plane, états et étapes tracés, Ready seulement après les contrôles de santé et le test de démarrage, transitions idempotentes, suppression limitée aux ressources propres. Parcours d'activation dans le portail Enterprise. Gabarit préparé selon le vrai schéma du Manager et jamais publié sans la validation explicite de l'utilisateur.

14. Vérité des capacités

Aucune fonction n'est déclarée terminée sans test réel ; aucune capacité, aucun SLA et aucune HA ne sont annoncés sans mesure. Les limites sont écrites dans navin-customer-operations/docs/KNOWN_LIMITATIONS.md.

Conséquences

• Un seul moteur à maintenir pour trois secteurs ; un secteur de plus est un pack, pas une application.
• Les connecteurs d'éditeurs restent à écrire et à tester un par un : rien n'est annoncé sans test.
• Deux outils de migration dans le dépôt (Alembic pour customer_ops, V*.sql pour le Control Plane), comme pour le RAG.
• Le code repris du RAG est dupliqué tant qu'une bibliothèque commune n'est pas décidée.

Points à valider par le client

1. Envoi sortant sur les canaux email et WhatsApp, absent du domaine channels.
2. Écosystème Guidia, introuvable dans le dépôt.
3. Cahier des charges détaillé, introuvable dans le dépôt.
4. Installation dédiée par instance pour les banques tant que la séparation de Cognee n'est que logique (repris de l'ADR-0175).
5. Remplacement de Grafana, Loki et Tempo par les composants autorisés (repris de l'ADR-0175).

Décision sur les points à valider

Le 2026-11-04, l'utilisateur a tranché :

1. Envoi sortant par des adaptateurs du produit (SMTP, WhatsApp Cloud API) par la garde de sortie et OpenBao, canal signalé « non configuré » sans réglage ; le domaine channels partagé n'est pas modifié.
2. Guidia n'est pas réutilisé pour ce produit.
3. Les listes sont définies à partir des descriptions des tâches du board ; l'écart avec le cahier des charges est noté ici et pourra être réaligné.

Les points 4 et 5 reprennent les décisions déjà acceptées de l'ADR-0175.

Alternatives écartées

• Trois applications sectorielles : triple maintenance et gouvernance divergente.
• Comptes Keycloak imposés aux clients finaux : contraire à l'identité déjà détenue par le client.
• Copie du CRM ou du core banking dans le produit : double vérité et données sensibles hors des systèmes sources.
• Moteur de workflows externe concurrent du runtime Navin.
• Extension immédiate du domaine channels partagé pour l'envoi sortant : écartée par l'utilisateur pour éviter les conflits avec les autres produits développés en parallèle.
• Appels directs à LiteLLM ou aux moteurs (Qdrant, Cognee, Presidio).

Plan de réalisation

Quarante-cinq étapes « CO » suivies sur le tableau du projet : audit et architecture (P1), fondations (P2), conversations et canaux (P3), demandes, dossiers, SLA et workflows (P4), connaissances et mémoire (P5), connecteurs, données clients, actions et agents (P6), packs, transfert et console (P10), écrans (P11), sécurité, observabilité et qualité (P12), cycle de vie et activation (P13), validation finale (P14).