Agents documentaires : 2. Penser l'architecture
Une fois le besoin, l'audience, le service et les bénéfices attendus définis (voir IA agentique : 1. Définir la stratégie), le défi suivant concerne l'architecture :
Comment concevoir le bon agent pour le bon environnement de connaissances ?
Un rédacteur technique ne travaille pas dans le vide.
Avant de concevoir un agent, il doit déjà comprendre l'écosystème documentaire : quelles connaissances sont disponibles, comment elles sont organisées, qui les produit et les utilise, et quelles parties peuvent ou doivent être exploitées.
Cette connaissance façonne directement le comportement de l'agent.
Sa conception dépend de :
- la connaissance à laquelle il peut accéder ;
- la structure et la hiérarchie de cette connaissance ;
- les audiences et la responsabilité du contenu ;
- les types et formats d'informations qu'il doit comprendre ;
- les métadonnées disponibles — ou absentes — et ce qu'elles décrivent ;
- le cycle de vie et le statut du contenu ;
- les skills dont il a besoin ;
- les actions qu'il est autorisé à effectuer ;
- le guidage fourni par son prompt : instructions, priorités et garde-fous.
Configurer l'agent n'est donc pas une simple phase de paramétrage technique.
C'est une extension de la stratégie documentaire, qui s'appuie sur la connaissance qu'a le rédacteur technique du corpus, des utilisateurs, de l'architecture de l'information, de la terminologie, de la gouvernance et des pratiques documentaires.
Comprendre le contenu avant de configurer l'agent
La documentation technique est rarement composée uniquement de texte.
Dans les écosystèmes documentaires sur lesquels j'ai travaillé ces dernières années, le contenu pouvait inclure :
- du texte ;
- des captures d'écran et illustrations ;
- des diagrammes, y compris des diagrammes Mermaid ;
- des visuels PNG et SVG ;
- des extraits de ligne de commande ;
- des endpoints d'API REST ;
- des exemples de bibliothèques Python ;
- d'autres exemples de code et instructions techniques ;
- des formules mathématiques.
C'est important, car l'agent doit être conçu à partir de la forme réelle de la documentation qu'il va traiter.
Dans les environnements techniques, le sens est souvent réparti entre plusieurs types de contenu. Une procédure peut combiner du texte explicatif, des instructions en ligne de commande, des extraits de code, des diagrammes et des exemples d'API.
L'agent doit donc être capable d'interpréter ces éléments ensemble, plutôt que de traiter la documentation comme un corpus purement textuel.
Cela m'a amenée à définir clairement, dans la conception de l'agent, des comportements tels que :
Traiter ensemble le code et la documentation.
Le même principe s'applique au contenu visuel.
Si des connaissances importantes sont portées par des diagrammes, des captures d'écran ou d'autres ressources visuelles, l'agent doit disposer des capacités nécessaires pour y accéder et les interpréter.
La question architecturale n'est donc pas seulement :
À quelles connaissances l'agent doit-il accéder ?
C'est aussi :
Sous quelles formes ces connaissances se présentent-elles, et lesquelles l'agent doit-il être capable de comprendre ?
La conception du prompt fait partie de l'architecture
La conception du prompt commence avant même sa rédaction.
Elle rassemble les décisions et les informations recueillies lors des étapes précédentes : le rôle de l'agent, le service qu'il doit fournir, les bénéfices attendus, les connaissances auxquelles il peut accéder, les types de contenu qu'il doit comprendre, les risques à éviter, ainsi que les politiques ou contraintes qui s'appliquent dans l'organisation.
Traduire les éléments de conception en instructions
Le prompt transforme tous ces éléments en un ensemble formel et structuré d'instructions.
| Élément de conception | Traduction dans le prompt |
|---|---|
| Rôle de l'agent | Description du rôle et de la mission |
| Besoin utilisateur et service attendu | Objectifs et cas d'usage typiques |
| Audience cible | Ton, niveau de détail, style de réponse |
| Bénéfices attendus | Critères de succès et résultats attendus |
| Surface de connaissances | Périmètre et sources autorisées |
| Contenus à exclure | Règles hors périmètre et restrictions |
| Types et formats de contenu | Instructions pour traiter texte, code, visuels ou autres contenus techniques |
| Structure documentaire | Règles de recherche et de navigation |
| Métadonnées et informations de cycle de vie | Règles de priorisation des sources et de fiabilité |
| Terminologie et vocabulaire | Règles de normalisation et références au glossaire |
| Politiques et contraintes de l'entreprise | Garde-fous et comportements obligatoires |
| Faiblesses documentaires connues | Gestion des conflits, ambiguïtés et règles de repli |
| Interaction utilisateur attendue | Format de réponse, guidage, escalade ou actions suivantes |
Plus ces éléments sont définis avec précision, plus le comportement de l'agent devient prévisible et utile.
Un processus de conception itératif
En pratique, la construction de ces prompts a été un processus itératif et collaboratif avec l'IA. J'ai utilisé Copilot, l'assistant IA disponible dans l'environnement de l'entreprise, comme partenaire de travail pour structurer les prompts, challenger les formulations, identifier les cas manquants, affiner les instructions et améliorer l'organisation des réponses attendues.
En tant que rédactrice technique et experte en documentation, je suis restée à l'initiative du projet et j'ai joué le rôle de chef d'orchestre du processus : définir la direction, superviser le travail, fournir les instructions et prendre les décisions de conception à partir du contexte documentaire, de ma connaissance du domaine et de ma compréhension des utilisateurs et de leurs besoins.
J'ai également joué un rôle d'éditrice tout au long du processus. Les prompts ont été progressivement affinés par la relecture, la correction, la post-édition et des itérations répétées, jusqu'à ce que le comportement de l'agent corresponde aussi précisément que possible au service attendu.
Rendre les priorités visibles dans le prompt
Les instructions critiques doivent être clairement identifiées afin que l'agent puisse les distinguer des consignes plus générales. Des libellés tels que IMPORTANT, Critical Rule ou Critical Behavior peuvent servir de marqueurs pour établir une hiérarchie entre les instructions et rendre leur priorité plus claire.
Le principe est comparable à celui de la précédence en CSS : certaines règles sont destinées à prendre le pas sur des règles plus générales. Par exemple, une instruction visant à exclure les informations propres à un client doit primer sur une consigne plus large demandant de récupérer autant de contexte pertinent que possible.
C'est particulièrement important lorsqu'un prompt combine des instructions de tâche, des comportements attendus, des restrictions de périmètre et des règles de repli.
Définir le périmètre comme frontière opérationnelle
La surface de connaissances définit où l'agent peut chercher des informations.
Les règles de périmètre et de hors-périmètre définissent comment l'agent est autorisé à se comporter dans cet environnement.
Ces règles traduisent la stratégie documentaire en limites opérationnelles.
Selon le service que l'agent doit fournir, elles peuvent définir :
- les types de demandes qu'il doit traiter ;
- les sujets, audiences ou informations qu'il doit exclure ;
- la manière dont il doit traiter les contenus mixtes ou ambigus ;
- les actions qu'il est autorisé à suggérer ou à exécuter ;
- les situations dans lesquelles il doit rediriger, escalader ou refuser de répondre.
Cela crée un lien direct avec les services définis précédemment (voir IA agentique : 1. Stratégie).
Un agent d'onboarding peut expliquer des concepts et guider les utilisateurs, mais doit éviter de répondre à des questions d'entreprise sans rapport avec son rôle.
Un agent de support peut fournir des instructions pas à pas et suggérer une escalade, mais ne doit pas inventer des étapes de dépannage non documentées.
Un agent d'analyse documentaire peut identifier des doublons ou incohérences, mais ne doit pas supprimer ou réécrire automatiquement du contenu sans validation.
Définir le comportement hors périmètre
Un agent utile doit donc aussi savoir quand ne pas répondre.
Si les connaissances disponibles sont incomplètes, contradictoires, hors du périmètre défini ou insuffisamment fiables, la réponse la plus sûre peut être d'indiquer clairement cette limite plutôt que de générer une réponse plausible.
Selon le cas d'usage, l'agent peut alors :
- demander une clarification ;
- découper une demande trop large en sous-thèmes plus petits ;
- ignorer les contenus hors périmètre et poursuivre la recherche ;
- limiter la réponse aux informations vérifiées ;
- pointer vers la source disponible ;
- recommander une validation ;
- rediriger l'utilisateur vers un autre service ou agent ;
- déclencher un mécanisme d'escalade ;
- ou simplement dire non lorsqu'aucune information fiable ou pertinente n'est disponible.
Cette capacité à prendre du recul n'est pas une faiblesse de l'agent. Elle fait partie de sa fiabilité.
Le comportement en cas d'échec doit être conçu aussi délibérément que le comportement en cas de succès. Ce n'est pas un cas marginal à ajouter après coup.
Exploiter les métadonnées pour qualifier les sources
Les métadonnées font partie de l'architecture de connaissances sur laquelle s'appuie l'agent.
Retrouver une information pertinente ne suffit pas. L'agent a aussi besoin d'indices qui l'aident à qualifier les sources qu'il trouve et à distinguer un contenu simplement disponible d'un contenu plus susceptible d'être actuel, faisant autorité ou fiable.
Ces règles de qualification des sources peuvent s'appuyer sur des métadonnées telles que :
- l'auteur et la responsabilité du contenu ;
- les dates de création et de mise à jour ;
- l'historique des pages et les informations de version ;
- le statut dans le cycle de vie ;
- les labels et catégories ;
- le type de source ;
- des indicateurs tels que
archived,deprecated,WIPou des statuts équivalents.
La proximité native entre Rovo et Confluence permet de baser ces règles sur les métadonnées Confluence, comme l'auteur ou l'historique des pages, ainsi que sur des métadonnées définies par l'utilisateur, telles que des statuts ou des labels.
Dans un site Web de documentation — comme celui que vous êtes en train de lire — les métadonnées structurées peuvent jouer le même rôle via le front matter, la taxonomie, les dates de publication et de modification, le statut du contenu, les informations canoniques ou d'autres champs lisibles par machine.
Ces métadonnées apportent un contexte supplémentaire qui aide l'agent à qualifier les informations récupérées et à distinguer ce qui est simplement disponible de ce qui est plus susceptible d'être actuel, faisant autorité ou pertinent.
Si ces signaux sont absents, incohérents ou mal maintenus, cette absence est elle-même une information utile : elle peut révéler des faiblesses dans la gouvernance documentaire, la gestion du cycle de vie ou la qualité des métadonnées.
Du SEO au GEO — Comment les métadonnées structurées peuvent améliorer à la fois la découvrabilité et la lisibilité par l'IA des sites de documentation.
Définir la surface de connaissances
Un agent documentaire ne doit pas nécessairement avoir accès à tout.
Une base de connaissances rassemble des contenus aux objectifs, niveaux de maturité, audiences, règles de responsabilité et exigences de confidentialité très différents.
Définir la surface de connaissances revient donc à décider exactement quelle partie du corpus l'agent est autorisé à utiliser et lui est nécessaire.
Cette décision répond à deux objectifs :
- protéger les informations qui doivent rester hors du périmètre de l'agent ;
- améliorer la pertinence en concentrant l'agent sur les connaissances nécessaires au service attendu.
Une surface trop étroite peut fournir trop peu de contexte et produire des réponses pauvres ou incomplètes. L'agent peut alors apporter peu de valeur supplémentaire.
Une surface trop large — par exemple « l'ensemble de la base de connaissances » ou « tout le contenu R&D » — peut créer le problème inverse : trop de bruit, des informations non pertinentes ou contradictoires, ou des contenus à des stades de cycle de vie très différents traités comme s'ils avaient la même autorité.
La bonne surface n'est donc ni la plus grande ni la plus petite possible.
C'est celle qui fournit suffisamment de contexte pour que l'agent puisse rendre son service de manière fiable, sans introduire de bruit inutile.
Dans mon cas, j'ai volontairement limité la surface à la documentation technique incluse dans mon audit. J'ai exclu les espaces marketing et communication, les espaces personnels, les contenus propres aux projets et les informations spécifiques aux clients.
Certaines exclusions ont été définies directement dans les prompts ; d'autres ont été appliquées via la configuration Knowledge de Rovo Studio.
Choisir la surface de connaissances fait partie de la stratégie documentaire.
Choisir les bons skills
Les skills font partie de l'architecture.
Une fois le rôle, le périmètre, les priorités et le comportement attendu de l'agent définis, il faut lui donner les capacités nécessaires pour remplir ce rôle.
La question n'est pas :
Quels skills sont disponibles ?
Mais plutôt :
De quelles capacités l'agent a-t-il besoin pour fournir le service pour lequel il a été conçu ?
Pour les agents documentaires, deux capacités sont particulièrement importantes.
Naviguer dans la hiérarchie
Un agent documentaire doit être capable de naviguer dans la structure de la base de connaissances, et pas seulement de récupérer des pages isolées.
Les connaissances pertinentes peuvent être réparties entre pages parentes et enfants, plusieurs niveaux de hiérarchie ou différents ensembles documentaires liés. L'agent doit donc pouvoir passer d'une page à l'autre tout en conservant suffisamment de contexte pour comprendre comment les informations s'articulent.
C'est particulièrement important dans les grands écosystèmes de documentation technique, où la réponse se trouve rarement sur une seule page.
Trouver la source de vérité
Retrouver une information ne suffit pas. L'agent doit aussi identifier quelles informations méritent le plus de confiance.
C'est particulièrement important dans les bases de connaissances ayant une longue durée de vie, où plusieurs versions peuvent coexister, où d'anciennes pages restent accessibles, ou encore où certains contenus sont marqués comme brouillon, WIP, archivé, "legacy" ou "deprecated".
Cette évaluation peut s'appuyer sur les métadonnées (voir plus haut) telles que les dates de mise à jour, les informations de version, le statut dans le cycle de vie, la responsabilité ou d'autres indicateurs d'autorité et de fraîcheur.
Le même principe s'applique à une base de connaissances comme Confluence et à un site de documentation dont les métadonnées sont suffisamment structurées et maintenues.
L'agent a donc besoin de capacités qui l'aident à distinguer une information simplement disponible d'une information probablement fiable, actuelle et faisant autorité.
Skills et tools sont différents
Un skill et un tool ne jouent pas le même rôle dans l'architecture d'un agent, notamment dans Rovo Studio.
- Un skill définit une manière réutilisable pour l'agent d'aborder ou d'exécuter une tâche.
- Un tool expose une capacité exécutable que l'agent peut invoquer, généralement avec des entrées et sorties définies.
Selon la plateforme d'IA, ces tools peuvent être fournis par la plateforme elle-même ou exposés via des intégrations, des connecteurs, des serveurs MCP ou d'autres systèmes externes.
La distinction devient particulièrement importante dès que l'on dépasse le cadre d'un agent autonome : les tools peuvent permettre à un agent d'interagir avec d'autres systèmes, de déclencher des actions, d'échanger des informations structurées ou de participer à une architecture multi-agents plus large.
De la spécialisation à l'orchestration
La spécialisation reste un principe architectural important.
Chaque agent doit avoir un rôle, un périmètre et un comportement attendu clairement définis. Un certain recouvrement peut néanmoins être utile lorsque les agents sont aussi conçus pour fonctionner de manière indépendante.
Par exemple, un agent de recherche d'information peut avoir besoin de capacités de base de normalisation terminologique même s'il existe un agent dédié au glossaire. L'objectif n'est pas d'éliminer tout recouvrement, mais de maintenir des responsabilités suffisamment distinctes pour que chaque agent reste compréhensible et utile.
Lorsque plusieurs agents spécialisés coexistent, un orchestrateur peut fournir un point d'entrée unique pour l'utilisateur.
L'utilisateur ne devrait pas avoir à savoir quel agent est responsable de la recherche, du support, de la terminologie ou de la qualité documentaire — ni même à décider à l'avance si sa question relève de telle ou telle catégorie.
L'orchestrateur peut interpréter la demande, mobiliser les expertises pertinentes, combiner les résultats et renvoyer une réponse unique et cohérente.
Cela crée une séparation utile entre :
- spécialisation interne : plusieurs agents, chacun conçu autour d'un service documentaire spécifique ;
- et simplicité externe : une seule interaction et une seule réponse consolidée pour l'utilisateur.
Une architecture simplifiée peut être représentée ainsi :
Ce schéma représente le principe architectural, et non le workflow d'exécution détaillé. Un orchestrateur réel peut utiliser un routage conditionnel, un traitement séquentiel, des appels parallèles ou d'autres chemins de décision selon la demande.
Bien que j'aie conçu le workflow d'orchestration pour mes quatre agents, je n'ai malheureusement pas pu l'implémenter, car je n'avais pas les droits d'accès à la configuration Tools nécessaire dans Rovo Studio.
Le rédacteur technique expert comme architecte d'agents
Concevoir un agent documentaire — et plus encore un système d'agents — demande bien plus que de savoir écrire un prompt.
Cela exige une expertise du domaine, de l'architecture de l'information, des utilisateurs et de leurs usages, de la terminologie, de la gouvernance et des métadonnées, ainsi que du contenu technique.
C'est pourquoi je qualifierais ce rôle comme relevant du rédacteur technique expert.
Le rédacteur technique travaille déjà à l'intersection des connaissances, des utilisateurs, des produits et des systèmes documentaires. La conception d'agents étend cette responsabilité à une nouvelle manière de consommer ces connaissances et d'interagir avec elles.
Le livrable n'est plus seulement une page, un guide ou un portail documentaire.
Dans une approche docs-as-data, le rédacteur technique conçoit aussi la manière dont les connaissances documentées peuvent être retrouvées, interprétées, combinées et réutilisées par des systèmes d'IA.
L'objectif n'est pas de remplacer les modes traditionnels de consultation de la documentation, mais de rendre les connaissances plus faciles à trouver et à utiliser grâce à des modes d'interaction complémentaires.
-
Les utilisateurs peuvent toujours parcourir, rechercher et lire directement la documentation.
-
Les agents peuvent ajouter une couche supplémentaire : interroger le corpus en langage naturel, consolider des informations distribuées, guider les utilisateurs ou transformer les connaissances documentées en service exploitable.
Les plateformes d'IA fournissent des modèles, des skills, des tools et des intégrations.
Mais la conception d'un agent documentaire fiable dépend toujours de l'expertise humaine pour déterminer quelles connaissances doivent être exposées, comment elles doivent être interprétées, quelles règles doivent gouverner l'agent et quel service il doit finalement fournir.
Concevoir le bon agent commence par comprendre les connaissances avant de configurer l'IA.
Poursuivez avec l'étape 3 : Tester et évaluer.
© Autrice : Florence Venisse, Experte en documentation technique & IA – Première version datée du 12 septembre 2026