ADR-0040 — Les profils d'agent sont adressés par prénom, et décrivent les rôles du runtime
Le site décrivait les cinq spécialistes de deux façons incompatibles.
Statut
Accepté · 2026-09-25
Piliers : ai-platform, growth-web
Contexte
Le site décrivait les cinq spécialistes de deux façons incompatibles.
Le runtime, c'est-à-dire ce que @Atlas délègue réellement, lit
src/features/ai/agents/agents/specialists.ts et
src/features/ai/orchestrator/team/team-roster.ts. Il connaît Marketing
(@Maya : pubs, flows Klaviyo, social, SEO), Merchandising (@Marco :
catalogue, prix, contenu du thème), Operations (@Otis : mise en place,
intégrations, webhooks, automatisations), Intelligence (@Faye) et Support
(@Sam). La doc publique /docs/agents, CLAUDE.md et llms.txt disaient
la même chose.
Les profils publics, eux, lisaient le registre d'identité
(identity-registry.ts), qui portait un second jeu : acquisition payante,
conversion et panier moyen, e-mail et SMS, analytics, rétention. La page
/agents/lifecycle affichait « @Otis builds your email and SMS flows »
pendant que chaque demande Klaviyo partait chez Marketing. Le carrousel de
la home, la leçon d'académie, l'article de lancement et le canvas de
/auth reprenaient ce second jeu.
Les URLs portaient ce second jeu : /agents/traffic, /conversion,
/lifecycle, /intelligence, /retention. Ces slugs de rôle avaient déjà
dérivé une fois (growth-web/0647 : la page /about citait des rôles que
le registre avait renommés), et /agents/intelligence était un troisième
« intelligence » à côté de /features/intelligence et du hub.
Enfin, /features/ai-team décrivait les mêmes six agents que /agents,
avec deux entrées de nav (« AI Team » et « The team »), et le JSON-LD
d'un profil était une Person avec un jobTitle et un worksFor : un
graphe de connaissance lisait six employés.
Le site est encore peu indexé. Un renommage coûte une redirection aujourd'hui, six quand la langue entrera dans l'URL (ADR 0038).
Décision
Un seul jeu de rôles, celui du runtime : le registre d'identité décrit ce
que le routeur fait, et ses outils sont ceux de la définition que le
délégué exécute. Un profil d'agent est adressé par le prénom en
minuscules (/agents/maya), jamais par son rôle, et les anciens slugs de
rôle répondent 308 vers le prénom. /features/ai-team fusionne dans
/agents. Le JSON-LD d'un agent est une SoftwareApplication créée et
publiée par l'Organization.
Alternatives écartées
| Option | Pourquoi non |
|---|---|
| Garder les rôles des profils et aligner le runtime dessus | Le runtime est ce que le produit fait. Réécrire le routage pour coller à une copie marketing aurait changé le comportement d'@Atlas pour cinq pages, et l'éval de routage (evals/routing.eval.ts) aurait été réécrite pour suivre la copie au lieu de la garder honnête. |
Garder les slugs de rôle, alignés sur les rôles du runtime (/agents/marketing, /agents/operations…) | Cinq redirections aujourd'hui pour des slugs qui redériveront au prochain renommage de rôle, comme ils l'ont déjà fait une fois. Et /agents/intelligence restait un troisième « intelligence ». Un prénom ne bouge pas quand un rôle bouge. |
Slugs ag-spec-* (les ids internes) | Illisibles pour un humain, et l'id de @Faye est ag-spec-finance, une clé historique persistée en base qu'aucun texte public ne doit exposer (team-roster.ts, PUBLIC_HANDLE). |
Garder /features/ai-team comme page produit distincte | Même équipe, mêmes agents, deux pages et deux entrées de nav : la page se contredisait elle-même (« six specialists » en meta, « @Atlas plus five specialists » en description). Son contenu propre (mémoire, skills, règles) est déjà documenté ailleurs. |
JSON-LD Person avec additionalType: SoftwareAgent | Un Person avec worksFor est un employé. Un agent est un logiciel : SoftwareApplication, creator et publisher = l'Organization (/#organization), isPartOf le produit (/#software). |
Conséquences
- Onze redirections 308 à garder pour toujours : cinq slugs de rôle, cinq
préfixes d'images (
/agents/<rôle>/*.png, déplacées sous le prénom) et/features/ai-team. Deux anciennes règles (/features/skills,/features/knowledge) pointent désormais directement sur/agents, sans chaîne. - Les clés de catalogue suivent le slug :
agents.registry.<prénom>,marketingPages.agents.profile.*.<prénom>,home.teamCarousel.agents.<prénom>. Ajouter un agent, c'est ajouter son prénom àAgentSluget un bloc dans les six catalogues. - Le titre d'un profil garde le métier en tête (« Shopify marketing ·
@Maya »,
agentPublicTitle) : on cherche un métier, pas un prénom. - Signal de révision : un agent renommé (prénom changé) ou deux agents portant le même prénom. Ni l'un ni l'autre n'est prévu.
Comment c'est appliqué
src/features/ai/agents/identity-registry-tools.test.ts: chaque profil de spécialiste annonce exactement les outils de sa définition runtime, le slug est le prénom en minuscules, et l'artwork vit souspublic/agents/<slug>/.src/app/(marketing)/agents/[slug]/_components/agent-scenarios.test.ts: chaque carte de scénario rejoue un cas deevals/routing.eval.tset ne s'affiche que sur la page de l'agent vers lequel l'éval route. Le cas Klaviyo (routé vers Marketing) et le cas webhook (routé vers Operations) y figurent.src/features/ai/prompts/kernel-team.test.ts: la liste des spécialistes du kernel, lue à chaque tour, nomme les domaines du roster et ne donne Klaviyo qu'à Marketing. Elle portait l'ancien jeu.src/app/(marketing)/agents/[slug]/_components/agent-json-ld.test.ts: le nœud est uneSoftwareApplication, sans aucune propriété dePerson.next.config.mjs, blocwave2:Cet blocwave2:GENERIC(ligne C) : les redirections.