Criar uma ação do zero create-action-from-scratch

Adicione um recurso que a plataforma não criou. Defina a ação em LLM Apps, grave o manipulador no repositório vinculado e adicione um widget, se necessário.

Neste guia: Aprenda a definir uma ação, implementar seu manipulador e conectar um widget opcional. Teste a ação localmente, implante o aplicativo e tente a ação em uma plataforma LLM compatível.

Para seu primeiro aplicativo, comece com Configuração de infraestrutura e depois Criar ações. O guia de ações Criar explica a geração automática de um site e a criação manual.

Antes de começar

Você precisa:

Planejar a ação

Projete cada ação em torno de uma tarefa de usuário limpa. Antes de abrir a interface do usuário, defina:

Por exemplo, use este plano para uma ação Pesquisar Produtos:

Intent: Find products matching a category or search phrase
Inputs:
  category: optional string
  query: optional string
Result:
  content: text summary
  structuredContent: products and total count
Behavior: read-only, idempotent, open-world
Widget: product cards

Mantenha as tarefas relacionadas, mas diferentes, separadas. Use ações separadas para pesquisa de produto e compra de produto porque as tarefas têm diferentes requisitos de entrada, riscos e confirmação.

Criar os metadados da ação

Abra o aplicativo e selecione Ações e, em seguida, Criar Ação.

A caixa de diálogo Criar nova ação tem quatro guias: Detalhes da ação, Detalhes do widget LLM, Insights do aplicativo e Extensões de ChatGPT. A caixa de diálogo é aberta em Detalhes da ação. O editor de ação salva usa as mesmas guias.

As configurações opcionais de extensões ChatGPT permitem que as pessoas abram o aplicativo diretamente, usem um visualizador de arquivo personalizado ou encontrem recursos no compositor em clientes compatíveis. Configure-os depois que o comportamento correspondente do widget e da ação estiver pronto. Consulte Configurar extensões ChatGPT.

Inserir as informações da ação e os parâmetros de entrada

Em Informações de ação, digite:

A caixa de diálogo deriva um Identificador de código do nome, como search-products. O identificador é corrigido após a criação e deve ser exclusivo no aplicativo. Use o identificador exato para a pasta do manipulador.

Uma descrição útil é específica:

Search the product catalog by category or keyword. Returns matching
products with their names, prices, categories, and image URLs.

Evite descrições vagas como Obtém informações sobre o produto. A plataforma LLM usa a descrição para escolher entre as ações.

Em Parâmetros de entrada, selecione Adicionar parâmetro uma vez para cada valor aceito pelo manipulador. Para cada parâmetro, insira:

Para Pesquisar Produtos:

category
  Type: String
  Required: No
  Description: Product category used to narrow the catalog.

query
  Type: String
  Required: No
  Description: Product name or search phrase.

Use nomes de parâmetros estáveis. Alterar um nome também requer alterar o manipulador e seus testes.

Definir as configurações do LLM

Expandir configurações LLM. A seção é recolhida por padrão.

Em Anotações, selecione somente as dicas que são verdadeiras para a ação:

Por exemplo, a pesquisa de produtos normalmente é somente leitura, idempotente e de mundo aberto.

Em Metadados de OpenAI, insira mensagens curtas exibidas enquanto a ação é executada e, após sua conclusão, até 64 caracteres cada:

Invoking status text: Searching products...
Invoked status text: Products found

Em Visibilidade:

A Visibilidade não escolhe o tipo de widget. Para uma ação somente texto, selecione Nenhuma interface do usuário interativa em Detalhes do widget LLM > Tipo de widget.

Configurar Application Insights configure-analytics

Abra o Application Insights. Por padrão, a opção Coletar intenção de usuário está selecionada: a plataforma LLM cria um resumo curto e anônimo do que o usuário estava tentando realizar quando a ação foi executada.

Se você configurar seu próprio Adobe Analytics ou Customer Journey Analytics, a intenção do usuário também será enviada para lá. Consulte Configurar Adobe Analytics e Customer Journey Analytics.

Revise as instruções abaixo da caixa de seleção, que orientam o resumo. Limite-as a intenções não confidenciais e anônimas e descreva sua coleta de dados na política de privacidade. As instruções aceitam até 2.000 caracteres Limpe Coletar intenção de usuário para não coletar resumo.

Para obter definições completas de campo, consulte Campos de ação e widget.

Configurar o widget

Abra Detalhes do Widget do LLM. Para uma ação somente texto, selecione Nenhuma interface do usuário interativa em Tipo de widget e ignore as configurações restantes do widget.

Em Informações do widget, configure:

A descrição do widget é diferente da descrição da ação:

LLM Apps aplica a descrição do widget como metadados do componente. Não retorne a descrição do manipulador.

Expanda URLs de modelo e insira:

Os URLs típicos são:

Script URL:
https://main--<repo>--<owner>.aem.live/scripts/aem-embed.js

Widget URL:
https://main--<repo>--<owner>.aem.live/<widget-page>

Em Configuração da CSP, adicione apenas as origens que o dispositivo precisa para ativos e solicitações de rede. Um widget que carrega recursos externos pode não ser renderizado se o CSP estiver incompleto.

Se a página do projeto ou widget do EDS ainda não existir, conclua Trazer seu próprio projeto EDS e retorne à ação.

Salvar a ação

Selecione Criar nova ação. A ação aparece na página Ações com um selo Não implantado.

Salvar cria os metadados, mas a ação ainda precisa de um manipulador.

Quando você reabre a ação salva, o editor mostra as mesmas guias. Para salvar edições posteriores, selecione Salvar alterações.

Implementar o manipulador

Clonar o repositório do manipulador vinculado e instalar suas dependências:

npm install

Criar:

actions/
└── search-products/
    └── index.js

O nome da pasta deve corresponder ao identificador de código da ação mostrado no editor de ações.

Para obter o contrato de resultado completo e a relação manipulador-widget, consulte Personalizar um manipulador gerado.

Contrato do manipulador

Exportar uma função assíncrona:

module.exports = async (args) => {
  return {
    content: [
      { type: 'text', text: 'Response for the LLM platform.' }
    ],
    structuredContent: {
      // Data for the widget.
    }
  };
};

O manipulador recebe os parâmetros definidos na interface do usuário do.

Retornar content

A plataforma LLM lê content como fallback de texto:

content: [
  { type: 'text', text: 'Found 3 matching products.' }
]

Sempre retornar content úteis, mesmo quando a ação tiver um widget.

Retornar structuredContent

O widget consome structuredContent como um objeto simples:

structuredContent: {
  products: [
    { id: 'P-100', name: 'Product A', price: '$20' }
  ],
  total: 1
}

A forma deve corresponder ao que o bloco EDS lê de bridge.toolResult.

Conectar uma API

Manter chamadas de API no manipulador do lado do servidor. Este exemplo chama uma API de produto pública. Configure a origem HTTPS da API em uma variável de aplicativo chamada PRODUCT_API_ORIGIN. O exemplo aceita os parâmetros query e category definidos acima, requer pelo menos um parâmetro e não requer credenciais.

const { getVariable } = require('@adobe/llm-apps-runtime');

module.exports = async ({ query = '', category = '' } = {}, extra) => {
  const normalizedQuery = typeof query === 'string' ? query.trim() : '';
  const normalizedCategory = typeof category === 'string' ? category.trim() : '';
  if (typeof query !== 'string' || typeof category !== 'string'
      || (!normalizedQuery && !normalizedCategory)
      || normalizedQuery.length > 200 || normalizedCategory.length > 100) {
    return {
      isError: true,
      content: [{ type: 'text', text: 'Enter a valid product search.' }],
      structuredContent: { products: [], total: 0 }
    };
  }

  const apiOrigin = getVariable(extra, 'PRODUCT_API_ORIGIN');
  if (!apiOrigin) {
    throw new Error('Product API configuration is unavailable.');
  }

  const origin = new URL(apiOrigin);
  if (origin.protocol !== 'https:') {
    throw new Error('Product API configuration must use HTTPS.');
  }

  const url = new URL('/v1/products', origin);
  if (normalizedQuery) {
    url.searchParams.set('query', normalizedQuery);
  }
  if (normalizedCategory) {
    url.searchParams.set('category', normalizedCategory);
  }

  const response = await fetch(url, {
    signal: AbortSignal.timeout(8000)
  });

  if (!response.ok) {
    throw new Error('Product service request failed.');
  }

  const payload = await response.json();
  if (!payload || !Array.isArray(payload.products)
      || !payload.products.every((product) =>
        product
        && typeof product.id === 'string'
        && typeof product.name === 'string'
        && typeof product.price === 'string')) {
    throw new Error('Product service returned an unexpected response.');
  }

  const products = payload.products.map((product) => ({
    id: product.id,
    name: product.name,
    price: product.price
  }));

  return {
    content: [
      { type: 'text', text: `Found ${products.length} matching products.` }
    ],
    structuredContent: {
      products,
      total: products.length
    }
  };
};

Não coloque credenciais de API no código-fonte, nos metadados de ação, no JavaScript widget, nos logs ou em erros voltados para o usuário. Atualmente, a interface do usuário Variáveis e segredos aceita somente variáveis não confidenciais, não segredos. Não armazene um token de API em uma variável. Se sua API upstream exigir credenciais, organize um mecanismo de credenciais do lado do servidor aprovado antes de conectá-lo.

Para código de produção, valide a resposta upstream completa antes de mapear campos aprovados para structuredContent.

Adicionar testes de manipulador

Criar o teste correspondente:

test/
└── actions/
    └── search-products.test.js

Testar pelo menos:

Executar:

npm test

Para layout de projeto e teste de MCP local, consulte Desenvolvimento e teste de manipulador local.

Testar a ação localmente

Executar:

npm run dev:local

Sem um actions.json local, o servidor descobre o manipulador com o mínimo de metadados e sem validação do esquema de entrada.

Use o Inspetor de MCP ou curl para:

Conectar e testar o widget

Se a ação tiver um widget:

Consulte Trazer seu próprio projeto de EDS.

Implantar e testar

Se os metadados existirem sem um manipulador correspondente, a implantação registrará a ação com um stub padrão. Adicione o manipulador antes de disponibilizar a ação aos usuários.