# Un site headless conçu pour les agents IA autant que pour les visiteurs humains

> Architecture d'un projet qui expose délibérément un schéma structuré et des points d'accès pensés pour être consommés par des agents autant que par un front React classique.

- Auteur : Clément Hadrot
- Publié le : 2026-06-12
- Mis à jour le : 2026-06-12
- Catégorie : Headless & API
- URL : https://wpmoderne.dev.wordpress-developpement.fr/headless/site-headless-concu-agents-ia-visiteurs-humains/

## L’essentiel

- Le même contenu WordPress alimente un front visuel classique et une couche de données pensée pour des agents
- Un schéma explicite et stable compte davantage pour un agent qu'une belle mise en page
- Exposer une intention claire par contenu réduit les erreurs d'interprétation côté agent

Le commanditaire de ce projet, un comparateur indépendant d'assurances professionnelles, est parti d'un constat inhabituel pour un brief de refonte de site : une part croissante de son trafic ne provenait plus de visiteurs humains cliquant sur des liens, mais d'agents automatisés interrogeant le site pour répondre à des questions posées par leurs propres utilisateurs ailleurs. La question posée à l'équipe technique n'était donc plus seulement « comment ce site s'affiche-t-il dans un navigateur », mais « comment ce site peut-il être compris correctement par un système qui ne voit jamais son rendu visuel ».

Ce texte décrit l'architecture retenue pour répondre aux deux besoins simultanément, sans sacrifier l'un pour l'autre, à partir d'un même WordPress headless comme source de contenu unique.

## Deux consommateurs, une seule source de vérité

Le principe fondateur du projet a été de refuser catégoriquement de maintenir deux bases de contenu séparées, une pour les humains et une pour les agents, une tentation initiale qui aurait immédiatement posé un problème de synchronisation. WordPress reste l'unique source de vérité du contenu, mais expose deux surfaces distinctes construites à partir des mêmes données : le front React classique, destiné au navigateur, et une couche de données structurées, destinée à être consommée directement par un agent sans jamais passer par le rendu visuel.

## Ce que l'équipe a changé dans le modèle de contenu

Le premier changement, le plus structurant, a porté sur les champs eux-mêmes. Un champ ACF de type texte libre nommé « garanties » a été remplacé par une structure répétée explicite, avec des sous-champs typés (montant de la garantie, franchise, exclusions), plutôt que de laisser un rédacteur décrire librement ces informations dans un paragraphe. Cette structuration, motivée initialement pour améliorer l'affichage d'un tableau comparatif côté humain, s'est révélée tout aussi déterminante pour la lisibilité côté agent : un agent qui doit comparer deux offres d'assurance a besoin d'extraire un montant précis, pas d'interpréter une phrase rédigée en langage naturel avec ses ambiguïtés potentielles.

> L'essentiel à retenir : Le même contenu WordPress alimente un front visuel classique et une couche de données pensée pour des agents ; Un schéma explicite et stable compte davantage pour un agent qu'une belle mise en page ; Exposer une intention claire par contenu réduit les erreurs d'interprétation côté agent

```
{
  "garanties": [
    {
      "type": "responsabilite_civile",
      "montant_couverture": 500000,
      "devise": "EUR",
      "franchise": 250,
      "exclusions": ["negligence_grave"]
    }
  ]
}
```

## Un point d'accès dédié, distinct du front visuel

Plutôt que de demander à un agent d'analyser le HTML rendu du site, ce qui reste possible mais fragile face à toute évolution de mise en page, un endpoint REST dédié expose directement cette structure de données, avec un schéma documenté et volontairement stable dans le temps, versionné explicitement pour que toute évolution future n'invalide pas silencieusement les intégrations existantes.

```
add_action('rest_api_init', function () {
    register_rest_route('donnees-structurees/v1', '/offres', [
        'methods'  => 'GET',
        'callback' => 'exposer_offres_structurees',
        'permission_callback' => '__return_true',
    ]);
});
// Réponse annoncée avec un champ explicite de version de schéma
// { "version_schema": "1.2", "offres": [...] }
```

Un fichier `llms.txt`, placé à la racine du site, référence explicitement ce point d'accès et décrit en langage clair son usage prévu, pour orienter un agent vers la source de données structurées plutôt que vers une tentative d'extraction du rendu visuel, plus sujette à erreur.

### Exposer une intention, pas seulement une donnée

Un enseignement inattendu de ce projet a été l'importance de préciser explicitement, à côté de chaque donnée, l'intention ou le contexte qui l'accompagne. Un simple nombre comme `250` pour une franchise ne suffit pas sans préciser son unité et son contexte d'application : la structure finalement retenue inclut systématiquement une clé `contexte` à côté de chaque valeur numérique sensible à l'interprétation, réduisant nettement les cas où des tests menés avec plusieurs agents différents interprétaient une même donnée de façon divergente.

## Ce que cette double exposition n'a pas résolu

- Un agent qui interroge encore le rendu HTML classique du front React, sans passer par l'endpoint dédié, reste exposé aux mêmes limites qu'auparavant, cette approche ne fonctionnant que pour les agents qui découvrent et utilisent réellement le point d'accès structuré prévu à cet effet.
- Maintenir deux surfaces d'exposition à jour (le rendu visuel et la couche structurée) demande une discipline de test double à chaque évolution du modèle de contenu, un coût de maintenance réel qu'il ne faut pas sous-estimer.
- Aucune garantie technique n'existe qu'un agent tiers respecte effectivement le schéma proposé plutôt que de tenter, malgré tout, d'extraire une information du rendu visuel du site, un choix hors du contrôle de l'équipe du projet.

> Concevoir un contenu pensé pour un agent ne veut pas dire ajouter une couche technique en plus ; cela veut dire structurer le contenu plus rigoureusement dès sa création, un effort qui profite en réalité autant à l'affichage humain qu'à la lecture automatisée.

## Notre verdict

Ce projet montre qu'un site pensé pour des agents ne s'oppose pas à un site pensé pour des humains ; les deux gagnent en réalité à la même discipline de structuration rigoureuse du contenu à la source. La différence tient surtout dans l'exposition d'un point d'accès dédié, stable et documenté, plutôt que dans une refonte complète du modèle éditorial existant. Pour une équipe WordPress headless, l'essentiel du travail consiste moins à ajouter une technologie nouvelle qu'à revoir la rigueur de son propre modèle de contenu.