# Pour les agents IA

> La documentation et la spécification dans des formats lisibles par les assistants de code et les agents.

Toute la documentation est conçue pour être lue par des humains **et** par des agents (assistants de code, outils d'automatisation).

| Ressource | Adresse | Contenu |
|---|---|---|
| Index | [`/llms.txt`](/llms.txt) | La liste des pages, avec un lien Markdown et une description pour chacune |
| Documentation complète | [`/llms-full.txt`](/llms-full.txt) | Toutes les pages en un seul fichier Markdown |
| Une page en Markdown | `/docs/<page>.md` | Ajoutez `.md` à l'adresse d'une page, ou utilisez le lien « Voir en Markdown » |
| Spécification OpenAPI 3 | [`/openapi.json`](/openapi.json) | Toutes les routes, paramètres, corps et portées requises (`x-required-scopes`) |

## Conseils pour un agent

- **Partez de la spécification OpenAPI** pour générer un client ou des outils : elle indique, pour chaque opération, le mode d'authentification et la portée exigée.
- **Utilisez une clé de sandbox** (`pk_test_…`) pour tout essai automatisé : rien n'y est facturé et aucun vrai destinataire n'est contacté.
- **Donnez à l'agent le moins de portées possible** : une clé en lecture seule (`messages:read`, `usage:read`) suffit pour observer.
- Faites toujours passer un **`Idempotency-Key`** par ses envois : un agent qui réessaie ne doit jamais dupliquer un message.
- **Ne laissez jamais un agent envoyer en production sans validation humaine** : un message envoyé à un client ne se rattrape pas.