Ejecución en seco de Adobe Commerce Developer Agent App Builder

Un tutorial práctico para crear, implementar y probar casos de uso de extensibilidad de Commerce con Adobe Commerce Developer Agent (CDA). Esta ejecución en seco cubre tres casos de uso: un webhook de límite de cantidad de carritos, una retención de pedidos de alto valor y un archivado controlado por evento para pedidos retenidos, desde el modelo hasta las pruebas funcionales.

Primeros pasos

Cómo informar sobre problemas y comentarios

A lo largo de la ejecución en seco, se encuentran con bordes ásperos, lo que se espera mientras se trabaja con una nueva función. Capture y comparta cualquier problema con el contacto del programa de Adobe mediante la plantilla de comentarios proporcionada durante la incorporación.

Requisitos previos

Cuentas y acceso

Herramientas

Se requiere una tienda de Edge Delivery Services (EDS) para la validación funcional. Necesitará lo siguiente:

Instale la plantilla de la tienda en una carpeta vacía y seleccione la instancia de ACCS cuando se le solicite:

aio commerce extensibility app-setup -s aem-boilerplate-commerce -n storefront

Inicia la tienda:

cd storefront
npm run start

Abrir Commerce Developer Agent

Caso de uso 1: gancho web de unidades máximas del carro de compras

Este caso de uso valida los límites de cantidad del carro de compras antes de agregar un producto, mediante un webhook sincrónico de Commerce.

Fase de modelo

Escriba el siguiente mensaje y haga clic en Generar modelo:

Add a validation webhook that runs before a product is added to the cart.

Use the Commerce webhook method observer.sales_quote_item_save_before (type before) — do not use
observer.checkout_cart_product_add_before, observer.sales_quote_add_item, or any other event.

Calculate the total by summing all quote line quantities and the quantity of the current item.
If the same SKU already exists in the quote, exclude its existing quantity to avoid double-counting.

If the total is greater than the maximum allowed, block the add and show:
"You have reached the maximum amount of items."

The maximum allowed must be configurable in Commerce Admin as max_cart_units, with default 10.

Map payload fields using name and source properties:
- name: item.qty, source: data.item.qty
- name: item.sku, source: data.item.sku
- name: quote, source: context_checkout_session.get_quote[items.qty,items.sku]

Set required: true and fallback_error_message: "You have reached the maximum amount of items."
on the webhook config.

When blocking the add, do not use exceptionOperation, because it serializes exceptionClass as class.
Instead, manually return an exception operation response whose body includes type:
{
  "op": "exception",
  "message": "You have reached the maximum amount of items.",
  "type": "\\Magento\\Framework\\GraphQl\\Exception\\GraphQlInputException"
}

Refine el modelo introduciendo detalles en el cuadro de chat o haciendo clic en una de las píldoras encima del cuadro de chat (Suposiciones de desafío, Encuentre lagunas de diseño, etc.). Una vez que esté satisfecho, haga clic en Aprobar plan para continuar.

Fase de desarrollo

El agente pasa a la fase de desarrollo y comienza a aprovisionar el espacio de trabajo.

Una vez aprovisionado, el agente muestra una lista de tareas de implementación y comienza a crear.

Una vez que esté satisfecho con el código, haga clic en la ficha Integraciones para continuar.

Configuración de integraciones

Conectar o crear un espacio de trabajo de App Builder

Para crear o conectar un proyecto de App Builder, siga las instrucciones que aparecen en pantalla.

Si se conecta a un espacio de trabajo existente, asegúrese de que tenga:

Si crea un nuevo espacio de trabajo, agregue manualmente la API Adobe Commerce as a Cloud Service.

Haga clic en Siguiente para continuar.

Conectarse a Commerce

Seleccione la instancia de ACCS de la lista o escriba la dirección URL en el campo URL base de REST de Commerce y, a continuación, haga clic en Conectar la instancia de Commerce. Haga clic en Siguiente para continuar.

Conectarse a GitHub

Conecte el espacio de trabajo a un repositorio de GitHub introduciendo la URL del repositorio y utilizando la aplicación de GitHub o un token de acceso personal. Haga clic en Siguiente para continuar.

Configurar variables de entorno

Complete las variables de entorno que requiera el proyecto.

Implementar

Haga clic en Desarrollo para regresar a la fase de desarrollo y, a continuación, solicite al agente que realice el despliegue en el campo de solicitud.

Confirme la implementación.

Asociar la aplicación en la administración de aplicaciones

Instalación y configuración en Administración de aplicaciones

Pruebas funcionales

Caso de uso 2: retención de pedido de alto valor y código de verificación

Vuelva a la fase Modelo para comenzar este caso de uso.

Fase de modelo

Escriba el siguiente mensaje y haga clic en Generar modelo:

Add a Commerce event priority subscription to `plugin.sales.api.order_management.place`.

Extract `entity_id` and `grand_total` from the Commerce event payload using event `fields` in `app.commerce.config.ts`.

Important: the runtime action receives a CloudEvents-shaped payload. For Commerce eventing extracted fields,
parse them from `params.data.value`, not directly from `params.data`. The handler must use:
- `params.data.value.entity_id`
- `params.data.value.grand_total`

When `grand_total` is greater than `order_hold_threshold`:
1. Generate a verification code locally.
2. Put the order on hold with state and status `holded`.
When putting the order on hold, save the verification code using `custom_attributes`, not `extension_attributes`.
The Commerce `POST V1/orders` payload should include:
{
  "entity": {
    "entity_id": <entity_id>,
    "state": "holded",
    "status": "holded",
    "custom_attributes": [
      {
        "attribute_code": "<hold_verification_attribute>",
        "value": "<verification_code>"
      }
    ]
  }
}
3. Save the verification code via a `POST V1/orders` Commerce REST API call.

Make these configurable in Commerce Admin:
- `order_hold_threshold`, default `500`
- `hold_verification_attribute`, default `lab_verification_code`

Validate inputs before use:
- `entity_id` must be a positive integer.
- `grand_total` must be a non-negative number.

Refine el modelo según sea necesario y luego haga clic en Aprobar plan para continuar.

Desarrollar, implementar, asociar e instalar

Siga el mismo proceso utilizado en el Caso de uso 1 para pasar de los requisitos a una aplicación instalada; no es necesario volver a configurar las integraciones.

Pruebas funcionales

Caso de uso 3: archivado basado en eventos para pedidos retenidos

Vuelva a la fase Modelo para comenzar este caso de uso.

Fase de modelo

Escriba el siguiente mensaje y haga clic en Generar modelo:

When an order is saved with state holded, archive it to external storage and
record a reference that can be looked up later by order ID.

Add an event priority subscription on observer.sales_order_save_after, filtered to fire only when
state equals holded. From the event payload, extract:
- `entity_id`
- `payment.amount_ordered`
- `custom_attributes` (to read the `lab_verification_code` attribute set in Step 3)

The event handler must:
1. Persist the order details to the `held_orders` App Builder DB collection:
{
  "order_id": <entity_id>,
  "grand_total": <payment.amount_ordered>,
  "verification_code": <lab_verification_code>,
  "archived_at": <ISO timestamp>
}
2. Ensure the record can be looked up later by order ID.

The `held_orders` collection must exist before the handler runs:
- Provision persistent App Builder Database Storage in region `amer`.
- Create the collection during app installation.
- Create a unique index on `order_id` during installation.
- Drop the whole `held_orders` collection when the app is uninstalled.

Register the event handler separately from the existing cart validation webhook and high-value order hold action:
- runtime action: `order-archive/archive-held-order`
- non-web action
- `include-ims-credentials: true` on the archive action and the installation action

Follow the `commerce-app-storage` skill for DB auth, installation steps, and ext.config wiring.
Do not use custom IMS credential normalization or `Core.AuthClient.generateAccessToken`.

Refine el modelo según sea necesario y luego haga clic en Aprobar plan para continuar.

Desarrollar, implementar, asociar e instalar

Siga el mismo proceso utilizado en los casos de uso anteriores para pasar de los requisitos a una aplicación instalada; no es necesario volver a configurar las integraciones.

Pruebas funcionales

Resolución de problemas

Si la aplicación generada por CDA no se comporta como se espera o produce errores, pídale al agente que solucione los problemas desde la fase de desarrollo.

Cuanto más concreto sea el informe, mejor podrá el agente diagnosticar el problema.

Pasos opcionales

Descargar el código

Para seguir refinando o editando en su IDE favorito, descargue el código generado por CDA haciendo clic en el icono de descarga en la barra de herramientas del Explorador de fase de desarrollo. Seleccione una carpeta de destino, haga clic en Guardar y luego descomprima el paquete del espacio de trabajo.

Para utilizar las mismas habilidades de agente que utiliza CDA, instálelas en la carpeta del proyecto:

npx skills add adobe/aio-commerce-sdk --skill commerce-app-init -y && \
npx skills add adobe/aio-commerce-sdk --skill commerce-app-eventing -y && \
npx skills add adobe/aio-commerce-sdk --skill commerce-app-webhooks -y && \
npx skills add adobe/aio-commerce-sdk --skill commerce-app-business-config -y && \
npx skills add adobe/aio-commerce-sdk --skill commerce-app-storage -y && \
npx skills add adobe/skills --skill appbuilder-project-init -y

A continuación, inicie el IDE o CLI y comience a solicitar ayuda.

Adjuntar contexto mediante archivo o vínculo

En lugar de preguntar directamente en las fases de modelo o desarrollo, puede adjuntar un contexto mediante un archivo de texto o un vínculo:

Problemas y soluciones conocidos

La fase de modelo no genera tareas

Para desbloquearlo y continuar, empuje al agente a generar tareas.

Los botones para insertar y extraer de GitHub no funcionan

En su lugar, descargue el archivo ZIP del proyecto desde la fase Desarrollo.

Tutoriales relacionados

Guía tutorial, casos de uso y problemas conocidos con soluciones alternativas

Recursos adicionales