Créer des Agents dans Medusa

Cette compétence couvre l'intégralité de la pile pour ajouter un agent IA interne orienté admin à un projet Medusa. Ces agents sont utilisés par les marchands et opérateurs de magasin via le tableau de bord admin Medusa — pas par les clients sur une vitrine. Pour les agents orientés client (par ex. un chatbot de vitrine), une architecture différente est nécessaire : routes API publiques, pas de MedusaExec, et authentification de vitrine.

Contraintes

• Utilisation interne uniquement — cette architecture est réservée aux utilisateurs admin (marchands, opérateurs, personnel support), pas aux clients. Les routes se trouvent sous src/api/admin/, l'interface dans le tableau de bord admin Medusa, et l'accès est protégé par l'authentification admin partout.
• L'authentification est non-négociable — MedusaExec exécute du TypeScript arbitraire avec accès complet à la base de données. Toutes les routes d'agent doivent utiliser AuthenticatedMedusaRequest et se situer sous src/api/admin/. Un endpoint non authentifié est une vulnérabilité d'exécution de code à distance.
• Utilise MedusaExec, pas d'outils personnalisés — pour toute opération de données, l'agent écrit du TypeScript et l'exécute via MedusaExec. Construis un outil personnalisé seulement pour des capacités qui ne peuvent pas être exprimées en TypeScript exécutable (par ex. appeler une API externe avec une clé secrète).
• Un module partagé, plusieurs agents — AgentSession et AgentMessage sont une infrastructure partagée. Utilise agent_type pour distinguer les sessions par agent. Ne crée jamais de modèles séparés par agent.
• Passe MedusaContainer via experimental_context — ne réimporte jamais les services directement dans les fichiers d'outils ; cela cause des dépendances circulaires.
• Le format de streaming est NDJSON — Content-Type: application/x-ndjson, un objet JSON par ligne suivi de \n.
• Lance les migrations après avoir ajouté ou modifié des modèles (npx medusa db:generate agent && npx medusa db:migrate).
• Les descriptions des outils se trouvent dans la config, pas en ligne dans tool() — l'objet config les remplace à l'exécution.

CRITIQUE : Charger les Fichiers de Référence Quand Nécessaire

⚠️ La référence rapide ci-dessous NE SUFFIT PAS pour l'implémentation. Charge le fichier de référence pertinent avant d'écrire du code.

Exigence minimale : Charge au moins le fichier de référence correspondant à ta tâche actuelle avant d'écrire du code.

Compétences Connexes

Charge celles-ci avec cette compétence quand pertinent :

• building-with-medusa — Modèles de module Medusa, workflows, conventions de modèles de données. Charge quand tu implémentes le service du module ou une logique backend personnalisée.
• building-admin-dashboard-customizations — Modèles de composants interface admin, TanStack Query, enregistrement de routes. Charge quand tu construis ou étends l'interface chat admin.

Vue d'Ensemble de l'Architecture

src/modules/agent/
  index.ts                ← Module() export + constante AGENT_MODULE
  service.ts              ← MedusaService + client Anthropic + stream(messages, container, config)
  models/
    session.ts            ← AgentSession (partagé sur tous les agents, filtré par agent_type)
    message.ts            ← AgentMessage
  agents/index.ts         ← orchestration streamText()
  tools/
    medusa-exec.ts        ← outil MedusaExec (outil principal pour toutes opérations de données)
    todo-write.ts         ← outil TodoWrite
  config/
    <agent-type>.ts       ← par agent : prompt système + descriptions des outils

src/api/admin/agent/<agent-type>/
  route.ts                ← POST (AuthenticatedMedusaRequest, cycle de vie session, stream NDJSON)
  sessions/route.ts       ← GET liste sessions (filtré par agent_type)
  sessions/[id]/route.ts  ← GET messages pour une session

src/admin/routes/<agent-type>/
  page.tsx                ← Interface chat React (extension admin)

src/lib/code-mode/
  executor.ts             ← exécuteur TypeScript sandboxé utilisé par MedusaExec

Erreurs Courantes

Vérifie que tu NE FAIS PAS ceci :

Sécurité :

• [ ] Route d'agent utilise MedusaRequest au lieu de AuthenticatedMedusaRequest
• [ ] Route d'agent placée en dehors de src/api/admin/

Architecture :

• [ ] Créer des modèles AgentSession/AgentMessage séparés par agent au lieu d'utiliser agent_type
• [ ] Importer les services directement dans les fichiers d'outils au lieu de les résoudre depuis experimental_context
• [ ] Construire un outil personnalisé pour une opération de données au lieu d'utiliser MedusaExec

Streaming :

• [ ] Manquant res.end() après la boucle de streaming (réponse ne ferme jamais)
• [ ] Manquant Transfer-Encoding: chunked ou Content-Type: application/x-ndjson headers
• [ ] Ne pas mettre en buffer les lignes incomplètes côté client (erreurs parse JSON sur paquets scindés)

Module :

• [ ] Oublier d'enregistrer le module dans medusa-config.ts
• [ ] Oublier de lancer les migrations après avoir modifié les modèles
• [ ] Coder en dur les descriptions des outils dans tool() au lieu de l'objet config

Fichiers de Référence Disponibles

reference/data-models.md       - model.define(), discriminateur agent_type, relations, migrations
reference/service.md           - extension MedusaService, init Anthropic, stream(), index module, enregistrement config
reference/agent-setup.md       - streamText(), câblage outil MedusaExec, prompt système, passage contexte
reference/api-route.md         - route POST, cycle de vie session, persistance messages, headers streaming
reference/streaming.md         - émission NDJSON, itération fullStream, types chunk, parsing côté client
reference/admin-extension.md   - interface chat React, fetch streaming, rendu messages, affichage appels outils, sidebar sessions
reference/medusa-exec.md       - configuration Executor, outil MedusaExec, motifs query.graph(), codes erreurs

Tests

Une fois l'agent implémenté, teste-le de bout en bout directement dans le tableau de bord admin :

1. Démarrer le serveur Medusa dev (npx medusa develop)
2. Ouvre le tableau de bord admin et navigue vers la page de l'agent dans la barre latérale (le libellé défini dans defineRouteConfig)
3. Tape un prompt simple en lecture seule — par ex. « Combien de produits y a-t-il dans le magasin ? » — et envoie
4. Vérifie que la réponse se streaming et une nouvelle session apparaît dans la barre latérale
5. Envoie un message de suivi dans la même session pour confirmer que l'historique de conversation est préservé
6. Recharge la page, sélectionne la session depuis la barre latérale, et confirme que l'historique des messages est restauré depuis la base de données

Si quelque chose ne fonctionne pas, vérifie :

• Onglet réseau du navigateur — la requête POST doit retourner Content-Type: application/x-ndjson avec des lignes chunked
• Logs du serveur — les lignes [agent] tool_call et [agent] step_finish confirment que l'agent fonctionne
• Base de données — les tables agent_session et agent_message doivent avoir des lignes avec le correct agent_type