Passer au contenu principal
GUIDE

Comment donner aux agents IA un chemin structuré dans votre application

Au lieu de forcer les agents à passer par des pages conçues pour des personnes, proposez-leur des routes structurées. Ce guide couvre les formats, la découverte, le routage par classe d'acteur et des limites équitables.

Toshendra Sharma

Par Toshendra SharmaFondateur et CEO, AgentCredia · Updated November 13, 2026

Intermédiaire · 10 min de lecture

Pourquoi les agents IA ont-ils besoin d'un chemin différent dans votre application ?

Une part croissante des requêtes vers votre application provient d'agents IA: assistants qui récupèrent de la documentation pour un utilisateur, outils de recherche qui lisent des pages produit, workflows autonomes qui appellent votre API. La plupart d'entre eux travaillent à travers des interfaces conçues pour des personnes. Ils téléchargent des pages HTML complètes, analysent les mises en page, suivent une navigation pensée pour une souris, et relancent les requêtes quand une page lourde en scripts ne s'affiche pas comme prévu.

C'est inefficace pour tout le monde. Les agents reçoivent un contenu bruyant et commettent des erreurs. Vos serveurs dépensent des ressources à afficher des pages que personne ne regarde. Et le trafic est difficile à interpréter, parce qu'il ressemble à un navigateur qui se comporte bizarrement. Si vous n'êtes pas encore certain de la part de votre trafic concernée, commencez par comment savoir si le trafic d'un site web provient d'agents IA.

Une meilleure approche consiste à donner aux agents un chemin structuré: du contenu et des actions dans des formats conçus pour les programmes, découvrables à des emplacements standard, avec des limites qui récompensent les clients qui s'identifient correctement. Ce guide montre comment faire cela sans construire une seconde application.

Étape 1: Décidez ce que les agents doivent pouvoir faire

Commencez par l'intention, pas par la technologie. Examinez les routes où vous voyez déjà du trafic d'agents et regroupez-les:

  • Lire du contenu: documentation, informations produit, pages tarifaires, articles d'aide, profils publics.
  • Interroger des données: recherche, consultation de catalogue, disponibilité, statut.
  • Effectuer des actions: créer, mettre à jour ou supprimer quelque chose au nom d'un utilisateur.

La lecture et l'interrogation sont de bons candidats pour un chemin structuré ouvert à tout client qui se comporte correctement. Les actions nécessitent une authentification et une autorisation, quelle que soit la manière dont le client s'identifie, et elles sont couvertes dans le guide sur la protection des actions sensibles.

Étape 2: Proposez des formats adaptés aux machines

Pour les routes de contenu, proposez les mêmes informations sans le chrome de la page. Deux formats couvrent la plupart des besoins:

  • Markdown pour le contenu rédigé comme la documentation et les articles, servi avec le type de média text/markdown enregistré dans RFC 7763. Il conserve les titres, listes, liens et blocs de code, et il est compact.
  • JSON pour les enregistrements structurés comme les produits, les offres ou le statut.

Utilisez la négociation de contenu pour que l'URL reste la même et que le client demande le format voulu:

TS
import express from "express";

const app = express();

app.get("/docs/:slug", async (req, res) => {
  const doc = await loadDoc(req.params.slug);
  if (!doc) return res.status(404).end();

  res.vary("Accept");
  const preferred = req.accepts(["text/html", "text/markdown", "application/json"]);

  if (preferred === "text/markdown") {
    return res.type("text/markdown; charset=utf-8").send(doc.markdown);
  }
  if (preferred === "application/json") {
    return res.json({ title: doc.title, updatedAt: doc.updatedAt, body: doc.markdown });
  }
  return res.render("doc", { doc });
});

Envoyez un en-tête Vary: Accept (RFC 9110 sur Vary) afin que les caches stockent chaque représentation séparément. Beaucoup d'équipes exposent aussi une URL alternative explicite, par exemple en ajoutant .md à un chemin de documentation, parce que certains clients trouvent cela plus simple que la négociation. Liez-la depuis la page HTML avec <link rel="alternate" type="text/markdown" href="..."> afin qu'elle puisse être découverte. Des liens typés comme celui-ci suivent le modèle Web Linking.

Étape 3: Comment les agents découvrent-ils votre chemin structuré ?

Les agents ne peuvent pas utiliser ce qu'ils ne trouvent pas. Publiez les points d'entrée aux endroits où les clients automatisés regardent déjà:

  1. /llms.txt à la racine du site: un court résumé Markdown de ce que votre site propose, avec des liens vers les pages les plus utiles et leurs versions structurées, conformément à la proposition llms.txt.
  2. Une description d'API comme un document OpenAPI, liée depuis votre documentation développeur et depuis /llms.txt.
  3. Des liens alternatifs dans les pages HTML pointant vers des versions Markdown ou JSON.
  4. Un sitemap listant vos URLs de contenu canoniques, au format défini par le protocole Sitemaps.

Un llms.txt minimal:

MARKDOWN
# Example App

> Example App helps teams plan projects. This file lists the best entry points for automated clients.

## Docs
- [Getting started](https://example.com/docs/getting-started.md): setup in five steps
- [API reference](https://example.com/openapi.json): OpenAPI description of the public API

## Policies
- [Automated access](https://example.com/docs/automated-access.md): limits and how to sign requests

Gardez une page qui explique vos règles pour les clients automatisés: quelles routes sont ouvertes, quelles limites s'appliquent, et comment un client peut s'identifier avec des requêtes signées pour recevoir un meilleur traitement. Des règles claires transforment l'approximation en coopération.

Étape 4: Routez selon la classe d'acteur, pas selon la chaîne user agent

Une fois que vous avez des réponses structurées, décidez qui les obtient par défaut. Utilisez la classe d'acteur et sa base plutôt que d'analyser les chaînes user agent au cas par cas. Les opérateurs d'IA publient bien leurs user agents, comme OpenAI et Anthropic le font pour leurs crawlers et fetchers, mais une correspondance de chaîne reste une simple déclaration.

TS
type ActorClass = "human" | "human_ai" | "agent" | "unknown";
type Basis = "verified" | "declared" | "inferred" | "unknown";

function preferStructured(actor: ActorClass, basis: Basis, accept: string): boolean {
  if (accept.includes("text/markdown") || accept.includes("application/json")) return true;
  return actor === "agent" && (basis === "verified" || basis === "declared");
}

Deux principes gardent cela sûr:

  • Les demandes explicites gagnent toujours. Si un client demande du Markdown ou du JSON, servez-le, quelle que soit la classe.
  • Les valeurs par défaut ne retirent jamais rien. Un visiteur Human ou Unknown reçoit toujours la page complète. Choisir une valeur par défaut structurée pour les agents change le format, pas ce qu'ils sont autorisés à voir.

Étape 5: Quels limites de débit les agents IA devraient-ils recevoir ?

Les limites de débit sont l'endroit où le contexte d'acteur devient le plus visible. Au lieu d'une seule limite pour tout le monde, donnez à chaque combinaison de classe et de base un budget adapté:

Acteur et base Routes de lecture Notes
Agent, Verified Limite plus élevée L'opérateur est identifiable et responsable
Agent, Declared ou Inferred Limite standard Les déclarations ne sont pas vérifiables
Unknown Limite standard Ne jamais être punitif par défaut
Human ou Human + AI Limite standard L'usage interactif atteint rarement les limites

Bornez la limite avec l'identifiant le plus stable disponible. Pour les agents vérifiés, c'est l'origine de l'opérateur et l'identifiant de clé. Pour les autres, utilisez l'identifiant d'accès ou une clé au niveau réseau.

TS
function limitKey(actor: { actor: ActorClass; basis: Basis; operator?: string }, ip: string, apiKey?: string) {
  if (actor.actor === "agent" && actor.basis === "verified" && actor.operator) return `op:${actor.operator}`;
  if (apiKey) return `key:${apiKey}`;
  return `ip:${ip}`;
}

function limitFor(actor: { actor: ActorClass; basis: Basis }): number {
  if (actor.actor === "agent" && actor.basis === "verified") return 600;
  return 120;
}

Les chiffres sont des espaces réservés. Définissez les vôtres à partir de la base observée. Lorsqu'un client dépasse une limite, renvoyez 429 Too Many Requests avec un en-tête Retry-After et un lien vers votre page d'accès automatisé. Les agents bien conçus ralentissent et la lisent.

Étape 6: Gardez les actions derrière l'autorisation

Un chemin structuré pour la lecture n'est pas un détour autour de votre modèle de sécurité. Toute action qui modifie des données nécessite toujours:

  1. une authentification avec un identifiant émis par votre application,
  2. une autorisation pour cette action précise, et
  3. les vérifications supplémentaires requises par le niveau de risque de la route.

Une signature vérifiée vous dit quel client appelle. Elle ne vous dit pas que ce client peut agir pour un utilisateur donné. Gardez ces questions séparées. Notre article sur ce que prouvent les requêtes signées d'agents IA explique la différence.

Étape 7: Mesurez l'effet

Exécutez d'abord le chemin structuré en mode observation, puis comparez:

  • la part des requêtes d'agents qui utilisent des formats structurés,
  • le coût serveur et la latence pour le trafic d'agents avant et après,
  • les taux d'erreur et de relance pour les clients agents,
  • combien de clients automatisés passent de declared à verified une fois que vous publiez vos consignes de signature.

Ces chiffres montrent si le chemin structuré remplit son rôle et où l'étendre ensuite.

Étape 8: Versionnez et documentez le chemin structuré

Traitez le chemin structuré comme une interface publique, car les agents vont construire dessus. Quelques habitudes le rendent fiable:

  1. Gardez des URLs stables. Si un agent a appris que /docs/getting-started.md existe, cela doit continuer de fonctionner. Quand le contenu change d'emplacement, renvoyez une 301 vers le nouvel emplacement plutôt qu'une 404.
  2. Incluez les heures de mise à jour. Placez un champ updatedAt dans les réponses JSON et un en-tête Last-Modified sur Markdown, afin que les agents puissent mettre en cache de manière sensée et ne rafraîchir que lorsque quelque chose a changé.
  3. Prenez en charge les requêtes conditionnelles. Répondez à If-None-Match et If-Modified-Since avec 304 Not Modified. Les agents qui sondent votre contenu coûtent bien moins cher lorsqu'ils peuvent revalider au lieu de tout télécharger à nouveau.
  4. Versionnez les changements cassants. Si une forme JSON doit changer, ajoutez un nouveau chemin de version ou un nouveau type de média et conservez l'ancien pendant une période publiée.
  5. Publiez un changelog pour la page d'accès automatisé. Les opérateurs d'agents bien comportés le lisent, et cela vous donne un endroit pour annoncer de nouvelles routes structurées.
TS
app.get("/api/plans", async (req, res) => {
  const plans = await loadPlans();
  const etag = `"${plans.version}"`;
  res.set("ETag", etag);
  res.set("Cache-Control", "public, max-age=300");
  if (req.get("if-none-match") === etag) return res.status(304).end();
  return res.json({ updatedAt: plans.updatedAt, plans: plans.items });
});

Ces pratiques profitent aussi à votre frontend et à vos intégrations partenaires. Un chemin structuré, stable, cacheable et documenté devient rapidement la manière la plus simple pour tout programme de travailler avec votre application.

Pièges courants

  • Servir des faits différents aux agents et aux personnes. La version structurée doit contenir les mêmes informations que la page. Un contenu divergent déroute les utilisateurs qui interrogent un assistant sur votre produit.
  • Cacher le chemin structuré. S'il n'est pas lié depuis /llms.txt, vos docs API ou les pages elles-mêmes, les agents continueront à aspirer le HTML.
  • Récompenser les déclarations. Les limites plus élevées doivent être réservées aux clients vérifiés. Une chaîne user agent copiée ne devrait pas ouvrir un budget plus important.
  • Oublier les caches. Sans Vary: Accept, un cache peut servir du Markdown à un navigateur.

Où Proof of Actor s'insère

Proof of Actor vous donne la classe d'acteur et la base dont vous avez besoin pour router les agents vers du contenu structuré et définir des limites équitables. Il détecte les agents signés, déclarés et inférés, vous aide à comprendre comment ils utilisent vos routes, et laisse la décision de routage dans votre code.

Pour concevoir un chemin structuré pour votre propre application avec notre équipe, demandez un accès anticipé. Pour les scénarios API et MCP en particulier, consultez APIs et MCP Servers, et lisez qui appelle votre serveur MCP ? pour voir comment le contexte d'acteur s'applique aux appels d'outils Model Context Protocol.

Sources

Construisez-le avec nous.

Rejoignez le programme fondateur développeur de Proof of Actor.

Obtenir un accès anticipéEspace développeur

Vous préférez en parler d'abord ? Parler aux fondateurs