WebMCP declarativo vs. imperativo: guía de construcción de un storefront

¿Una acción del storefront es un atributo HTML o una función JS? Con WebMCP no es una cuestión de estilo, es una decisión de arquitectura que todo equipo de frontend debería tomar antes del primer sprint. Esta guía la responde de forma práctica: dos ejemplos de código, una matriz de decisión, ningún debate nuevo sobre límites ni GEO. Eso ya lo tratamos en los posts enlazados más abajo.

Dos formas de hacer que un storefront sea accionable por agentes

WebMCP hace que las acciones del storefront sean ejecutables para los agentes de IA. Cómo se expone una acción al agente se reduce a dos patrones:

• Anotación declarativa: la acción vive como atributo directamente en el markup HTML. Un script de runtime de WebMCP lee el atributo y expone la acción, sin necesidad de código JS adicional por acción.
• Tool actuation imperativa: la acción es una función JS registrada con su propio nombre, parámetros y valor de retorno. El agente llama a la función como si fuera una API.

Ambos patrones producen el mismo resultado, el agente ejecuta una acción en el storefront, pero se diferencian en esfuerzo, control y superficie de error.

La vía declarativa: anotación HTML

La anotación declarativa encaja con acciones que se corresponden 1:1 con un elemento visible de la UI, son de corta duración y no necesitan una transición de estado en varios pasos. Un botón de carrito es el ejemplo estándar:

<button
  data-webmcp-action="cart.add"
  data-webmcp-target="product"
  data-webmcp-params='{"variantId": "{{variant.id}}", "quantity": 1}'
  data-webmcp-result="cart.summary"
>
  Añadir al carrito
</button>

La anotación describe por completo lo que ocurre: nombre de la acción, entidad de destino, parámetros, resultado esperado. Sin configuración de tool aparte, sin imports, sin paso de build. El script de runtime recorre el DOM, registra la acción, listo. La contrapartida: cualquier lógica que no se pueda expresar en el valor de un atributo, validación, condiciones en varios pasos, pasos intermedios asíncronos, no cabe aquí.

La vía imperativa: tool actuation en JS

La tool actuation imperativa encaja en cuanto una acción necesita lógica de negocio, varias llamadas al backend o gestión de errores:

webmcp.registerTool({
  name: "cart.add",
  description: "Añade una variante de producto al carrito activo.",
  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 función encapsula la comprobación, la llamada al backend y la forma de la respuesta. El agente solo ve el nombre, el esquema de parámetros y el valor de retorno, no la implementación. Eso da control total sobre los casos de error y las transiciones de estado, pero cuesta esfuerzo de configuración por acción: registro, tipado, pruebas.

Matriz de decisión: ¿cuál y cuándo?

Regla general para el equipo: si la acción cabe en una frase sin condiciones, anótala de forma declarativa. En cuanto aparece un "si X entonces Y, si no Z", regístrala de forma imperativa.

Errores habituales al anotar

• Sobrecarga de anotaciones: demasiados atributos data-webmcp-* en un mismo elemento sin una convención de nombres clara, el agente ya no puede distinguir prioridades.
• Tool sin ruta de error: tools registrados que no devuelven una respuesta estructurada cuando fallan, el agente interpreta entonces un fallo como un éxito.
• Fuente de verdad duplicada: la misma acción anotada de forma declarativa y registrada de forma imperativa a la vez, el script de runtime no sabe qué patrón se aplica.
• Esquema de resultado ausente: el agente no recibe un éxito o fallo estructurado y tiene que adivinarlo por el texto de la UI.

Combinar ambos patrones en el mismo storefront

En la práctica, los storefronts en producción mezclan ambos patrones. Las acciones de la PDP como añadir al carrito, guardar en la wishlist o cambiar de variante funcionan de forma declarativa, porque son simples y están ligadas a la UI. La lógica de checkout, descuentos y stock funciona de forma imperativa, porque comprueba el estado del backend y tiene que gestionar errores. Ese reparto es justamente la razón por la que Laioutr, como Frontend Management Platform, ofrece anotación y tool registry en la misma capa de componentes. Quien escribe los componentes decide acción por acción qué patrón encaja, sin mantener dos sistemas separados. El frontend sigue siendo un Composable Headless Frontend, no dos stacks paralelos.

Si entiendes WebMCP como un modelo operativo y no como una función aislada, el marco más amplio está en Frontend as a Service: la anotación y la tool actuation son dos piezas de la capa de agentes que se diseña desde el principio.

Checklist de implementación

• Enumera todas las acciones del storefront que los agentes deberían poder ejecutar: carrito, wishlist, pasos de checkout, código de descuento.
• Clasifica cada acción con la matriz anterior: declarativa o imperativa.
• Anota las acciones declarativas directamente en la plantilla del componente, no en archivos de configuración aparte.
• Registra los tools imperativos con un esquema de parámetros completo, no solo con un nombre.
• Prueba ambas vías con tráfico real de agentes, no solo con clics manuales.
• Documenta los valores de retorno de cada acción para que los agentes puedan interpretar los resultados de forma fiable.

Si quieres los fundamentos de la actuation de agentes en el frontend, lee WebMCP: cuando los frontends se convierten en acciones para agentes. Para el ángulo GEO, cómo los frontends agent-ready se citan en las AI overviews, consulta Frontend agent-ready: el GEO se encuentra con WebMCP. El límite entre WebMCP y MCP en un contexto de commerce, actuation en el navegador o en el servidor, se aborda en WebMCP vs. MCP Commerce: navegador vs. servidor. Y cómo los frontends permiten que los agentes escriban de forma segura, governance y guardrails, es el tema de Frontends MCP Commerce: permitir que los agentes escriban de forma segura.

Esta guía es deliberadamente práctica: el patrón de anotación, el patrón de tool actuation, la matriz de decisión. Si buscas respuesta a las preguntas sobre límites y governance, los cuatro posts anteriores las cubren. Si quieres construir hoy mismo, la matriz y los dos ejemplos de código son el punto de partida directo. Para conocer la plataforma detrás de todo esto, visita la página de inicio de Laioutr.