Une architecture qui fait échouer le build : architect-os, suivi dans son code
La plupart des plateformes d’agents sont décrites par un schéma et tenues par la relecture. Celle-ci est assez petite pour être lue en une après-midi et assez stricte pour qu’un import interdit fasse échouer le build : l’architecture est imposée, pas seulement décrite.1 Un client appelle un outil d’intention sur une passerelle unique ; le service propriétaire de l’outil lance un agent dans un bac à sable et répond par un résultat validé.2 C’est un squelette, et il dit où il s’arrête.35
Le texte du film, scène par scène
- Une architecture en couches ne tient que si quelque chose l’impose. Dans architect-os, l’architecture est imposée, pas seulement décrite : un mauvais import fait échouer le build.
- Quatre niveaux, un seul chemin pour un appel. Un client appelle un outil d’intention ; la passerelle le route vers le service qui le possède. Proxy: le seul composant exposé. Passerelle: authentification, catalogue, routage, quotas, audit. Service: lance un worker Claude Agent SDK isolé. Données: le seul composant qui importe pg.
- Chaque composant : quatre couches, une racine de composition. domain: entités et ports. application: cas d’usage, ports injectés par constructeur. infrastructure: adaptateurs, dont un en mémoire pour chaque port. presentation: traduction MCP ou HTTP, rien d’autre. src/main.ts: le seul endroit qui construit des objets.
- Des frontières strictes, contrôlées par npm run arch. pg: seulement dans data/src/infrastructure. Claude Agent SDK: seulement dans services/*/worker. SDK MCP: seulement en presentation et infrastructure. Cycles d’import: aucun.
- Les échecs sont des valeurs. Un appel d’outil renvoie un Result de statut failed avec un code d’erreur nommé ; rien ne lève d’exception à travers une frontière de service.
- Chaque brique arrive avec ses tests. Des tests unitaires pour chaque couche touchée. Un test de contrat par port, lancé sur chaque adaptateur, y compris celui en mémoire. Un cas de bout en bout quand elle est sur le chemin d’un appel.
- Ce qu’il ne fait pas encore. Un squelette d’architecture, sans release. Le chemin réel du SDK d’agent n’est pas exercé par la suite par défaut. Les images Docker et docker compose up ne sont pas exercés par la CI.
- architect-os. Paquet agentic-ai 0.1.0, MIT. Deux outils d’intention : recall et remember. $ npm ci $ npm run check
Sources: Sources : CLAUDE.md, README, docs/testing.md et CHANGELOG de cdeust/architect-os au commit f699c89. Aucune release n’existe ; le film décrit le squelette sur main.
Un point d’entrée, quatre niveaux, un seul chemin typé vers les données
Un client voit un serveur MCP et deux outils. Derrière ce serveur, quatre niveaux, dont chacun ne parle qu’à son voisin : un proxy qui est le seul composant exposé, une passerelle, un service par domaine et un composant de données.34 La passerelle authentifie l’appelant, applique un quota, route l’appel vers le service propriétaire de l’outil et le journalise. Elle ne lance aucun agent et ne touche à aucune donnée, et elle transmet la réponse du service sans l’interpréter.5
Les outils sont des outils d’intention : recall et remember, pas « chercher » et « insérer ».6 Les outils de bas niveau existent, mais seul un agent dans un worker peut les appeler, et chacun est déclaré une fois comme une vue d’une opération de données.7 Donner les outils de bas niveau aux clients a été envisagé puis rejeté : cela reporte le coût, les limites et la validation sur chaque client et ne laisse aucun endroit unique où valider la sortie.8 La base de données est derrière le même resserrement : un seul composant importe le pilote, et il expose des opérations nommées et typées, jamais de SQL libre.10
Le découpage en couches est un jeu de règles, et un test prouve qu’elles mordent
Le découpage à l’intérieur d’un composant est classique : domaine, application, infrastructure, présentation, et une racine de composition qui est le seul endroit où les objets sont construits.13 Ce qui l’est moins, c’est que rien ne repose sur la relecture. Douze règles nommées, dans un seul fichier de configuration, sont exécutées par la même commande que les tests, et la CI exécute cette commande.141516
Trois de ces règles confinent une dépendance à un seul endroit : le pilote de base de données à l’infrastructure du composant de données, le Claude Agent SDK à un worker, le SDK MCP à la présentation et à l’infrastructure.171819 Un garde qu’on n’a jamais vu échouer ne prouve pas grand-chose. Un test écrit donc un fichier fautif par règle dans les vrais répertoires des composants, vérifie que chaque règle se déclenche sur son fichier, supprime les fichiers et vérifie que l’arbre est de nouveau vert.20 Le registre des décisions en donne la raison en une ligne : les relecteurs laissent passer des imports, la CI non.22
Un agent sans outils propres, et une réponse qui est vérifiée
Chaque appel a son propre conteneur : système de fichiers en lecture seule, toutes les capacités retirées, utilisateur non root, limites de mémoire et de processus, un seul réseau interne.2324 À l’intérieur, l’agent n’a aucun outil intégré. Sa liste d’outils est vide, les outils autorisés sont ceux, internes, du service, aucun fichier de réglages n’est chargé et aucune session n’est conservée.25 Ces options restent dans le code à dessein : la documentation les appelle le plancher de sécurité, par opposition au comportement, qui vit dans des fichiers.26
Le worker ne décide pas si sa propre sortie est digne de confiance. Le service analyse ce que le worker a écrit et le valide contre le schéma de l’outil ; un écart est enregistré comme un échec avec un code nommé, parce qu’un agent victime d’une injection de prompt pourrait sinon renvoyer n’importe quoi.2728 Les échecs sont des valeurs : chaque outil répond par un Result, dont le code d’erreur vient d’une liste fermée.2930 Chaque étape d’un appel est enregistrée comme un événement de son run.31 Un run terminé ne peut pas être terminé une seconde fois, et cette règle est tenue par un déclencheur de base de données, pas par du TypeScript.32