Adobe Commerce Developer Agent App Builder dry run

A hands-on walkthrough for building, deploying, and testing Commerce extensibility use cases with the Adobe Commerce Developer Agent (CDA). This dry run covers three use cases: a cart quantity limit webhook, a high-value order hold, and event-driven archival for held orders, from blueprint through functional testing.

Getting started

How to report issues and feedback

Throughout the dry run, you encounter rough edges — that’s expected while working with a new feature. Capture and share any issues with your Adobe program contact using the feedback template provided during onboarding.

Prerequisites

Accounts and access

Tools

An Edge Delivery Services (EDS) storefront is required for functional validation. You’ll need:

Install the storefront boilerplate in an empty folder, selecting your ACCS instance when prompted:

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

Start the storefront:

cd storefront
npm run start

Opening the Commerce Developer Agent

Use case 1: cart maximum units webhook

This use case validates cart quantity limits before a product is added, using a synchronous Commerce webhook.

Blueprint stage

Enter the following prompt and click Generate 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"
}

Refine the blueprint by entering details in the chat box or by clicking one of the pills above the chat box (Challenge assumptions, Find design gaps, etc.). Once you’re satisfied, click Approve plan to move forward.

Develop stage

The agent transitions to the Develop stage and begins provisioning the workspace.

Once provisioned, the agent shows a list of implementation tasks and starts building.

Once satisfied with the code, click the Integrations tab to move forward.

Configure integrations

Connect or create an App Builder workspace

To create or connect an App Builder project, follow the on-screen instructions.

If connecting to an existing workspace, make sure it has:

If creating a new workspace, manually add the Adobe Commerce as a Cloud Service API.

Click Next to continue.

Connect to Commerce

Select your ACCS instance from the list, or enter the URL in the Commerce REST Base URL field, then click Connect Commerce instance. Click Next to continue.

Connect to GitHub

Connect the workspace to a GitHub repository by entering the repository URL and either using the GitHub App or a personal access token. Click Next to continue.

Configure environment variables

Fill in any environment variables required by the project.

Deploy

Click Develop to return to the develop stage, then ask the agent to deploy in the prompt field.

Confirm the deployment.

Associate the app in App Management

Install and configure in App Management

Functional testing

Use case 2: high-value order hold and verification code

Navigate back to the Blueprint stage to begin this use case.

Blueprint stage

Enter the following prompt and click Generate 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.

Refine the blueprint as needed, then click Approve plan to move forward.

Develop, deploy, associate, and install

Follow the same process used in Use case 1 to move from requirements to an installed application — there’s no need to reconfigure integrations.

Functional testing

Use case 3: event-driven archival for held orders

Navigate back to the Blueprint stage to begin this use case.

Blueprint stage

Enter the following prompt and click Generate 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`.

Refine the blueprint as needed, then click Approve plan to move forward.

Develop, deploy, associate, and install

Follow the same process used in the previous use cases to move from requirements to an installed application — there’s no need to reconfigure integrations.

Functional testing

Troubleshooting

If the application generated by CDA isn’t behaving as expected or is producing errors, ask the agent to troubleshoot from the Develop stage.

The more concrete the report, the better the agent can diagnose the issue.

Optional steps

Download the code

To continue refining or editing in your favorite IDE, download the code generated by CDA by clicking the download icon on the Develop stage Explorer toolbar. Select a destination folder and click Save, then unzip the workspace package.

To use the same agent skills CDA uses, install them in your project folder:

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

Then start your IDE or CLI and begin prompting.

Attach context via file or link

Instead of prompting directly in the Blueprint or Develop stages, you can attach context using a text file or a link:

Known issues and workarounds

The Blueprint stage does not generate tasks

To get unblocked and continue, nudge the agent to generate tasks.

The buttons to push to and pull from GitHub are not functional

Instead, download the project ZIP file from the Develop stage.

Related tutorials

Tutorial guide, use cases and known issues with workarounds

Additional resources