WebMCP déclaratif vs impératif : guide de build storefront

Une action de storefront est-elle un attribut HTML ou une fonction JS ? Avec WebMCP, ce n'est pas une question de style, c'est une décision d'architecture que chaque équipe frontend doit prendre avant le premier sprint. Ce guide y répond de façon pratique : deux exemples de code, une matrice de décision, sans rouvrir le débat sur les frontières ou le GEO. Nous l'avons déjà traité dans les articles liés ci-dessous.

Deux façons de rendre un storefront actionnable par des agents

WebMCP rend les actions d'un storefront exécutables par des agents IA. La façon dont une action est exposée à l'agent se joue entre deux modèles :

• Annotation déclarative : l'action vit comme un attribut directement dans le markup HTML. Un script runtime WebMCP lit l'attribut et expose l'action, sans code JS supplémentaire par action.
• Actuation impérative par outil: l'action est une fonction JS enregistrée, avec son propre nom, ses paramètres et sa valeur de retour. L'agent appelle la fonction comme une API.

Les deux modèles produisent le même résultat, l'agent exécute une action dans le storefront, mais avec un effort, un contrôle et une surface d'erreur différents.

La voie déclarative : l'annotation HTML

L'annotation déclarative convient aux actions qui correspondent 1:1 à un élément d'interface visible, sont éphémères et ne nécessitent pas de transition d'état à plusieurs étapes. Un bouton panier est l'exemple type :

<button
  data-webmcp-action="cart.add"
  data-webmcp-target="product"
  data-webmcp-params='{"variantId": "{{variant.id}}", "quantity": 1}'
  data-webmcp-result="cart.summary"
>
  Ajouter au panier
</button>

L'annotation décrit intégralement ce qui se passe : nom de l'action, entité cible, paramètres, résultat attendu. Pas de configuration d'outil séparée, pas d'import, pas d'étape de build. Le script runtime scanne le DOM, enregistre l'action, c'est terminé. L'inconvénient : toute logique qui ne peut pas s'exprimer dans une valeur d'attribut, validation, conditions à plusieurs niveaux, étapes intermédiaires asynchrones, n'a pas sa place ici.

La voie impérative : l'actuation par outil JS

L'actuation impérative par outil convient dès qu'une action nécessite de la logique métier, plusieurs appels backend ou une gestion d'erreurs :

webmcp.registerTool({
  name: "cart.add",
  description: "Ajoute une variante de produit au panier actif.",
  parameters: {
    variantId: { type: "string", required: true },
    quantity: { type: "number", default: 1 }
  },
  async execute({ variantId, quantity }) {
    const stock = await storefront.inventory.check(variantId);
    if (stock.available < quantity) {
      throw new Error("insufficient_stock");
    }
    const cart = await storefront.cart.addLine(variantId, quantity);
    return { cartId: cart.id, itemCount: cart.itemCount, subtotal: cart.subtotal };
  }
});

La fonction encapsule la vérification, l'appel backend et le format de réponse. L'agent ne voit que le nom, le schéma des paramètres et la valeur de retour, pas l'implémentation. Cela donne un contrôle complet sur les cas d'erreur et les transitions d'état, mais coûte un effort de mise en place par action : enregistrement, typage, tests.

Matrice de décision : quand utiliser quoi ?

Règle simple pour l'équipe : si l'action tient en une phrase sans condition, annoter en déclaratif. Dès qu'un « si X alors Y, sinon Z » entre en jeu, enregistrer en impératif.

Erreurs fréquentes lors de l'annotation

• Surcharge d'annotations: trop d'attributs data-webmcp-* sur un même élément sans convention de nommage claire, l'agent ne distingue plus les priorités.
• Outil sans chemin d'erreur: des outils enregistrés qui ne renvoient aucune réponse structurée en cas d'échec, l'agent interprète alors un plantage comme un succès.
• Double source de vérité: la même action à la fois annotée en déclaratif et enregistrée en impératif, le script runtime ne sait plus quel modèle appliquer.
• Schéma de résultat manquant: l'agent ne reçoit pas de succès ou d'échec structuré et doit deviner à partir du texte de l'interface.

Combiner les deux modèles dans un même storefront

En pratique, les storefronts en production mélangent les deux modèles. Les actions de la page produit, ajouter au panier, liste de souhaits, changer de variante, fonctionnent en déclaratif, car elles sont simples et liées à l'interface. La logique de commande, de remise et de stock fonctionne en impératif, car elle vérifie l'état backend et doit gérer les erreurs. Cette séparation explique pourquoi Laioutr, en tant que Frontend Management Platform, propose l'annotation et un registre d'outils dans la même couche de composants. Les auteurs de composants décident, par action, du modèle adapté, sans maintenir deux systèmes séparés. Le frontend reste un Composable Headless Frontend, pas deux stacks parallèles.

Pour qui envisage WebMCP comme un modèle d'exploitation plutôt qu'une fonctionnalité isolée, le cadre plus large se trouve sous Frontend as a Service : l'annotation et l'actuation par outil sont deux briques de la couche agent, pensée dès le départ.

Checklist de build

• Lister toutes les actions du storefront que les agents doivent pouvoir exécuter : panier, liste de souhaits, étapes de commande, code de remise.
• Classer chaque action selon la matrice ci-dessus : déclarative ou impérative.
• Annoter les actions déclaratives directement dans le template du composant, pas dans des fichiers de configuration séparés.
• Enregistrer les outils impératifs avec un schéma de paramètres complet, pas seulement un nom.
• Tester les deux chemins avec du trafic agent réel, pas seulement avec des clics manuels.
• Documenter les valeurs de retour par action pour que les agents interprètent les résultats de façon fiable.

Pour les fondamentaux de l'actuation des agents sur le frontend, lisez WebMCP : quand les frontends deviennent des actions d'agent. Pour la perspective GEO, comment les frontends agent-ready sont cités dans les AI overviews, voir Agent-Ready Frontend : le GEO rencontre WebMCP. La frontière entre WebMCP et MCP dans un contexte commerce, actuation navigateur vs serveur, est traitée dans WebMCP vs MCP Commerce : navigateur vs serveur. Et comment laisser les agents écrire en toute sécurité sur le frontend, gouvernance et garde-fous, fait l'objet de MCP Commerce Frontends : laisser les agents écrire en toute sécurité.

Ce guide est volontairement centré sur l'implémentation : le pattern d'annotation, le pattern d'actuation par outil, la matrice de décision. Pour les questions de frontière et de gouvernance, les quatre articles ci-dessus les traitent. Pour construire dès aujourd'hui, la matrice et les deux exemples de code constituent le point de départ direct. Pour découvrir la plateforme derrière tout cela, direction la page d'accueil Laioutr.