Comment Fonctionne l'IA de Ce Site : Décortiquons une Production Mastra

L'assistant à qui tu parles est la démo

La plupart des agences te montrent une capture d'écran d'un chatbot. L'assistant IA de ce site est le vrai système, en production, construit sur Mastra. Ce guide l'ouvre en grand. Pas de théâtre de diagrammes, juste l'architecture, les compromis, et les parties qui comptent vraiment quand une fonctionnalité IA doit survivre à un trafic réel.

Le point que la plupart des équipes ratent : le modèle de langage représente peut-être dix pour cent d'un assistant IA en production. Les quatre-vingt-dix pour cent restants, c'est le routage, les tools, l'état, la langue, la sécurité, et les garanties de livraison ennuyeuses qui décident si un lead atteint un jour un humain. Nous avons couvert le pattern général dans Du Prototype IA à la Production. Voici le build concret.

La forme du système

L'assistant est un ensemble d'agents Mastra, chacun avec une tâche précise, exposés via des routes API Next.js :

• quoteAgent : l'assistant conversationnel sur les surfaces de devis et de contact. Il répond aux questions sur les services, qualifie naturellement, et capture les leads.
• chatbotAgent : un assistant léger pour la démo interactive.
• visionAgent, voiceAgent, analyticsAgent : des agents ciblés derrière le terrain de jeu de la démo.

Chaque agent est une simple déclaration : un nom, un jeu d'instructions, un modèle, et les tools qu'il est autorisé à appeler. L'identifiant du modèle est centralisé dans un seul module, donc le changer sur chaque agent est une modification d'une ligne et un déploiement, pas un chercher-remplacer à travers tout le codebase.

export const quoteAgent = new Agent({
  name: "quoteAgent",
  instructions: `...`,
  model: MODEL,
  tools: { submitProposal, scheduleCall, draftEmail, sendSummary },
});

C'est cette structure qui compte. L'agent ne contient pas de logique métier. Il décide quel tool appeler et quand. Les tools contiennent la logique.

Le tool calling, c'est là que le travail se fait

Un chat qui ne renvoie que du texte est un jouet. L'agent de devis a quatre tools, et les instructions sont écrites pour qu'il les appelle dès qu'il dispose des champs requis, sans demander à l'utilisateur la permission de continuer :

• submitProposal : capturer un lead projet (nom, email, résumé).
• scheduleCall : réserver un appel avec l'équipe.
• sendSummary : envoyer par email un résumé de la conversation.
• draftEmail : préparer un email que l'équipe relira.

La discipline qui rend tout ça utilisable est dans le prompt : collecter le minimum de champs requis, puis agir. Pas de boucles "dois-je continuer ?", pas d'accusés de réception vides. Quand l'utilisateur a donné un nom, un email et un résumé de projet, le tool de proposition se déclenche. L'utilisateur obtient un résultat clair, pas une impasse.

La langue vit dans le contexte d'exécution, pas dans le prompt

Ce site est livré en cinq langues : anglais, allemand, français, espagnol et arabe. L'assistant doit répondre dans la langue du visiteur et respecter le registre, le Sie formel en allemand par exemple, et la lecture de droite à gauche pour l'arabe.

La mauvaise façon de faire est d'inscrire la langue en dur dans le prompt système et de reconstruire un prompt par langue. La bonne façon est le contexte d'exécution. Chaque requête porte la langue, résolue à partir d'une valeur explicite, d'un en-tête x-i18n-locale, ou de l'en-tête Accept-Language, et l'agent la lit au moment de la génération :

const runtimeContext = new RuntimeContext();
if (finalLocale) runtimeContext.set("locale", finalLocale);
runtimeContext.set("requestId", requestId);

Un agent, un jeu d'instructions, cinq langues. Le même identifiant de requête circule à travers les logs, donc une conversation unique peut être tracée de bout en bout.

Un état qui se dégrade au lieu de casser

Le stockage des conversations utilise LibSQL quand une URL de base de données est configurée, et bascule sur un store en mémoire quand elle ne l'est pas. L'import est paresseux et enveloppé dans un try et catch, donc une dépendance optionnelle manquante ne fait jamais tomber l'assistant. Il tourne simplement sans historique durable.

C'est un principe récurrent à travers le système : l'infrastructure optionnelle se dégrade vers une valeur par défaut sûre plutôt que de lever une exception. Une agrégation qui ne peut pas atteindre une source renvoie du vide. L'assistant qui ne peut pas atteindre une base de données continue de répondre. Rien de visible côté utilisateur ne dépend de la présence d'un service optionnel.

La couche de sécurité autour de chaque requête

Le modèle est la partie facile. La frontière de la requête, c'est là que les fonctionnalités IA en production se font blesser. Chaque appel à l'assistant passe par les mêmes barrières avant qu'un seul token ne soit généré :

1. Validation de la méthode et de l'entrée : POST uniquement, longueur d'entrée bornée, corps mal formés rejetés avec une erreur structurée et un identifiant de requête.
2. Rate limiting : des limites par requête, pour qu'un seul client ne puisse pas vider le budget d'inférence.
3. Vérification de l'origine et CSRF : les appels du navigateur doivent venir d'une origine autorisée et porter un token CSRF valide. Le token est posé en cookie et vérifié à chaque appel mutant.
4. Autorisation interne : les appels serveur à serveur depuis notre propre backend sautent les vérifications du navigateur via un chemin d'authentification interne explicite, jamais un contournement implicite.

Ces barrières ne sont pas spécifiques à l'IA. Ce sont les mêmes que celles dont tout endpoint sérieux a besoin. L'erreur que font les équipes est de traiter une route IA comme spéciale et de les sauter. Un endpoint LLM reste un endpoint, et il dépense de l'argent à chaque appel, ce qui fait du rate limit un contrôle des coûts autant qu'un contrôle de sécurité.

Aucune perte silencieuse de lead

Un lead que l'IA capture mais que le système laisse tomber est pire que pas d'IA du tout. Donc les leads sont journalisés dans le flux de logs avant que la livraison ne soit tentée, et les échecs de livraison sont loggés explicitement plutôt qu'avalés. Si un fournisseur d'email est en panne, le lead existe quand même dans l'enregistrement et peut être récupéré. Le chemin de capture et le chemin de livraison sont découplés à dessein, parce que la chose coûteuse à perdre est l'intention, pas l'email.

Le streaming, parce que la latence est une fonctionnalité

Les réponses streament token par token plutôt que de bloquer jusqu'à ce que la réponse complète soit prête. Sur une surface commerciale, la latence perçue est la différence entre un visiteur qui attend et un qui s'en va. Le streaming est géré dans un petit helper dédié, donc chaque route d'agent obtient le même comportement sans répéter la plomberie.

Ce que nous avons délibérément choisi de ne pas construire

Une bonne architecture, c'est aussi une liste de choses auxquelles tu as dit non.

• Pas d'assistant généraliste. L'agent de devis est cantonné aux seules affaires d'Oronts. Demande-lui d'écrire un FizzBuzz ou de compter les lettres d'un mot, et il refuse et redirige. Un assistant commercial qui répond à des quiz est un risque, pas une fonctionnalité, et un assistant ouvert est une surface d'attaque ouverte.
• Aucun chiffre inventé. L'assistant énonce mot pour mot les fourchettes de prix publiées et ne construit jamais d'estimation spécifique à un projet. Les fourchettes de planification viennent d'un ingénieur senior après cadrage, jamais d'un modèle qui veut se rendre utile.
• Aucune promesse. Il ne confirme jamais une faisabilité, n'engage jamais un calendrier, et ne garantit jamais un résultat. Il collecte de l'information et passe la main à des personnes.

Ces contraintes vivent dans les instructions et ce sont les lignes les plus importantes de tout le système. La capacité d'un modèle est bornée par les garde-fous qui l'entourent, et sur un site commercial, les garde-fous sont le produit.

Ce qu'il faut retenir pour ton propre build

Si tu mets une fonctionnalité IA en production, le choix du modèle est la décision que tu regretteras le moins. Investis ton effort sur la frontière : validation, rate limiting, langue, dégradation gracieuse, et un chemin de capture qui ne perd jamais l'intention. Des frameworks comme Mastra te donnent les primitives d'agent et de tool pour que tu puisses dépenser cet effort là où il paie.

Pour les patterns environnants, consulte nos guides sur l'architecture multi-agents, l'observabilité IA et l'IA avec humain dans la boucle. Si tu veux ce genre de système intégré à ton propre produit, démarre une conversation ou demande un devis.