SYS_PRO_1 — Orchestration des appels LLM

Manuel LÉGER (Direction technique déjà construite). Ce processus est implémenté et testé (Lots 3 → 6h, clôturés). Cette fiche décrit le processus et renvoie aux workflows n8n et ADR existants ; elle ne réinvente rien. Source du quoi technique : 07_Reference_Systeme.md §B2.3 / B2.3ter / B2.11. Source du pourquoi : 03_Registre_Decisions.md ADR-028/029. [CORPUS]

Objet et finalité

Fournir le point d'appel unique de tout agent IA du système : recevoir une demande d'appel (clé agent + message), assembler la requête (prompt système + utilisateur, modèle résolu, contrat de sortie), exécuter l'appel LLM via OpenRouter, parser la réponse, et rendre une sortie normalisée — succès ou échec. [CORPUS]

Finalité métier : aucun workflow d'agent ne parle directement à un fournisseur LLM. Tout passe par cette plomberie, ce qui garantit (a) un format de sortie déterministe (ADR-028), (b) la capture systématique de la télémétrie (ADR-029, cf. SYS_PRO_2), (c) une gestion d'erreur homogène (cf. SYS_PRO_5), (d) la résolution centralisée du modèle (cf. SYS_PRO_3). [CORPUS]

C'est la colonne vertébrale du jumeau numérique : le pattern d'invocation T (transactionnel) d'ADR-039. [CORPUS]

Pilote

Direction pilote : SYS — Système.
Agent / acteur pressenti : aucun agent LLM « pilote » — ce processus est la plomberie qui sert les agents. Opéré par les sub-workflows n8n agent_call (orchestrateur), prepare_agent_call (assemblage), get_agent_config (DAL config). Responsable humain : le gérant (administration de la stack). [CORPUS]

Déclencheurs (entrées)

Appel Execute Workflow de agent_call par n'importe quel workflow métier (Lots 9+) ou de test. [CORPUS]
INPUT contractuel : { agent_key, dossier_id?, task_type?, runtime_inputs:{ user_message } }.
- agent_key = clé canonique CODE-NN (ex. DEX-01, SYS-99). [CORPUS]
- dossier_id / task_type portés de bout en bout jusqu'au log de télémétrie (ne transitent pas par prepare_agent_call). [CORPUS]

Sorties et livrables

OUTPUT succès : { success:true, content (objet JSON si schéma, sinon string), raw_text, agent_key, model, resolved_from_mode, usage:{prompt_tokens, completion_tokens, reasoning_tokens, total_tokens, cost_usd}, latency_ms, error:null }. [CORPUS]
OUTPUT échec : { success:false, content:null, raw_text:null, agent_key, model, resolved_from_mode, usage:{…null}, latency_ms, error:<message> } — même contrat de surface que le succès (l'appelant teste success). [CORPUS]
Effet de bord systématique : 1 ligne écrite en telemetrie.appels_llm (succès ou échec), fire-and-forget (cf. SYS_PRO_2). [CORPUS]

Acteurs

Acteur	Rôle	Nature
`agent_call`	orchestrateur unique (validate → prepare → switch → HTTP → parse → log → output)	sub-workflow n8n [CORPUS]
`prepare_agent_call`	assemble messages `[system,user]`, garde de capacité, livraison du contrat	sub-workflow n8n [CORPUS]
`get_agent_config`	DAL — retourne la « ligne » de config résolue de l'agent	sub-workflow n8n [CORPUS]
OpenRouter	fournisseur LLM (proxy multi-modèles)	service externe [CORPUS]
Workflow appelant	fournit `agent_key` + `runtime_inputs` ; consomme `success`/`content`	tout workflow métier [CORPUS]

Logigramme (étapes macro)

[appelant] Execute Workflow agent_call { agent_key, dossier_id?, task_type?, runtime_inputs }
   │
[1] Validate input            (exige agent_key ; défauts dossier_id/task_type = null)
   │
[2] Call prepare_agent_call   → délègue à get_agent_config (DAL) : résout modèle, capacité, schéma
   │                             assemble messages[system,user] (+ injection plancher si schéma actif)
   │
[3] Switch type_agent
   │   ├─ "chain"        → [4] Build OpenRouter body (+t0)
   │   │                   [5] HTTP POST OpenRouter /chat/completions (usage:{include:true})
   │   │                   [6] Parse response
   │   │                   [7] log_llm_call (fire-and-forget)  → cf. SYS_PRO_2
   │   │                   [8] Hook observabilité (NoOp, trace_id=null)
   │   │                   [9] Output { success:true, content, usage, latency_ms }
   │   │                   ── sur échec (HTTP non-2xx | soft-error D2) ──→ branche llm_error (SYS_PRO_5)
   │   └─ "agent_tools"  → throw « non câblé — Lot 11 »

Détail nœud-par-nœud : 07_Reference_Systeme.md §B2.11 (topologie figée, IDs réels). [CORPUS]

Procédures et instructions rattachées

SYS_PQ_1 — Procédure d'orchestration des appels LLM (renvoie aux workflows + ADR).
SYS_IQ_1 — Instruction : appeler un agent via agent_call (contrat d'entrée/sortie, règles de format, seuils).
SYS_FQ_2 — Formulaire : enregistrement d'un appel LLM (telemetrie.appels_llm) — enregistrement partagé, propriété de SYS_PRO_2 (décrit là-bas comme livrable principal) ; ce processus en est producteur.

Interfaces amont/aval (handoffs)

Amont : tout workflow métier (Lots 9+) qui a besoin d'une production IA. Contrat = INPUT ci-dessus. [CORPUS]
Aval interne SYS :
- → SYS_PRO_2 (Télémétrie) : log_llm_call est appelé en fin de chaîne (succès et échec). [CORPUS]
- → SYS_PRO_3 (Gestion des modèles) : le modèle et sa capacité structured_outputs sont résolus via get_agent_config qui lit le manifeste agents.json + la vue view_native_output_schema.json. [CORPUS]
- → SYS_PRO_4 / SYS_PRO_5 (Notifications / Erreurs) : sur échec LLM, émission d'une notif llm_error + sortie propre. [CORPUS]
Aval métier : la sortie content est consommée par l'agent appelant (DEX, ADV, DAF…) qui en fait un livrable. SYS ne porte aucune logique métier ni donnée client (frontière 08 §4). [CORPUS]

Indicateurs (KPI)

KPI	Définition	Source	Cible indicative
Taux de succès des appels	`count(success=true) / count(*)`	`telemetrie.appels_llm`	> 98 % [STANDARD] [À CONFIRMER]
Latence médiane par appel	médiane `latency_ms`	`telemetrie.appels_llm`	[À COMPLÉTER — référence à fixer après volume réel]
Coût moyen par appel / par dossier	moy. `cost_usd` group by `task_type` / `dossier_id`	`telemetrie.appels_llm`	suivi dashboard 8bis-A [CORPUS]
Taux de conformité du format de sortie	part des réponses parsées sans fallback quand schéma attendu	log (fast-follow D3, non câblé)	[À COMPLÉTER]

Enregistrements

telemetrie.appels_llm — 1 ligne par appel (20 colonnes ; cf. SYS_FQ_2). Append-only. [CORPUS]
Historique d'exécutions n8n (rétention native, non structurée). [CORPUS]

Cas d'usage rattachés (UC-* du Recueil + nouveaux)

UC-A11 — Relancer une production insuffisante (model_override à modèle supérieur, nouvelle tentative) : s'appuie sur agent_call avec un agent_key/modèle ajusté. [CORPUS]
UC-E05 — Re-engager un agent (Q&A) : pattern conversationnel C (ADR-039) = agent_call + wrapper mémoire (jamais le nœud agent natif n8n). [CORPUS]
UC-SYS-01 (nouveau) — Invoquer un agent en mode transactionnel one-shot avec sortie structurée garantie (le cœur de ce processus). [STANDARD]
Transverse : tout UC des familles A/B/C qui fait produire un agent passe physiquement par agent_call. [CORPUS]

Roadmap (PQ/IQ/FQ restant à développer)

SYS_IQ_1_2 — Instruction « brancher la branche agent_tools » (Lot 11, actuellement throw explicite). [CORPUS]
SYS_IQ_1_3 — Instruction « assemblage multimodal binary_inputs » (Lot 11). [CORPUS]
Fast-follow D3 — garde « parse JSON raté quand schéma attendu » (severity warning) dans Parse response → à documenter en instruction quand livré. [CORPUS]
Pattern conversationnel C (wrapper mémoire chat_memory) — fiche/instruction dédiée quand l'agent conversationnel (P28) sera construit. [CORPUS]