Esecuzione a secco di Adobe Commerce Developer Agent App Builder

Procedura dettagliata per la creazione, la distribuzione e il test di casi d’uso di estensibilità per Commerce con Adobe Commerce Developer Agent (CDA). Questa esecuzione a secco copre tre casi d’uso: un webhook di limite della quantità del carrello, un blocco dell’ordine di valore elevato e l’archiviazione basata su eventi per gli ordini conservati, dalla blueprint al test funzionale.

Introduzione

Come segnalare i problemi e fornire feedback

Durante la fase di asciugatura, si incontrano spigoli sgrossati, come previsto durante l’utilizzo di una nuova feature. Acquisisci e condividi eventuali problemi con il contatto del programma Adobe utilizzando il modello di feedback fornito durante l’onboarding.

Prerequisiti

Account e accesso

Strumenti

Per la convalida funzionale è necessaria una vetrina Edge Delivery Services (EDS). Sono necessari:

Installa la boilerplate di storefront in una cartella vuota, selezionando la tua istanza ACS quando richiesto:

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

Avvia la vetrina:

cd storefront
npm run start

Apertura di Commerce Developer Agent

Caso d’uso 1: webhook delle unità massime del carrello

Questo caso d’uso convalida i limiti di quantità del carrello prima che venga aggiunto un prodotto, utilizzando un webhook Commerce sincrono.

Fase blueprint

Immetti il seguente prompt e fai clic su Genera blueprint:

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"
}

Affina il blueprint immettendo i dettagli nella casella di chat o facendo clic su una delle pillole sopra la casella di chat (Sfida presupposti, Trova spazi vuoti di progettazione, ecc.). Una volta ottenuti i risultati desiderati, fare clic su Approva piano per procedere.

Fase di sviluppo

L’agente passa alla fase di sviluppo e inizia a eseguire il provisioning dell’area di lavoro.

Una volta eseguito il provisioning, l’agente mostra un elenco di attività di implementazione e inizia a generare.

Una volta completato il codice, fai clic sulla scheda Integrazioni per andare avanti.

Configurare le integrazioni

Connetti o crea un’area di lavoro App Builder

Per creare o collegare un progetto App Builder, segui le istruzioni visualizzate.

Se ti connetti a un’area di lavoro esistente, assicurati che:

Se crei una nuova area di lavoro, aggiungi manualmente l’API Adobe Commerce as a Cloud Service.

Fai clic su Avanti per continuare.

Connetti a Commerce

Seleziona l’istanza di ACCS dall’elenco oppure immetti l’URL nel campo URL base REST Commerce, quindi fai clic su Connetti istanza di Commerce. Fai clic su Avanti per continuare.

Connetti a GitHub

Connetti l’area di lavoro a un archivio GitHub immettendo l’URL dell’archivio e utilizzando l’app GitHub o un token di accesso personale. Fai clic su Avanti per continuare.

Configurare le variabili di ambiente

Inserisci le variabili di ambiente richieste dal progetto.

Distribuisci

Fai clic su Sviluppa per tornare alla fase di sviluppo, quindi chiedi all’agente di distribuire nel campo del prompt.

Conferma la distribuzione.

Associa l’app a Gestione app

Installare e configurare in Gestione app

Test funzionali

Caso d’uso 2: blocco di ordini di valore elevato e codice di verifica

Torna alla fase Blueprint per iniziare questo caso d’uso.

Fase blueprint

Immetti il seguente prompt e fai clic su Genera blueprint:

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.

Ridefinisci il blueprint in base alle esigenze, quindi fai clic su Approva piano per andare avanti.

Sviluppo, distribuzione, associazione e installazione

Segui lo stesso processo utilizzato nel caso d’uso 1 per passare dai requisiti a un’applicazione installata, senza dover riconfigurare le integrazioni.

Test funzionali

Caso d’uso 3: archiviazione basata su eventi per gli ordini conservati

Torna alla fase Blueprint per iniziare questo caso d’uso.

Fase blueprint

Immetti il seguente prompt e fai clic su Genera blueprint:

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`.

Ridefinisci il blueprint in base alle esigenze, quindi fai clic su Approva piano per andare avanti.

Sviluppo, distribuzione, associazione e installazione

Segui lo stesso processo utilizzato nei casi d’uso precedenti per passare dai requisiti a un’applicazione installata, senza dover riconfigurare le integrazioni.

Test funzionali

Risoluzione dei problemi

Se l’applicazione generata da CDA non si comporta come previsto o genera errori, chiedi all’agente di risolvere i problemi dalla fase Develop.

Più concreto è il rapporto, migliore sarà la capacità dell’agente di diagnosticare il problema.

Passaggi facoltativi

Scarica il codice

Per continuare a perfezionare o modificare l’IDE preferito, scarica il codice generato da CDA facendo clic sull’icona Scarica sulla barra degli strumenti di Esplora risorse di Develop stage. Seleziona una cartella di destinazione e fai clic su Salva, quindi decomprimi il pacchetto dell’area di lavoro.

Per utilizzare le stesse abilità agente utilizzate da CDA, installale nella cartella dei progetti:

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

Quindi avvia IDE o CLI e inizia a visualizzare la richiesta.

Allega contesto tramite file o collegamento

Invece di visualizzare le istruzioni direttamente nelle fasi Blueprint o Sviluppo, puoi allegare il contesto utilizzando un file di testo o un collegamento:

Problemi noti e soluzioni alternative

La fase blueprint non genera attività

Per sbloccarsi e continuare, spostare l’agente per generare attività.

I pulsanti per il push e il pull da GitHub non sono funzionanti

Scarica il file ZIP del progetto dalla fase di sviluppo.

Tutorial correlati

Guida alle esercitazioni, casi d’uso e problemi noti con soluzioni alternative

Risorse aggiuntive