Constructeur d'agents IA

Cette page est le guide canonique pour construire des agents LLM avec l'AI Agent Builder de DevUtilities. Utilisez le flux guidé ci-dessus pendant la lecture, ou sautez à un sujet ci-dessous. Schemas, JSON MCP, prompts et comptages de jetons restent dans votre navigateur — rien n'est envoyé pour l'inférence.

AI Agent Builder est un atelier côté client pour assembler des configs d'agents prêtes pour la production : outils JSON Schema pour le function calling OpenAI, validation mcpServers pour Cursor et Claude Desktop, system prompts, budgets de jetons combinés et artefacts exportables pour le transfert d'équipe.

Ce que vous obtenez

• Quatre modes de flux : agent complet, function calling seul, configuration MCP, réponse structurée
• Modèles de démarrage : Filesystem MCP, OpenAI function calling, classifieur structuré
• Inférence exemple-JSON → JSON Schema avec additionalProperties: false strict optionnel
• Lint MCP local avec erreurs et avertissements par JSON-pointer
• Budget de jetons combiné entre prompt, tools minifiées et JSON MCP
• Exports : OpenAI tools JSON, response_format, config MCP, résumé markdown, bundle complet

Utilisez ce builder lorsque

• Vous avez besoin d'OpenAI tools JSON et ne voulez pas écrire le JSON Schema à la main
• Vous branchez des serveurs MCP Cursor ou Claude Desktop et voulez un lint avant de coller
• Vous devez prouver que le prompt + tools d'un agent tiennent encore dans une fenêtre de contexte
• Vous voulez une session persistée qui enchaîne schema → MCP → prompt → export

Préférez un outil autonome lorsque

• Vous n'avez besoin que d'une comparaison d'encoding approfondie ou d'un calcul de coût → LLM Token Counter
• Vous n'avez besoin que d'un lint MCP ponctuel sans prompts → MCP Validator
• Vous n'avez besoin que d'une inférence de schéma depuis un échantillon → Structured Output Generator

Choisissez un mode avant de définir les tools. Les modes masquent les étapes inutiles pour éviter de lutter contre des panneaux vides.

Parcours initial pour un agent complet. Les raccourcis de modèle sautent plusieurs de ces étapes.

1. Choisissez Agent complet (ou chargez le modèle OpenAI function calling).
2. Dans Définir les tools, ajoutez chaque tool avec un nom clair, une description et un JSON d'arguments d'exemple représentatif.
3. Examinez le JSON Schema inféré — activez le mode strict pour les structured outputs / strict tool calling OpenAI.
4. Collez ou éditez le JSON mcpServers si l'agent tournera dans Cursor ou Claude Desktop ; corrigez chaque erreur avant de continuer.
5. Rédigez des system instructions qui indiquent au modèle quand appeler quel tool et ce qu'il ne doit jamais inventer.
6. Ouvrez Budget de jetons, choisissez cl100k_base ou o200k_base, et confirmez que le total combiné tient dans votre modèle.
7. Exportez OpenAI tools JSON pour l'API, la config MCP pour le client bureau, et un résumé markdown pour l'équipe.
8. Exportez éventuellement le bundle JSON complet pour qu'un autre ingénieur puisse recharger le même état de session plus tard.

Problème : vous avez besoin d'un agent support client qui consulte météo et commandes via OpenAI function calling, mais le JSON Schema écrit à la main échoue encore à la validation stricte.

Comment cet outil le résout

1. Sélectionnez le mode Function calling ou chargez le modèle OpenAI function calling (météo + recherche de commande).
2. Éditez le JSON d'exemple pour que chaque champ nécessaire en production apparaisse au moins une fois — les clés manquantes ne deviennent pas des propriétés required.
3. Activez le mode strict pour que chaque objet émette additionalProperties: false.
4. Serrez le system prompt : confirmez les IDs de commande, n'inventez jamais de résultats de tools, gardez des réponses concises.
5. Vérifiez le budget de jetons sous o200k_base si vous déployez sur GPT-4o.
6. Exportez OpenAI tools JSON et collez-le dans votre client Chat Completions ou Responses API.

Résultat : un tableau tools strict prêt pour l'API plus un prompt aligné sur les schemas — sans éditeur de schéma séparé.

Problème : Cursor ou Claude Desktop rejette votre mcp.json, ou le serveur filesystem démarre avec le mauvais répertoire et voit trop du disque.

Comment cet outil le résout

1. Choisissez le mode Configuration MCP ou chargez le modèle Filesystem MCP.
2. Remplacez /path/to/allowed/dir par un chemin absolu vers le seul répertoire que l'agent peut toucher.
3. Lancez la validation — corrigez command/args manquants, URLs invalides et valeurs env non string.
4. Utilisez des valeurs env placeholder (pas de secrets de production) pendant le lint dans le navigateur.
5. Exportez le JSON mcpServers validé dans votre config Cursor ou Claude Desktop.
6. Ajoutez des system instructions qui exigent une confirmation avant les opérations fichiers destructives.

Résultat : une config client MCP lintée et un prompt aligné sur les capacités du serveur avant de redémarrer l'app bureau.

Problème : vous avez besoin que le modèle renvoie sentiment, confiance, sujets et un court résumé en JSON — les réponses en prose cassent votre parser downstream.

Comment cet outil le résout

1. Choisissez le mode Réponse structurée ou chargez le modèle classifieur structuré.
2. Éditez le JSON d'exemple pour correspondre à la forme exacte attendue par votre pipeline.
3. Activez le mode strict pour que les clés non déclarées soient rejetées à la validation.
4. Rédigez un system prompt qui interdit la prose hors de l'objet JSON.
5. Exportez response_format json_schema pour les structured outputs OpenAI.
6. Vérifiez que le budget de jetons laisse encore de la place pour le document d'entrée à classer.

Résultat : un schéma de sortie unique à brancher dans les APIs structured-output avec des instructions correspondantes.

Problème : après avoir ajouté trois tools et une longue config MCP, le prompt combiné de l'agent ne tient plus dans le budget pratique de GPT-4o une fois l'historique de chat inclus.

Comment cet outil le résout

1. Ouvrez l'étape Budget de jetons et notez le total combiné prompt + tools minifiées + JSON MCP.
2. Raccourcissez les descriptions de tools et retirez les champs d'exemple inutilisés qui gonflent les schemas required.
3. Déplacez le texte de politique verbeux hors du system prompt toujours actif vers une récupération à la demande.
4. Si vous n'avez besoin que d'une math d'encoding plus profonde, copiez le payload assemblé dans LLM Token Counter.
5. Réexportez seulement quand le budget montre une marge confortable pour l'historique et les completions.

Résultat : vous détectez le dépassement dans le builder — pas après la première erreur 400 en production.

Le JSON d'exemple doit être du JSON strict. Seules les clés présentes dans l'exemple deviennent des propriétés required. Les objets et tableaux imbriqués infèrent les types depuis les valeurs d'échantillon.

Règles empiriques

• Incluez chaque champ que le modèle doit pouvoir envoyer — l'omission signifie « non required », pas « optionnel avec un default ».
• Utilisez des enums réalistes comme échantillons string, puis éditez le schéma à la main si vous avez besoin d'un tableau enum explicite.
• Activez le mode strict pour émettre additionalProperties: false sur chaque objet — recommandé pour structured outputs et strict tool calling OpenAI.
• Les tableaux vides infèrent des types d'éléments faibles — ajoutez au moins un élément représentatif.

Les serveurs stdio ont besoin de command et généralement d'args. Les serveurs distants ont besoin d'une url http ou https valide. Les valeurs env doivent être des strings. Les erreurs bloquent la confiance d'export ; les avertissements méritent une passe manuelle.

Enveloppes client courantes

• La clé de premier niveau doit être "mcpServers" selon les conventions Cursor et Claude Desktop
• Les serveurs filesystem doivent utiliser des chemins absolus en allow-list
• Préférez des placeholders env pendant l'édition dans le navigateur ; injectez les vrais secrets uniquement sur la machine locale

Les comptages de jetons combinent system prompt, schemas d'outils minifiés et JSON MCP. Choisissez cl100k_base pour une approximation GPT-4 / Claude ou o200k_base pour GPT-4o. Les comptages utilisent des tables tiktoken locales — aucun appel API.

• Traitez le nombre comme un plancher : l'historique de chat et les résultats de tools en ajoutent davantage à l'exécution
• Revérifiez après chaque édition de schéma ou de prompt
• Utilisez LLM Token Counter quand vous avez besoin de cartes de frontières ou de coûts mensuels sur un payload personnalisé

Symptômes : OpenAI rejette le payload tools, ou le modèle ne peut pas passer des arguments dont votre app a réellement besoin.

Pourquoi cela arrive

Les schémas stricts rejettent les clés non déclarées. Si le JSON d'exemple a omis un champ, il n'est jamais devenu une propriété. Si le mode strict est désactivé, les limites structured-output d'OpenAI peuvent encore rejeter les objets ouverts.

Diagnostiquer

Comparez les properties du schéma inféré aux arguments envoyés par votre application. Vérifiez que le mode strict est activé pour cibler les structured outputs OpenAI.

Correctifs

1. Ajoutez les clés manquantes au JSON d'exemple et régénérez le schéma.
2. Activez le mode strict pour que additionalProperties: false soit cohérent sur les objets imbriqués.
3. Raccourcissez les constructions non supportées (oneOf très imbriqués, types exotiques) selon les limites structured output d'OpenAI.
4. Réexportez tools JSON et retestez avec un payload d'arguments connu et valide.

Symptômes : erreurs de validation sur command/url, le client n'arrive pas à démarrer le serveur, ou le transport distant ne se connecte jamais.

Pourquoi cela arrive

Entrées stdio sans command, entrées distantes sans URLs http(s), valeurs env numériques ou mauvaises clés de premier niveau cassent les parsers clients.

Diagnostiquer

Lisez le JSON pointer de chaque erreur de lint. Confirmez que l'enveloppe utilise mcpServers et que chaque serveur est soit stdio (command) soit distant (url), pas un hybride cassé.

Correctifs

1. Ajoutez command et args pour les serveurs stdio ; citez toutes les valeurs env comme strings.
2. Utilisez des URLs http:// ou https:// pour les transports MCP distants.
3. Corrigez le nom de la clé de premier niveau en mcpServers.
4. Relancez la validation jusqu'à disparition des erreurs ; triez les avertissements avant de livrer.

Symptômes : des API keys apparaissent dans le JSON exporté, les diffs git ou des captures du builder.

Pourquoi cela arrive

Les blocs env MCP sont du JSON brut. Coller des secrets de production dans un outil navigateur — même local — augmente le risque de fuite via presse-papiers, partage d'écran et commits accidentels.

Diagnostiquer

Cherchez dans les exports et le panneau MCP les motifs sk-, Bearer ou clés fournisseur. Vérifiez que les configs versionnées ne contiennent que des placeholders.

Correctifs

1. Remplacez les secrets par des placeholders style ${ENV_VAR} dans le builder.
2. Injectez les vraies valeurs uniquement dans le client bureau local ou le magasin de secrets du déploiement.
3. Faites tourner toute clé collée dans un chat, un ticket ou un écran partagé.
4. Ajoutez un scan de secrets pre-commit pour mcp.json et les fichiers de bundle d'agent.

Cet espace de travail n'envoie pas votre config — mais le presse-papiers et git le peuvent encore.

• Ne committez jamais d'API keys dans les blocs env MCP — utilisez des placeholders de variables d'environnement
• Utilisez des chemins absolus au moindre privilège pour les serveurs MCP filesystem
• Revoyez le budget de jetons avant d'ajouter de grands exemples few-shot aux prompts de production
• Préférez des schémas stricts pour que les tools n'acceptent pas de clés inattendues
• Traitez les bundles exportés comme sensibles s'ils contiennent des noms de tools internes ou des hôtes d'infra

• Partez d'un modèle, puis supprimez les tools inutiles — des schémas plus petits sont moins chers et plus sûrs
• Nommez les tools avec des verbes clairs (lookup_order, get_weather) alignés sur les instructions du system prompt
• Gardez une seule source de vérité : exportez depuis ce builder au lieu de maintenir des copies de schéma divergentes
• Revalidez MCP après chaque changement de chemin ou de command
• Documentez le budget de jetons dans l'export markdown pour que les relecteurs voient l'impact coût dans les PRs
• Utilisez LLM Token Counter pour les diffs d'encoding approfondis ; utilisez ce builder pour l'agent assemblé