Méthodologie de conception des Characters : Créer des agents IA qui fonctionnent vraiment

Claude & Jozo · 9 min read · 2026/02/12

Agents IAConception de CharactersDéveloppementMéthodologie

Méthodologie de conception des Characters : Créer des agents IA qui fonctionnent vraiment

La plupart des tutoriels sur les agents IA commencent par la configuration des outils. Connecter ce serveur MCP. Enregistrer cette skill. Configurer ces prompts.

Ensuite, les utilisateurs se demandent pourquoi leur agent « Directeur Marketing » envoie des e-mails via SendGrid un jour et via Mailgun le lendemain. Ou pourquoi l’« Analyste SEO » interroge parfois Google Analytics, parfois Search Console, et parfois invente simplement des métriques.

Les agents sont théoriquement capables. Ils ont des outils e-mail. Ils ont accès à l’analytique. Mais ils ne fonctionnent pas de manière fiable.

Voici ce que nous avons appris en construisant 14 Characters IA pour TeamDay : le problème n’est pas les outils. Le problème, c’est la méthodologie.

Le piège de l’abstraction

L’écosystème des agents IA adore les taxonomies. Outils vs. serveurs MCP vs. skills vs. plugins vs. prompts. Les développeurs passent des heures à débattre : l’e-mail devrait-il être un outil MCP ou une skill avec un script bash ?

Du point de vue de l’utilisateur métier, ces distinctions n’ont aucun sens.

Quand quelqu’un demande à son Directeur Marketing d’« envoyer le point hebdomadaire », peu lui importe que l’e-mail parte via :

Un outil MCP appelant l’API Resend
Une skill exécutant une commande bash curl
Un script TypeScript avec des identifiants issus des variables d’environnement
Du SMTP direct via sendmail

Ce qui compte : l’e-mail est-il envoyé ? Correctement. À chaque fois.

Retirez les abstractions et il reste exactement deux primitives :

1. Les fonctions exécutables — Code qui s’exécute et retourne un résultat (outils, outils MCP, commandes bash, scripts)

2. Le texte de prompt — Instructions que l’IA lit et suit (prompts système, skills, fichiers CLAUDE.md)

Tout le reste est du packaging et de la structure organisationnelle autour de ces deux primitives.

Le piège de l’abstraction survient quand on optimise pour la taxonomie (choisir entre les types d’outils) plutôt que pour la fiabilité (est-ce que ça fonctionne vraiment ?).

Le principe de l’exemple fonctionnel

Voici la véritable unité de capacité d’un agent IA :

Un exemple fonctionnel avec des identifiants.

Pas l’enregistrement d’un outil. Pas une configuration de serveur MCP. Pas une description de skill.

Un exemple fonctionnel ressemble à ceci :

# Envoyer un e-mail via Resend
curl -X POST https://api.resend.com/emails \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Point hebdomadaire",
    "html": "<p>Contenu ici</p>"
  }'

# Réponse attendue :
# {"id": "abc-123", "status": "sent"}

# Identifiants : RESEND_API_KEY dans .env
# Dernier test : 2026-02-10
# Responsable : Équipe Marketing

Sans exemple fonctionnel, Claude choisit arbitrairement parmi 1000 options. Avec un exemple fonctionnel, il suit le modèle éprouvé à chaque fois.

La différence entre « peut théoriquement envoyer des e-mails » et « envoie de manière fiable des e-mails via Resend avec nos identifiants » est un exemple fonctionnel testé et documenté.

Le modèle des recettes

Une recette est ce que nous appelons un exemple fonctionnel testé et éprouvé pour une tâche spécifique.

Notre Character Directeur Marketing possède ces recettes :

Envoyer un e-mail via Resend (testé, identifiants dans env)
Interroger l’API Search Console (testé, OAuth configuré)
Analyser des mots-clés via Ahrefs (testé, clé API dans env)
Récupérer les données Google Analytics (testé, ID de propriété documenté)

Chaque recette comprend :

Quand l’utiliser — « Pour envoyer des e-mails transactionnels »
Référence des identifiants — « Clé API : RESEND_API_KEY (dans .env) »
Exemple fonctionnel — Commande curl réelle ou extrait de code qui fonctionne
Réponse attendue — À quoi ressemble le succès
Dernier test — Date à laquelle nous avons vérifié que ça fonctionne réellement

Les recettes ne sont pas des définitions abstraites d’outils. Ce sont des procédures concrètes et testées dont nous savons qu’elles fonctionnent parce que nous les avons exécutées.

Les recettes sont les briques atomiques. Les Characters sont des compositions.

Conception de Characters bottom-up

Voici la méthodologie qui fonctionne vraiment :

Étape 1 : Qui est ce Character ?

Pas des capacités abstraites. Un rôle et un objectif spécifiques.

Mauvais : « Assistant IA avec des capacités marketing »

Bon : « Directeur Marketing qui envoie des rapports de performance hebdomadaires aux parties prenantes »

Plus le rôle est clair, plus la conception est facile.

Étape 2 : Quelles tâches ce rôle accomplit-il vraiment ?

Pas ce qu’il pourrait théoriquement faire. Ce qu’il fait littéralement le mardi matin.

Pour le Directeur Marketing :

Vérifier les performances des campagnes (le lundi à 9h)
Examiner les tendances du trafic organique (quotidiennement)
Envoyer le récapitulatif hebdomadaire aux parties prenantes (le vendredi à 16h)
Analyser les classements des mots-clés (sur demande)

Remarquez que ce sont des tâches, pas des outils. « Vérifier les performances des campagnes » est un travail à accomplir. Que cela utilise l’API Google Ads, Search Console, ou les deux, est un détail d’implémentation.

Étape 3 : Comment les humains réels accomplissent-ils ces tâches ?

C’est là qu’on devient précis sur le tech stack.

Pour « vérifier les performances des campagnes » :

La personne réelle se connecte à Google Analytics
Consulte les 7 derniers jours de trafic
Compare avec la période précédente
Note les changements significatifs

Traduction technique :

Interroger l’API Google Analytics
ID de propriété : 478766521
Métriques : sessions, pages vues, taux de rebond
Plage de dates : 7 derniers jours vs. 7 jours précédents
Identifiants OAuth nécessaires

Maintenant vous savez quelle recette construire.

Étape 4 : Notre tech stack le supporte-t-il ?

Peut-on accéder à ces API depuis notre environnement d’exécution ?

Vérifier :

Avons-nous les identifiants ? (Vérifier .env, vérifier la configuration OAuth)
Peut-on faire des appels API depuis le sandbox ? (Tester la commande curl)
Les packages requis sont-ils installés ? (Vérifier l’image Docker ou installer à la demande)

Si la réponse est non :

Ajouter la capacité à votre environnement d’exécution (installer des packages, configurer OAuth)
Utiliser une approche différente (serveur MCP pour les dépendances lourdes)
Ajuster le rôle du Character (reconnaître la limitation)

La réalité de l’environnement d’exécution contraint ce qui est possible. Si psql n’est pas installé dans le sandbox, aucune quantité de prompt engineering ne donnera à Claude un accès à la base de données.

Étape 5 : Écrire et tester les recettes

C’est l’étape critique que la plupart des gens sautent.

Ne pas écrire :

L'agent peut interroger Google Analytics via l'API.

Écrire :

# Interroger Google Analytics — Trafic des 7 derniers jours
curl -H "Authorization: Bearer $GA_ACCESS_TOKEN" \
  "https://analyticsdata.googleapis.com/v1beta/properties/478766521:runReport" \
  -d '{
    "dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
    "metrics": [{"name": "sessions"}]
  }'

# Dernier test : 2026-02-10 (fonctionnel)
# Responsable : Équipe Marketing
# Identifiants : GA_ACCESS_TOKEN depuis OAuth (expire dans 1h)

Puis l’exécuter vraiment. Vérifier que ça fonctionne. Corriger ce qui ne marche pas. Documenter la version fonctionnelle.

La recette n’est réelle que quand elle est testée.

Étape 6 : Composer le Character

Vous avez maintenant :

Un rôle clair (Directeur Marketing)
Des tâches spécifiques (mises à jour hebdomadaires, analyse du trafic)
Des recettes testées (Search Console, Analytics, Resend)

Le Character est la composition :

# Character : Directeur Marketing

## Rôle
Vous êtes le Directeur Marketing de TeamDay. Vous suivez les performances,
analysez les tendances et communiquez les insights aux parties prenantes.

## Responsabilités clés
- Envoyer des rapports de performance hebdomadaires (vendredi à 16h)
- Surveiller le trafic organique quotidiennement
- Analyser les classements des mots-clés sur demande

## Recettes disponibles

### Envoyer un e-mail via Resend
Quand : Pour envoyer des mises à jour aux parties prenantes
Recette : /recipes/send-email-resend.md

### Interroger Search Console
Quand : Pour analyser le trafic organique ou les mots-clés
Recette : /recipes/search-console-query.md

### Récupérer Google Analytics
Quand : Pour vérifier les tendances globales du trafic
Recette : /recipes/google-analytics-query.md

## Style de communication
- Direct, sans jargon d'entreprise
- Commencer par les chiffres (« +15 % de trafic vs. la semaine dernière »)
- Expliquer ce qui a changé et pourquoi c'est important

Le Character fait référence aux recettes. Les recettes contiennent des exemples fonctionnels.

C’est ainsi qu’on construit des Characters qui fonctionnent vraiment.

Réutilisabilité grâce au chevauchement du tech stack

C’est là que le modèle de recettes porte ses fruits.

Le Directeur Marketing a besoin d’accéder à Search Console. L’Analyste SEO a besoin d’accéder à Search Console. La même recette.

Le Représentant Commercial doit envoyer des e-mails. Le Directeur Marketing doit envoyer des e-mails. La même recette.

Les recettes deviennent naturellement une bibliothèque :

/recipes/
├── send-email-resend.md
├── search-console-query.md
├── google-analytics-query.md
├── ahrefs-keyword-analysis.md
├── postgres-query.md
└── notion-page-create.md

Chaque nouveau Character ajoute peut-être 1–2 nouvelles recettes. La plupart sont réutilisées.

Mais cela ne fonctionne que si les recettes sont des exemples fonctionnels testés. Si ce sont des définitions abstraites d’outils, la réutilisabilité n’a pas d’importance car elles ne fonctionnent de toute façon pas de manière fiable.

La porte de qualité

Les capacités d’un Character ne sont réelles qu’à la mesure de ses recettes testées.

Questions à se poser :

Pas : « Ce Character a-t-il l’e-mail configuré ? »

Demandez : « Avons-nous vérifié que la recette e-mail envoie réellement un e-mail ? »

Pas : « Ce Character peut-il accéder à notre base de données ? »

Demandez : « Avons-nous testé la recette de requête de base de données avec de vraies identifiants ? »

La différence entre les Characters qui sont des façades et ceux qui livrent ce sont les recettes testées.

Nous l’avons appris à nos dépens. Nous avons construit des Characters pour la page /team de notre site marketing. Ça avait fière allure. 14 employés IA à recruter. Des descriptions professionnelles. Des capacités impressionnantes.

Puis nous avons essayé de les utiliser pour du vrai travail. La plupart ne fonctionnaient pas de bout en bout. Des dépendances manquantes. Des recettes non testées. Des capacités abstraites sans exemples fonctionnels.

La porte de qualité : si nous ne l’avons pas testé, nous ne le livrons pas.

Réalité de l’environnement d’exécution : ce qui est vraiment possible

L’environnement sandbox contraint ce qui est possible. Comprendre ces contraintes façonne une meilleure conception des Characters.

Ce qui fonctionne partout

API HTTP via curl :

curl -H "Authorization: Bearer $API_KEY" https://api.example.com/endpoint

Chaque sandbox a curl. Si vous pouvez atteindre une API via HTTP, vous pouvez l’intégrer.

Scripts bash :

#!/bin/bash
# Toute logique que vous pouvez scripter fonctionne dans le sandbox

Outils CLI courants :

git, grep, sed, awk, jq, node, python

Ce qui nécessite une configuration

Clients de base de données :

psql ou mysql doit être installé
Option 1 : Pré-installer dans l’image Docker
Option 2 : Wrapper HTTP API (pg-gateway)
Option 3 : Serveur MCP pour les requêtes complexes

Packages lourds (Puppeteer, Playwright) :

Arbres de dépendances volumineux
Dépendances binaires (Chrome)
Option 1 : Pré-installer dans l’image de base (si fréquemment utilisé)
Option 2 : Serveur MCP (isolé, géré séparément)

Flux OAuth :

Authentification interactive
Logique de rafraîchissement des tokens
Option 1 : Préconfigurer les tokens (variables d’environnement)
Option 2 : Le serveur MCP gère l’authentification

Arbre de décision pratique

Peut-on le faire avec curl ? → Écrire la recette, tester, terminé
Besoin d’un package < 50 Mo ? → Installer dans l’image Docker
Besoin de dépendances lourdes ? → Serveur MCP (en dernier recours)
Besoin d’une authentification interactive ? → Serveur MCP ou tokens préconfigurés

Plus les exigences d’exécution sont simples, plus le Character est fiable.

La différence avec la façon dont la plupart des gens construisent

Top-down (approche courante) :

Choisir un framework d’agents IA
Configurer des serveurs MCP
Ajouter des skills et des outils
Écrire le prompt système
Espérer que ça fonctionne

Problèmes :

Outils configurés mais non testés
Pas d’exemples fonctionnels, seulement des capacités abstraites
Le Character peut théoriquement tout faire, ne fait de manière fiable rien
La première utilisation réelle révèle que ça ne fonctionne pas vraiment

Bottom-up (notre approche) :

Définir un rôle et des tâches spécifiques
Cartographier les tâches sur de vrais workflows humains
Tester et vérifier chaque workflow (écrire des recettes)
Composer le Character à partir de recettes testées
Porte de qualité : chaque capacité est vérifiée

Résultat :

Chaque recette est testée et connue pour fonctionner
Les capacités du Character correspondent à la réalité testée
La première utilisation fonctionne parce que les recettes ont été vérifiées
Quand quelque chose casse, on sait quelle recette corriger

La méthodologie inverse le processus : partir de workflows vérifiés, composer vers le haut jusqu’aux Characters — non pas configurer des outils par le haut en espérant que ça marche.

Exemple réel : Directeur Marketing

Voici le processus de conception réel pour l’un de nos Characters.

Étape 1 : Définition du rôle

Qui : Directeur Marketing de TeamDay Objectif : Surveiller les performances marketing et communiquer les insights

Étape 2 : Tâches réelles

Après observation du vrai travail marketing :

Vérifier Google Analytics pour les tendances de trafic (quotidiennement)
Surveiller Search Console pour les classements de mots-clés organiques (hebdomadairement)
Envoyer des rapports de performance aux parties prenantes (hebdomadairement)
Analyser des campagnes spécifiques sur demande

Étape 3 : Vrai workflow humain

Pour « envoyer le récapitulatif hebdomadaire » :

La personne se connecte à Google Analytics
Consulte les 7 derniers jours : sessions, pages vues, top pages
Compare avec la semaine précédente
Note les changements significatifs
Vérifie Search Console pour les top requêtes
Rédige un e-mail avec les résultats
Envoie via Gmail

Étape 4 : Vérification du tech stack

Google Analytics :

✅ Accès API disponible
✅ ID de propriété : 478766521
✅ OAuth configuré
✅ Interrogeable via curl

Search Console :

✅ Accès API disponible
✅ Site : teamday.ai
✅ OAuth configuré
✅ Interrogeable via curl

E-mail :

✅ Utilisation de Resend (pas Gmail)
✅ Clé API dans env : RESEND_API_KEY
✅ Envoyable via curl

Étape 5 : Écrire les recettes

Recette 1 : Google Analytics — 7 derniers jours

#!/bin/bash
# Récupérer le trafic des 7 derniers jours depuis Google Analytics

curl -H "Authorization: Bearer $GA_ACCESS_TOKEN" \
  "https://analyticsdata.googleapis.com/v1beta/properties/478766521:runReport" \
  -d '{
    "dateRanges": [
      {"startDate": "7daysAgo", "endDate": "today"},
      {"startDate": "14daysAgo", "endDate": "8daysAgo"}
    ],
    "metrics": [
      {"name": "sessions"},
      {"name": "totalUsers"},
      {"name": "screenPageViews"}
    ],
    "dimensions": [{"name": "pagePath"}]
  }'

# Résultat du test (2026-02-10) :
# {
#   "rows": [
#     {"dimensionValues": [{"value": "/"}],
#      "metricValues": [{"value": "1243"}, {"value": "892"}, ...]}
#   ]
# }

# Identifiants : GA_ACCESS_TOKEN (OAuth, expire dans 1h)

Testé : ✅ Fonctionne Dernière vérification : 10/02/2026

Recette 2 : Envoyer un e-mail via Resend

#!/bin/bash
# Envoyer un e-mail via l'API Resend

TO="$1"
SUBJECT="$2"
BODY="$3"

curl -X POST https://api.resend.com/emails \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"from\": \"[email protected]\",
    \"to\": \"$TO\",
    \"subject\": \"$SUBJECT\",
    \"html\": \"$BODY\"
  }"

# Résultat du test (2026-02-10) :
# {"id": "abc-123", "status": "sent"}

# Identifiants : RESEND_API_KEY dans .env

Testé : ✅ Fonctionne Dernière vérification : 10/02/2026

Étape 6 : Composer le Character

# Directeur Marketing

Vous êtes le Directeur Marketing de TeamDay. Vous surveillez les performances
et communiquez les insights.

## Tâche de récapitulatif hebdomadaire

Chaque vendredi à 16h :

1. Interroger Google Analytics (7 derniers jours vs. précédents)
   Recette : /recipes/google-analytics-7day.sh

2. Interroger Search Console (top requêtes organiques)
   Recette : /recipes/search-console-top-queries.sh

3. Rédiger l'e-mail :
   - Objet : « TeamDay Marketing Update — Semaine du [date] »
   - Format :
     **Trafic :** [sessions] ([+/-]% vs. semaine dernière)
     **Top pages :** [liste top 3]
     **Top requêtes :** [liste top 3]
     **Changements notables :** [tout ce qui dépasse >20 % de variation]

4. Envoyer via Resend
   Recette : /recipes/send-email-resend.sh
   À : jozo at teamday.ai

Résultat : Un Character qui envoie de manière fiable des mises à jour hebdomadaires parce que chaque étape est une recette testée.

Ce que nous avons appris à nos dépens

1. « Testé » signifie vraiment testé

Nous avons documenté des recettes. Elles semblaient bonnes. Nous avons livré les Characters.

Puis nous avons essayé de les utiliser. La moitié des recettes n’avait jamais été exécutée. Les endpoints API avaient changé. Les identifiants étaient incorrects. Les ID de propriété étaient obsolètes.

La solution : Tester chaque recette. L’exécuter vraiment. Vérifier la réponse. Mettre à jour quand les API changent.

2. Les recettes se dégradent

Les API changent. Les identifiants expirent. Les services sont abandonnés.

La solution : Dater chaque recette. Quand un Character échoue, vérifier les dates des recettes. Retester et mettre à jour.

3. Les lacunes d’exécution sont réelles

Nous avons conçu un Character Analyste SQL qui interroge notre base de données. Puis découvert que psql n’était pas installé dans le sandbox.

La solution : Tester les capacités de l’environnement d’exécution avant de concevoir les Characters. Si psql n’est pas là, soit l’installer, soit utiliser un wrapper HTTP API.

4. La composition bat la configuration

Nous avons passé des semaines à configurer des serveurs MCP pour diverses capacités. Configuration complexe. Beaucoup de pièces mobiles.

Puis nous avons écrit de simples scripts bash avec des commandes curl. Ils ont fonctionné immédiatement.

L’enseignement : Commencer simple. Les scripts bash avec curl couvrent 80 % du chemin. N’ajouter de la complexité que lorsque le simple ne suffit pas.

L’insight méta

Toute cette méthodologie est née de la construction de Characters IA devant vraiment fonctionner — pas seulement être impressionnants en démo.

Quand on construit pour les démos :

Les capacités abstraites conviennent
« Peut envoyer des e-mails » suffit
Les captures d’écran de configuration paraissent impressionnantes

Quand on construit pour la production :

Les recettes testées sont indispensables
« Envoie de manière fiable des e-mails via Resend avec nos identifiants » est la barre
Les exemples fonctionnels comptent plus que la complexité de configuration

La différence méthodologique : les démos optimisent pour la largeur des capacités, la production optimise pour la profondeur de la fiabilité.

Nous construisons des équipes IA où les Characters font un vrai travail. Cela nous a forcés à résoudre le problème de fiabilité.

La méthodologie bottom-up centrée sur les recettes en est le résultat.

Essayez vous-même

Pour créer un Character qui fonctionne vraiment :

Définir un rôle spécifique Non : « IA Marketing » Oui : « Directeur Marketing qui envoie des mises à jour hebdomadaires »
Lister 3 tâches réelles Non : « Analyser les données marketing » Oui : « Vérifier le trafic des 7 derniers jours dans Google Analytics »
Écrire un exemple fonctionnel Ne pas documenter les outils. Écrire une commande curl qui fonctionne. La tester. Vérifier la réponse.
Créer un fichier de recette Sauvegarder l’exemple fonctionnel sous /recipes/nom-tache.md Inclure : quand utiliser, identifiants, code fonctionnel, date du dernier test
Référencer depuis le Character Le prompt système fait référence au fichier de recette Le Character sait quand l’utiliser et comment l’invoquer
Tester de bout en bout Utiliser vraiment le Character pour la tâche Corriger ce qui ne fonctionne pas Mettre à jour la recette

Commencer avec une tâche, une recette, un Character.

Une fois que vous en avez construit un qui fonctionne de manière fiable, la méthodologie prend tout son sens. Puis passer à davantage de recettes et de Characters.

Sur notre page /team, nous avons 14 Characters IA. Ils ont l’air professionnels. Des capacités impressionnantes. Mais nous avons appris : paraître capable et l’être réellement sont deux choses différentes.

Ceux qui fonctionnent vraiment ont des recettes testées. Ceux qui sont des façades ont des définitions abstraites d’outils.

La méthodologie n’est pas compliquée : bottom-up à partir d’exemples fonctionnels, composer vers des Characters, tester de bout en bout.

Mais elle inverse la façon dont la plupart des gens construisent des agents IA. Et c’est cette inversion qui rend les Characters fiables.

Construire à partir de recettes. Tout tester. Livrer ce qui fonctionne.