Adobe Commerce Developer Agent App Builder - Probelauf

Eine praktische Anleitung zum Erstellen, Bereitstellen und Testen von Anwendungsfällen für die Erweiterbarkeit von Commerce mit dem Adobe Commerce Developer Agent (CDA). Dieser Probelauf deckt drei Anwendungsfälle ab: einen Webhook zur Begrenzung der Warenkorbmenge, einen hochwertigen Auftragsbestand und eine ereignisgesteuerte Archivierung für gespeicherte Aufträge, von der Blueprint bis hin zu Funktionstests.

Erste Schritte

Melden von Problemen und Feedback

Während des gesamten Trockenlaufs stoßen Sie auf raue Kanten - das wird erwartet, wenn Sie mit einer neuen Funktion arbeiten. Erfassen und teilen Sie alle Probleme mit Ihrem Adobe-Programmkontakt mithilfe der Feedback-Vorlage, die beim Onboarding bereitgestellt wurde.

Voraussetzungen

Konten und Zugriff

Tools

Für die funktionale Validierung ist eine Edge Delivery Services (EDS)-Storefront erforderlich. Sie benötigen:

Installieren Sie die Storefront-Textvorlage in einem leeren Ordner und wählen Sie Ihre ACS-Instanz aus, wenn Sie dazu aufgefordert werden:

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

Starten Sie die Storefront:

cd storefront
npm run start

Öffnen des Commerce Developer Agent

Anwendungsfall 1: Webhook für maximale Einheiten im Warenkorb

In diesem Anwendungsbeispiel werden mithilfe eines synchronen Commerce-Webhooks die Mengenbeschränkungen für den Warenkorb validiert, bevor ein Produkt hinzugefügt wird.

Blueprint-Phase

Geben Sie die folgende Eingabeaufforderung ein und klicken Sie auf Blueprint erstellen:

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

Verfeinern Sie den Blueprint, indem Sie Details in das Chat-Feld eingeben oder auf eine der Pillen über dem Chat-Feld klicken (Challenge-Annahmen, Designlücken finden usw.). Wenn Sie zufrieden sind, klicken Sie auf Plan genehmigen, um fortzufahren.

Stadium entwickeln

Der Agent wechselt in die Entwicklungsphase und beginnt mit der Bereitstellung des Arbeitsbereichs.

Nach der Bereitstellung zeigt der Agent eine Liste der Implementierungsaufgaben an und beginnt mit der Erstellung.

Wenn Sie mit dem Code zufrieden sind, klicken Sie auf die Registerkarte Integrationen, um fortzufahren.

Integrationen konfigurieren

Verbinden oder Erstellen eines App Builder-Arbeitsbereichs

Um ein App Builder-Projekt zu erstellen oder zu verbinden, folgen Sie den Anweisungen auf dem Bildschirm.

Wenn Sie eine Verbindung zu einem vorhandenen Arbeitsbereich herstellen, stellen Sie sicher, dass Folgendes zutrifft:

Wenn Sie einen neuen Arbeitsbereich erstellen, fügen Sie die Adobe Commerce as a Cloud Service-API manuell hinzu.

Klicken Sie Weiter um fortzufahren.

Verbindung zu Commerce herstellen

Wählen Sie Ihre ACS-Instanz aus der Liste aus oder geben Sie die URL in das Feld Commerce REST-Basis-URL ein und klicken Sie dann auf Commerce-Instanz verbinden. Klicken Sie Weiter um fortzufahren.

Verbindung zu GitHub herstellen

Verbinden Sie den Arbeitsbereich mit einem GitHub-Repository, indem Sie die Repository-URL eingeben und entweder die GitHub-App oder ein persönliches Zugriffstoken verwenden. Klicken Sie Weiter um fortzufahren.

Konfigurieren von Umgebungsvariablen

Füllen Sie alle für das Projekt erforderlichen Umgebungsvariablen aus.

Bereitstellen

Klicken Sie Entwickeln, um zur Entwicklungsphase zurückzukehren, und bitten Sie dann den Agenten, die Bereitstellung im Eingabeaufforderungsfeld vorzunehmen.

Bestätigen Sie die Bereitstellung.

App in App Management verknüpfen

Installieren und Konfigurieren von in App Management

Funktionstests

Anwendungsfall 2: Hochwertiger Auftragssperre- und Verifizierungs-Code

Navigieren Sie zurück zum Blueprint-Schritt, um diesen Anwendungsfall zu starten.

Blueprint-Phase

Geben Sie die folgende Eingabeaufforderung ein und klicken Sie auf Blueprint erstellen:

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.

Verfeinern Sie den Blueprint nach Bedarf und klicken Sie dann auf Plan genehmigen, um fortzufahren.

Entwickeln, Bereitstellen, Verknüpfen und Installieren

Folgen Sie dem gleichen Prozess wie in Anwendungsfall 1, um von den Anforderungen zu einer installierten Anwendung zu wechseln - es ist nicht erforderlich, Integrationen neu zu konfigurieren.

Funktionstests

Anwendungsfall 3: Ereignisgesteuerte Archivierung für ausgeführte Aufträge

Navigieren Sie zurück zum Blueprint-Schritt, um diesen Anwendungsfall zu starten.

Blueprint-Phase

Geben Sie die folgende Eingabeaufforderung ein und klicken Sie auf Blueprint erstellen:

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

Verfeinern Sie den Blueprint nach Bedarf und klicken Sie dann auf Plan genehmigen, um fortzufahren.

Entwickeln, Bereitstellen, Verknüpfen und Installieren

Folgen Sie dem gleichen Prozess wie in den vorherigen Anwendungsfällen, um von den Anforderungen zu einer installierten Anwendung zu wechseln - es ist nicht erforderlich, Integrationen neu zu konfigurieren.

Funktionstests

Fehlerbehebung

Wenn sich die von der geräteübergreifenden Analyse generierte Anwendung nicht wie erwartet verhält oder Fehler verursacht, bitten Sie den Agenten, die Fehlerbehebung in der Entwicklungsphase durchzuführen.

Je konkreter der Bericht, desto besser kann der Agent das Problem diagnostizieren.

Optionale Schritte

Code herunterladen

Um mit der Verfeinerung oder Bearbeitung in Ihrer bevorzugten IDE fortzufahren, laden Sie den von CDA generierten Code herunter, indem Sie auf der Symbolleiste des Explorers für die Entwicklungsphase auf das Symbol Herunterladen klicken. Wählen Sie einen Zielordner aus, klicken Sie auf Speichern und entpacken Sie dann das Arbeitsbereich-Paket.

Um dieselben Agentenfähigkeiten, die CDA verwendet, zu verwenden, installieren Sie diese in Ihrem Projektordner:

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

Starten Sie dann Ihre IDE oder CLI und beginnen Sie mit der Eingabeaufforderung.

Kontext über Datei oder Link anhängen

Anstatt direkt im Blueprint- oder Entwicklungs-Schritt dazu aufzufordern, können Sie den Kontext mithilfe einer Textdatei oder eines Links anhängen:

Bekannte Probleme und Problemumgehungen

Die Blueprint-Phase generiert keine Aufgaben

Um die Blockierung aufzuheben und fortzufahren, bewegen Sie den Agenten, Aufgaben zu generieren.

Die Schaltflächen zum Pushen und Abrufen von GitHub funktionieren nicht

Laden Sie stattdessen die ZIP-Projektdatei aus der Entwicklungsphase herunter.

Verwandte Tutorials

Tutorial, Anwendungsfälle und bekannte Probleme mit Workarounds

Zusätzliche Ressourcen