# Développer avec des agents IA Chaque page est aussi servie en Markdown. Les fichiers ci-dessous donnent à un agent de code les mêmes faits que ces pages vous donnent. ## Ce qui est là pour les machines[​](#ce-qui-est-là-pour-les-machines "Lien direct vers Ce qui est là pour les machines") | Ressource | URL | Usage | | -------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Index | `https://dzbuild.dev/llms.txt` | La liste des pages, une ligne chacune. Collez-la dans un chat ou pointez un agent dessus. | | Site entier | `https://dzbuild.dev/llms-full.txt` | Toutes les pages dans un seul fichier Markdown. | | Une page en Markdown | l'URL de la page suivie de `.md`, par exemple `https://dzbuild.dev/fr/oauth.md` | Une page sans navigation. Les pages arabes et anglaises fonctionnent de la même façon sous `/ar/` et à la racine. | | Compétence agent | `https://dzbuild.dev/skills/dzbuild-apps/SKILL.md` | Les faits et les règles dont un agent a besoin pour construire une application DZBuild. | | Modèle AGENTS.md | `https://dzbuild.dev/agents/AGENTS.md` | Un fichier de départ pour le dépôt de votre application. | | Description OpenAPI | `https://dzbuild.dev/openapi/dzbuild-apps-v1.json` | Chaque opération qu'un jeton d'installation peut appeler, avec ses paramètres, ses scopes et la forme de ses réponses. | | Application exemple | [dzbuild-app-starter](https://github.com/DZBuild-com/dzbuild-app-starter) | Trois presets Cloudflare Worker et un exemple Node.js, chacun avec ses tests. | Chaque page HTML porte aussi `` vers son jumeau Markdown, pour qu'un outil qui lit la page trouve seul la version brute. ## Donnez la compétence à votre agent[​](#donnez-la-compétence-à-votre-agent "Lien direct vers Donnez la compétence à votre agent") Le fichier de compétence suit le format Agent Skills : une courte description qui dit à l'agent quand l'utiliser, puis les instructions. Claude Code lit les compétences dans `.claude/skills/` de votre projet ou dans `~/.claude/skills/` sur votre machine : ``` mkdir -p .claude/skills/dzbuild-apps curl -sSf https://dzbuild.dev/skills/dzbuild-apps/SKILL.md -o .claude/skills/dzbuild-apps/SKILL.md ``` Pour les agents qui lisent un `AGENTS.md` à la racine du dépôt (Codex, Cursor et d'autres), partez du modèle et gardez vos propres règles de projet en dessous : ``` curl -sSf https://dzbuild.dev/agents/AGENTS.md -o AGENTS.md ``` Les deux fichiers reprennent les règles de ce site, pour que votre agent travaille à partir des mêmes faits que vous. ## Donnez la documentation à votre agent comme serveur MCP[​](#donnez-la-documentation-à-votre-agent-comme-serveur-mcp "Lien direct vers Donnez la documentation à votre agent comme serveur MCP") `@dzbuild/docs-mcp` donne à tout client MCP ces pages et la référence de l'API, lues depuis dzbuild.dev, sans aucun identifiant. La page [/agents/connect](https://dzbuild.dev/fr/fr/agents/connect) donne la commande ou la configuration pour Claude Code, Codex, Cursor et Claude Desktop. ## Poser une question sur une page[​](#poser-une-question-sur-une-page "Lien direct vers Poser une question sur une page") Sous chaque page, une barre propose **Voir en Markdown**, **Copier le Markdown**, **Ouvrir dans ChatGPT** et **Ouvrir dans Claude**. Les deux derniers ouvrent un nouveau chat qui commence par lire cette page. Le message envoyé est : ``` Read https://dzbuild.dev/fr/oauth.md so I can ask questions about it. ``` Pour une tâche plutôt qu'une question, donnez à l'agent l'index et la compétence ensemble, puis décrivez ce que l'application fait pour le marchand : ``` Read https://dzbuild.dev/llms.txt and https://dzbuild.dev/skills/dzbuild-apps/SKILL.md. Build a DZBuild app in Node.js that installs on a store through the OAuth flow, stores one token per store, verifies webhooks, and posts a message to our Slack channel when an order is confirmed. Secrets come from environment variables. ``` ## Générer un client depuis la description OpenAPI[​](#générer-un-client-depuis-la-description-openapi "Lien direct vers Générer un client depuis la description OpenAPI") La description est au format OpenAPI 3.1. Importez-la dans Postman ou Insomnia, ou générez des types et un client : ``` curl -sO https://dzbuild.dev/openapi/dzbuild-apps-v1.json npx openapi-typescript dzbuild-apps-v1.json -o dzbuild-apps-v1.d.ts ``` Le schéma de sécurité `dzOAuth` du fichier liste chaque scope avec sa description. Le fichier déclare `https://api.dzbuild.app` comme serveur, l'hôte que votre application appelle. ## Gardez les secrets hors du chat[​](#gardez-les-secrets-hors-du-chat "Lien direct vers Gardez les secrets hors du chat") Un agent a seulement besoin de savoir qu'un secret existe, jamais sa valeur. * Le secret client, le secret de signature et chaque jeton d'installation vivent dans des variables d'environnement ou un coffre de secrets sur votre serveur. Ne les collez pas dans un message, un dépôt ou une ligne de journal. * Si un secret atteint un chat ou un commit, régénérez-le dans la console développeur. L'ancien secret client s'arrête aussitôt ; les jetons déjà émis continuent de fonctionner, et renouveler le secret de signature le change pour toutes les installations à la fois : déployez la nouvelle valeur tout de suite. * Un agent ne doit pas se connecter au tableau de bord DZBuild à la place du marchand, le scripter, ni aspirer les pages des boutiques. Les données de boutique passent uniquement par l'API REST et les webhooks, comme le disent les [règles de sécurité](https://dzbuild.dev/fr/fr/security.md). * Les adresses de redirection sont comparées caractère par caractère. Enregistrez dans la console l'adresse exacte que votre code envoie, en `https`, avec la même barre oblique finale. ## Ce que les assistants se trompent sans la documentation[​](#ce-que-les-assistants-se-trompent-sans-la-documentation "Lien direct vers Ce que les assistants se trompent sans la documentation") Ces erreurs reviennent souvent quand une application est écrite à partir de connaissances générales sur OAuth ou les webhooks. Les pages liées tranchent chacune. * Attendre `expires_in` et un jeton de rafraîchissement. Les jetons d'installation n'ont ni l'un ni l'autre ; ils fonctionnent jusqu'à ce que le marchand désinstalle ou réinstalle. Voir [Concepts clés](https://dzbuild.dev/fr/fr/concepts.md). * Envoyer une écriture sans `Idempotency-Key`. `POST`, `PATCH` et `DELETE` répondent `400` sans elle. Voir [Limites de requêtes](https://dzbuild.dev/fr/fr/rate-limits.md). * Analyser le corps du webhook avant de vérifier la signature. Le HMAC couvre les octets bruts, un corps re-sérialisé ne correspond donc jamais. Voir [Webhooks](https://dzbuild.dev/fr/fr/webhooks.md). * Enregistrer le webhook via `POST /v1/webhooks`. Les applications y reçoivent `403` ; l'URL de webhook se règle une fois sur l'application dans la console. Voir [Référence de l'API](https://dzbuild.dev/fr/fr/api-reference.md). * Demander tous les scopes. Le marchand voit une ligne par ressource sur l'écran de consentement, et la vérification compare les scopes avec ce que la fiche dit de l'application. Voir [Scopes](https://dzbuild.dev/fr/fr/scopes.md). * Construire un sélecteur de boutique dans un seul jeton. Un jeton n'atteint que sa boutique ; utilisez le jeton de chaque boutique depuis la liste `stores` de la réponse du jeton. Voir [OAuth](https://dzbuild.dev/fr/fr/oauth.md).