Execução a seco do Adobe Commerce Developer Agent App Builder

Uma apresentação prática para criar, implantar e testar casos de uso de extensibilidade do Commerce com o Adobe Commerce Developer Agent (CDA). Essa simulação abrange três casos de uso: um webhook de limite de quantidade do carrinho, uma retenção de pedido de alto valor e arquivamento orientado por eventos para pedidos suspensos, desde o blueprint até o teste funcional.

Introdução

Como relatar problemas e feedback

Durante todo o período de seca, você encontra bordas ásperas — o que é esperado ao trabalhar com um novo recurso. Capture e compartilhe quaisquer problemas com o contato do programa do Adobe usando o modelo de feedback fornecido durante a integração.

Pré-requisitos

Contas e acesso

Ferramentas

Uma loja Edge Delivery Services (EDS) é necessária para a validação funcional. Você precisará de:

Instale a placa-mãe da loja em uma pasta vazia, selecionando a instância ACCS quando solicitado:

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

Iniciar a loja:

cd storefront
npm run start

Abrir o Commerce Developer Agent

Caso de uso 1: webhook de unidades máximas do carrinho

Esse caso de uso valida os limites de quantidade do carrinho antes que um produto seja adicionado, usando um webhook síncrono do Commerce.

Estágio de blueprint

Digite o prompt a seguir e clique em Gerar 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 o blueprint inserindo detalhes na caixa de chat ou clicando em uma das pílulas acima da caixa de chat (Desafiar hipóteses, Localizar lacunas de design etc.). Quando estiver satisfeito, clique em Aprovar plano para prosseguir.

Estágio de desenvolvimento

O agente faz a transição para o estágio Desenvolver e começa a provisionar o espaço de trabalho.

Depois de provisionado, o agente mostra uma lista de tarefas de implementação e começa a criar.

Depois de satisfeito com o código, clique na guia Integrações para avançar.

Configurar integrações

Conectar ou criar um espaço de trabalho do App Builder

Para criar ou conectar um projeto do App Builder, siga as instruções na tela.

Se estiver se conectando a um espaço de trabalho existente, verifique se ele tem:

Ao criar um novo espaço de trabalho, adicione manualmente a API do Adobe Commerce as a Cloud Service.

Clique em Avançar para continuar.

Conectar-se ao Commerce

Selecione a instância do ACCS na lista ou insira a URL no campo URL da Base REST do Commerce e clique em Conectar instância do Commerce. Clique em Avançar para continuar.

Conectar-se ao GitHub

Conecte o espaço de trabalho a um repositório GitHub inserindo o URL do repositório e usando o aplicativo GitHub ou um token de acesso pessoal. Clique em Avançar para continuar.

Configurar variáveis de ambiente

Preencha todas as variáveis de ambiente exigidas pelo projeto.

Implantar

Clique em Desenvolver para retornar ao estágio de desenvolvimento e solicitar que o agente implante no campo de prompt.

Confirme a implantação.

Associar o aplicativo no Gerenciamento de aplicativos

Instalar e configurar no Gerenciamento de aplicativos

Teste funcional

Caso de uso 2: retenção de ordem de alto valor e código de verificação

Volte para o estágio Blueprint para iniciar este caso de uso.

Estágio de blueprint

Digite o prompt a seguir e clique em Gerar 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 o blueprint conforme necessário, em seguida, clique em Aprovar plano para prosseguir.

Desenvolver, implantar, associar e instalar

Siga o mesmo processo usado no Caso de uso 1 para passar dos requisitos para um aplicativo instalado — não há necessidade de reconfigurar as integrações.

Teste funcional

Caso de uso 3: arquivamento orientado por eventos para pedidos retidos

Volte para o estágio Blueprint para iniciar este caso de uso.

Estágio de blueprint

Digite o prompt a seguir e clique em Gerar 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 o blueprint conforme necessário, em seguida, clique em Aprovar plano para prosseguir.

Desenvolver, implantar, associar e instalar

Siga o mesmo processo usado nos casos de uso anteriores para migrar dos requisitos para um aplicativo instalado — não há necessidade de reconfigurar as integrações.

Teste funcional

Solução de problemas

Se o aplicativo gerado pelo CDA não estiver se comportando como esperado ou estiver produzindo erros, peça ao agente para solucionar os problemas no estágio de desenvolvimento.

Quanto mais concreto for o relatório, melhor o agente poderá diagnosticar o problema.

Etapas opcionais

Baixar o código

Para continuar refinando ou editando em seu IDE favorito, baixe o código gerado pelo CDA clicando no ícone de download na barra de ferramentas do explorador de estágio de desenvolvimento. Selecione uma pasta de destino, clique em Salvar e descompacte o pacote do espaço de trabalho.

Para usar as mesmas habilidades do agente que o CDA usa, instale-as na pasta do projeto:

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

Em seguida, inicie o IDE ou CLI e comece a solicitar.

Anexar contexto via arquivo ou link

Em vez de solicitar diretamente nos estágios Blueprint ou Desenvolver, é possível anexar contexto usando um arquivo de texto ou um link:

Problemas conhecidos e soluções alternativas

O estágio de blueprint não gera tarefas

Para desbloquear e continuar, mova o agente para gerar tarefas.

Os botões para enviar e receber do GitHub não estão funcionais

Em vez disso, baixe o arquivo ZIP do projeto no estágio Desenvolver.

Tutoriais relacionados

Guia tutorial, casos de uso e problemas conhecidos com soluções alternativas

Recursos adicionais