# Un agent IA qui génère les types GraphQL d’un projet WordPress headless

> Retour d'expérience sur l'utilisation d'un agent pour maintenir à jour les types TypeScript générés depuis le schéma WPGraphQL à chaque changement de champ ACF.

- Auteur : Clément Hadrot
- Publié le : 2026-06-01
- Mis à jour le : 2026-06-01
- Catégorie : Headless & API
- URL : https://wpmoderne.dev.wordpress-developpement.fr/headless/agent-ia-genere-types-graphql-wordpress-headless/

## L’essentiel

- Un agent surveille les modifications de champs ACF et régénère les types TypeScript sans intervention manuelle
- La vérification automatique par compilation reste indispensable pour valider le travail de l'agent
- Un garde-fou explicite empêche l'agent de modifier lui-même le code métier consommant ces types

Le problème récurrent sur ce projet, une plateforme de gestion de biens immobiliers avec WordPress headless en back-office et WPGraphQL comme couche d'API, n'était pas la génération de types elle-même, un problème déjà bien résolu par des outils de codegen GraphQL classiques. Le problème était humain : à chaque ajout ou modification d'un champ ACF par l'équipe métier dans WordPress, quelqu'un côté développement devait se souvenir de relancer manuellement la commande de génération de types, un réflexe régulièrement oublié, provoquant des erreurs de type silencieuses détectées parfois plusieurs jours après le changement réel.

La solution testée sur ce projet a consisté à confier cette tâche répétitive et bien délimitée à un agent, chargé de surveiller les changements de schéma et de régénérer les types automatiquement, sans reproduire l'erreur classique de laisser un système automatisé toucher à autre chose que sa tâche strictement définie.

## Le périmètre volontairement restreint confié à l'agent

La décision la plus importante de ce projet n'a pas été technique mais organisationnelle : définir précisément ce que l'agent avait le droit de faire, et surtout ce qu'il n'avait pas le droit de faire. L'agent surveille le schéma GraphQL exposé par WPGraphQL, détecte tout changement de type ou de champ, régénère le fichier de types TypeScript correspondant, et ouvre une proposition de modification limitée à ce seul fichier généré.

```
# Commande exécutée par l'agent à chaque déclenchement
npx graphql-codegen --config codegen.yml
git diff --stat src/types/wpgraphql-generated.ts
```

L'agent n'a explicitement aucune autorisation d'aller modifier les composants qui consomment ces types. Si un changement de schéma casse la compilation d'un composant existant (un champ renommé, par exemple), l'agent signale l'échec de compilation dans sa proposition de modification, sans tenter de corriger lui-même le composant impacté, une tâche laissée délibérément à un développeur humain.

> L'essentiel à retenir : Un agent surveille les modifications de champs ACF et régénère les types TypeScript sans intervention manuelle ; La vérification automatique par compilation reste indispensable pour valider le travail de l'agent ; Un garde-fou explicite empêche l'agent de modifier lui-même le code métier consommant ces types

## Le déclencheur : un webhook WordPress vers l'agent

Un hook WordPress personnalisé, accroché sur la sauvegarde des groupes de champs ACF, envoie un signal léger (sans détail du changement, juste une notification) vers l'environnement d'exécution de l'agent, qui déclenche alors sa vérification complète du schéma :

```
add_action('acf/save_post', function ($post_id) {
    if (get_post_type($post_id) === 'acf-field-group') {
        wp_remote_post(AGENT_WEBHOOK_URL, [
            'body' => wp_json_encode(['evenement' => 'schema_acf_modifie']),
            'timeout' => 3,
        ]);
    }
}, 20);
```

Ce déclenchement événementiel évite à l'agent de devoir interroger le schéma en continu par sondage régulier, une approche plus coûteuse et moins réactive que ce déclenchement ciblé sur l'événement réel de modification.

### La vérification systématique par compilation

Le point non négociable de cette architecture est que la proposition de modification générée par l'agent ne peut jamais être fusionnée automatiquement dans le code du projet. Elle déclenche systématiquement la suite de compilation TypeScript et la suite de tests existante en intégration continue, exactement comme n'importe quelle contribution humaine. Sur les quatre mois d'observation, deux propositions de l'agent ont révélé un échec de compilation sur des composants existants, correctement signalé, et corrigé manuellement par un développeur en moins d'une heure à chaque fois, un délai bien inférieur aux plusieurs jours que prenait auparavant la détection manuelle d'un tel décalage.

## Ce que cette automatisation a changé concrètement

- Quarante-six changements de champs ACF ont été traités automatiquement sur la période observée, sans qu'aucune erreur de type ne passe inaperçue en production, contre en moyenne trois incidents de ce type par trimestre avant la mise en place de l'agent.
- Le temps entre un changement de champ côté WordPress et sa disponibilité en types TypeScript à jour côté développement est passé de plusieurs jours (le temps qu'un développeur pense à relancer la commande) à moins de deux minutes.
- Le travail de génération de types, auparavant perçu comme une corvée régulièrement reportée par l'équipe, a totalement disparu de la charge mentale quotidienne des développeurs.

## Les limites reconnues de cette approche

L'agent ne remplace en rien la réflexion de conception nécessaire lorsqu'un champ ACF change de structure de façon significative, par exemple un champ texte devenant un champ de relation vers un autre type de contenu. Dans ce cas précis, la régénération de type révèle bien le changement, mais l'adaptation du code métier qui exploite ce champ reste un travail de conception humain, que l'agent ne tente à aucun moment d'automatiser, conformément à son périmètre volontairement restreint défini dès le départ.

> Un agent utile n'est pas celui qui fait le plus de choses possible, mais celui dont le périmètre est assez restreint et assez bien défini pour qu'on puisse vérifier son travail sans effort disproportionné par rapport à la valeur qu'il apporte.

## En résumé

Ce cas d'usage reste modeste dans son ambition, ce qui explique en grande partie sa réussite : l'agent traite une tâche mécanique, répétitive, à faible risque, et strictement vérifiable par un processus de compilation existant. Il ne prend aucune décision de conception, se contente de proposer, et laisse systématiquement à un développeur la responsabilité finale de valider ou de corriger. C'est précisément ce périmètre restreint qui a rendu son adoption possible sans réticence de l'équipe technique du projet.