Creare un’azione da zero create-action-from-scratch

Aggiungi una funzionalità non creata dalla piattaforma. Definisci l’azione in LLM Apps, scrivi il relativo gestore nell’archivio collegato e aggiungi un widget, se necessario.

In questa guida: Scopri come definire un’azione, implementarne il gestore e connettere un widget facoltativo. Verifica l’azione a livello locale, distribuisci l’app e prova l’azione in una piattaforma LLM supportata.

Per la prima app, inizia con Configurazione infrastruttura, quindi Crea azioni. La guida alle azioni Crea spiega la generazione automatica da un sito web e la creazione manuale.

Prima di iniziare

Hai bisogno di:

Pianificare l’azione

Progetta ogni azione intorno a un’attività utente chiara. Prima di aprire l’interfaccia utente, definisci:

Ad esempio, utilizza questo piano per un’azione Cerca prodotti:

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

Mantieni separate le attività correlate ma diverse. Utilizza azioni separate per la ricerca dei prodotti e l’acquisto dei prodotti, in quanto le attività hanno requisiti diversi in termini di input, rischi e conferma.

Creare i metadati dell’azione

Apri l’app e seleziona Azioni, quindi seleziona Crea azione.

La finestra di dialogo per la creazione contiene schede Azione e Metadati widget. Espandi ogni sezione per configurare i relativi campi.

Immetti le informazioni di base

Inserisci:

La finestra di dialogo deriva un identificatore di codice dal nome, ad esempio search-products. L’identificatore viene corretto dopo la creazione e deve essere univoco all’interno dell’app. Utilizza l’identificatore esatto della cartella del gestore.

Una descrizione utile è specifica:

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

Evita descrizioni vaghe come Ottiene informazioni sul prodotto. La piattaforma LLM utilizza la descrizione per scegliere tra le azioni.

Seleziona annotazioni

Le annotazioni descrivono il comportamento dell’azione:

Seleziona solo le annotazioni vere. Ad esempio, la ricerca di prodotti è normalmente di sola lettura, idempotente e open-world.

Aggiungi metadati OpenAI

Inserisci brevi messaggi visualizzati durante l’esecuzione dell’azione e al suo completamento:

Invoking: Searching products...
Invoked: Products found

Per le azioni con widget, aggiungi Descrizione widget. La descrizione del widget è diversa dalla descrizione dell’azione:

LLM Apps applica la descrizione del widget come metadati del componente. Non restituire la descrizione dal gestore.

Configurare la visibilità

Per un’azione solo testo, selezionare anche Nessun widget in Metadati widget > Tipo. I controlli di visibilità non selezionano il tipo di widget dell’azione.

Aggiungi parametri di input

Aggiungi un parametro per ogni valore accettato dal gestore. Ogni parametro richiede:

Per Prodotti Di Ricerca:

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

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

Utilizza nomi di parametri stabili. La modifica di un nome richiede anche la modifica del gestore e dei relativi test.

Configurare Analytics configure-analytics

Abilitare Raccogli intento utente quando si desidera che Analytics includa un riepilogo della conversazione che ha portato all’azione.

Se configuri Adobe Analytics o Customer Journey Analytics, viene inviato anche l’intento utente. Vedere Configurazione di Adobe Analytics e Customer Journey Analytics.

La raccolta delle finalità utente è attivata per impostazione predefinita. Rivedi Descrizione intento utente, che contiene le istruzioni per la richiesta del riepilogo. Limita le istruzioni a un intento non sensibile e anonimo e descrivi la raccolta di dati nell’informativa sulla privacy. La descrizione accetta fino a 2.000 caratteri.

Per le definizioni complete dei campi, vedere Campi azione e widget.

Configurare il widget

Per un’azione solo testo, aprire Metadati widget e impostare Tipo su Nessun widget. Quindi salta le restanti impostazioni del widget.

Apri Metadati widget.

Configurare:

Espandi URL modello e immetti:

Gli URL tipici sono:

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

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

Concedi solo le autorizzazioni browser e i domini CSP richiesti.

Espandi Autorizzazioni (specifiche MCP) solo se il widget richiede funzionalità del browser come la geolocalizzazione. Lascia disattivate le autorizzazioni non utilizzate.

In Configurazione CSP, aggiungi le origini necessarie per le risorse e le richieste di rete. Un widget che carica risorse esterne potrebbe non eseguire il rendering se la relativa CSP è incompleta.

Se il progetto EDS o la pagina del widget non esiste ancora, completa Porta il tuo progetto EDS, quindi torna all’azione.

Salva l’azione

Seleziona Crea nuova azione. L’azione viene visualizzata nella pagina Azioni con un contrassegno Non distribuito.

Il salvataggio crea i metadati, ma l’azione richiede ancora un gestore.

Quando riapri l’azione salvata, l’editor dispone di Dettagli widget LLM, Dettagli azione e Schede Analytics. Per salvare le modifiche successive, selezionare Salva modifiche. La finestra di dialogo per la creazione e l’editor delle azioni salvate hanno layout diversi.

Implementare il gestore

Clona l’archivio del gestore collegato e installane le dipendenze:

npm install

Crea:

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

Il nome della cartella deve corrispondere all’identificatore di codice dell’azione visualizzato nell’editor delle azioni.

Per il contratto del risultato completo e la relazione handler-widget, vedere Personalizzare un handler generato.

Contratto gestore

Esporta una funzione asincrona:

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

Il gestore riceve i parametri definiti nell’interfaccia utente.

Restituisce content

La piattaforma LLM legge content come fallback del testo:

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

Restituisce sempre content utile, anche quando l’azione ha un widget.

Restituisce structuredContent

Il widget utilizza structuredContent come oggetto normale:

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

La forma deve corrispondere a quanto letto dal blocco EDS da bridge.toolResult.

Connettere un’API

Mantieni le chiamate API nel gestore lato server. Questo esempio chiama un’API di prodotto pubblica. Configura l’origine HTTPS dell’API in una variabile app denominata PRODUCT_API_ORIGIN. L’esempio accetta i parametri query e category definiti in precedenza, richiede almeno un parametro e non richiede credenziali.

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

Non inserire credenziali API nel codice sorgente, nei metadati di azioni, nel widget JavaScript, nei registri o in errori rivolti all’utente. L’interfaccia utente di Variabili e segreti supporta attualmente solo variabili non sensibili, non segreti. Non memorizzare un token API in una variabile. Se l’API a monte richiede delle credenziali, disponi un meccanismo di credenziali lato server approvato prima di connetterla.

Per il codice di produzione, convalidare la risposta upstream completa prima di mappare i campi approvati in structuredContent.

Aggiungi test del gestore

Crea il test corrispondente:

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

Prova almeno:

Esegui:

npm test

Per il layout del progetto e il test MCP locale, vedere Sviluppo e test del gestore locale.

Verifica l’azione a livello locale

Esegui:

npm run dev:local

Senza un actions.json locale, il server rileva il gestore con metadati minimi e nessuna convalida dello schema di input.

Utilizzare MCP Inspector o curl per:

Connetti e verifica il widget

Se l’azione ha un widget:

Vedi Porta il tuo progetto EDS.

Distribuzione e test

Se esistono metadati senza un gestore corrispondente, la distribuzione registra l’azione con uno stub predefinito. Aggiungi il gestore prima di rendere l’azione disponibile agli utenti.