Personalizar um widget gerado customize-generated-widget

A plataforma cria um dispositivo EDS para cada ação gerada. O widget já recebe o resultado da ação, renderiza dados de exemplo, aplica o estilo do host e está vinculado à ação em LLM Apps.

Comece testando o widget gerado. Em seguida, personalize o contrato de dados, a interação e o design visual.

Jornada: encontre o bloco gerado → alinhar seu contrato de dados → personalizar com segurança → visualizar localmente → implantar e testar.

Localizar o widget gerado

Abra o repositório EDS selecionado ao criar o aplicativo. Cada widget gerado é um bloco EDS:

blocks/
└── <action-name>/
    ├── <action-name>.js
    └── <action-name>.css

A plataforma também configura os URLs do widget e os arquivos SDK de suporte. Não é necessário criar um segundo projeto EDS ou inserir novamente esses valores para personalizar um widget gerado.

Como o SDK de aplicativos LLM conecta o widget

O pacote @adobe/llmapps-sdk conecta o dispositivo EDS ao host LLM. O repositório EDS gerado inclui:

scripts/
├── aem-embed.js
└── llmapps-sdk.js

O aem-embed.js estabelece a conexão de host, carrega a página de EDS e chama seu bloco:

export default async function decorate(block, bridge) {
  // Customize the widget here.
}

Você não importa a SDK no bloco. O bridge conectado é fornecido automaticamente. Ele permite que o widget:

Este guia aborda os métodos comuns de ponte. Consulte o @adobe/llmapps-sdk pacote para obter a API completa.

Entender o contrato de dados

O manipulador de ações retorna structuredContent e o bloco o lê de bridge.toolResult.

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

// EDS block
export default async function decorate(block, bridge) {
  const result = bridge ? await bridge.toolResult : null;
  const products = result?.structuredContent?.products ?? [];
  // Render products.
}

Quando você alterar structuredContent, atualize o manipulador e o widget juntos. Consulte Personalizar um manipulador gerado para obter o contrato de retorno completo.

Renderizar dados externos com segurança

Tratar saída do manipulador como dados não confiáveis. Prefira APIs DOM como textContent em vez de inserir valores de resposta em innerHTML.

function createProductCard(product, bridge) {
  const card = document.createElement('article');
  card.className = 'product-card';

  const title = document.createElement('h3');
  title.textContent = String(product.name ?? 'Product');

  const button = document.createElement('button');
  button.type = 'button';
  button.textContent = 'Tell me more';
  button.addEventListener('click', () => {
    if (bridge && product.id) {
      bridge.sendMessage(`Show me details for product ${String(product.id)}`);
    }
  });

  card.append(title, button);
  return card;
}

Valide as URLs antes de atribuí-las a href ou src e permita somente os protocolos exigidos pela experiência.

Usar a ponte do host

O EDS passa uma ponte conectada para decorate(block, bridge). A ponte de proteção chama, portanto, o bloco também é renderizado durante a pré-visualização direta do EDS.

Aplicar estilos de host

if (bridge) {
  bridge.applyHostStyles();
}

Isso se aplica à tipografia do host e às variáveis de tema. O CSS do widget deve suportar temas de host claros e escuros.

Enviar uma mensagem de acompanhamento

await bridge.sendMessage('Show me similar products.');

Use sendMessage quando uma interação precisar continuar a conversa.

Chamar outra ação

const result = await bridge.callTool('get-product-details', {
  id: product.id
});

Use callTool para uma interação explícita que precisa de outro resultado de ação. Transmita apenas valores validados e lide com falhas sem expor detalhes internos.

Manter o tamanho do widget sincronizado

if (bridge) {
  bridge.autoResize(block);
}

Chame autoResize após a renderização inicial para que o host possa responder às alterações de conteúdo.

Visualizar suas alterações

Os blocos gerados devem incluir dados de amostra para visualização direta quando bridge não estiver disponível.

Para visualizar o projeto EDS localmente:

npm install -g @adobe/aem-cli
aem up

Abra a página de widget gerada em http://localhost:3000. Verificar:

Em seguida, implante o aplicativo para preparo e teste com structuredContent ativo na plataforma LLM.

Publicar a personalização

Outras configurações de EDS

Se você não criou o aplicativo automaticamente ou deseja integrar um site de EDS existente, consulte Trazer seu próprio projeto de EDS.