Documenter un système d'agents d'IA avec le modèle C4

Les projets d'agents changent vite de forme : une passerelle d'outils apparaît, la mémoire passe dans son propre entrepôt, un deuxième fournisseur de modèles s'ajoute. Le schéma du wiki cesse généralement de correspondre au système en quelques semaines, et il n'a souvent jamais répondu à la première question d'une nouvelle recrue : quelles sont les parties, et qui parle à qui?

Quatre niveaux, et vous avez rarement besoin de tous

Le modèle C4, créé par Simon Brown, décrit le logiciel selon quatre niveaux de zoom : système logiciel, conteneur, composant et code. Le site de C4 est explicite : il n'est pas nécessaire d'utiliser tous les niveaux, et les schémas de contexte du système et de conteneurs suffisent à la plupart des équipes.

Servez-vous des onglets ci-dessus pour passer d'un niveau à l'autre. Ils montrent la même plateforme d'agents d'exemple, chacun avec un cran de zoom de plus.

• C1, contexte du système : votre système en une seule boîte, avec les personnes et les autres systèmes autour. Pas encore de technologie.
• C2, conteneurs : les applications et les entrepôts de données qui s'exécutent séparément, avec la technologie de chacun et leur mode de communication.
• C3, composants : les parties à l'intérieur d'un conteneur. Ne le dessinez que pour le conteneur qui en a besoin. Ici, c'est le service d'agents.
• C4, code : classes et interfaces. Il vaut généralement mieux le générer à partir du code source que le dessiner à la main.

Ce qu'est un conteneur dans un système d'agents

Un conteneur est quelque chose qui doit être en marche pour que le système fonctionne : une application Web, un service d'agents, une passerelle d'outils, une base de données. Le fournisseur de modèles et les systèmes d'affaires ne nous appartiennent pas; on les dessine donc comme des systèmes externes, hors de la frontière.

Des règles pour garder le dessin lisible

• Un niveau par schéma, et le niveau dans le titre.
• Étiquetez chaque flèche avec ce qui se passe et, au besoin, le protocole : HTTPS, SQL, MCP.
• Nommez la technologie ou le rôle à l'intérieur de chaque conteneur, pour que personne n'ait à deviner.
• Tracez une frontière autour du système visé, pour que ce qui est externe soit évident.
• Dites ce que vous avez laissé de côté. Un schéma de niveau 2 qui omet le déploiement devrait le préciser.

Gardez-le à côté du code

Conservez la source du schéma dans le dépôt et révisez-la dans la même demande de fusion que le changement qu'elle décrit. Un schéma modifié avec le code reste honnête. Celui qui ne vit que dans une présentation, non.