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

Usa questa guida per aggiungere una funzionalità che la piattaforma non ha creato. Definirai l’azione in LLM Apps, scriverai il relativo gestore nell’archivio collegato, aggiungerai un widget se necessario, verificherai e implementerai.

Percorso: Pianifica l’azione → crearne i metadati → scrivere il gestore → connettere il widget → il test in locale → distribuire e testare il plug-in.

Per la prima app, inizia con Crea automaticamente la prima app.

Prima di iniziare

Hai bisogno di:

Pianificare l’azione

Un’azione deve eseguire un’attività utente chiara. Prima di aprire l’interfaccia utente, definisci:

Ad esempio, per un’azione di Ricerca prodotti è possibile utilizzare:

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. La ricerca dei prodotti e l’acquisto dei prodotti non devono essere considerati come un’unica azione, in quanto presentano input, rischi e requisiti di conferma diversi.

Creare i metadati dell’azione

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

L’editor contiene schede Azione e Metadati widget.

Immetti le informazioni di base

Inserisci:

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. È diverso dalla descrizione dell’azione:

LLM Apps applica questo elemento come metadati del componente. Non restituirlo dal gestore.

Configurare la visibilità

Disattiva la visibilità dei widget quando l’azione restituisce solo testo.

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

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

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

Configurare il widget

Ignora questa sezione per un’azione di solo testo.

Apri Metadati widget.

Configurare:

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.

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.

A questo punto, i metadati esistono, ma l’azione richiede ancora un gestore.

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

content è il testo di riserva letto dalla piattaforma LLM:

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

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

Restituisce structuredContent

structuredContent è un oggetto normale utilizzato dal widget:

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 l’accesso API protetto nel gestore lato server. Carica la configurazione dall’ambiente di runtime e utilizza un’origine HTTPS fissa.

const API_ORIGIN = process.env.PRODUCT_API_ORIGIN;
const API_TOKEN = process.env.PRODUCT_API_TOKEN;

module.exports = async ({ query = '' } = {}) => {
  const normalizedQuery = String(query).trim();
  if (!normalizedQuery || normalizedQuery.length > 200) {
    return {
      content: [{ type: 'text', text: 'Enter a valid product search.' }],
      structuredContent: { products: [], total: 0 }
    };
  }

  if (!API_ORIGIN || !API_TOKEN) {
    throw new Error('Product API configuration is unavailable.');
  }

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

  const url = new URL('/v1/products', origin);
  url.searchParams.set('query', normalizedQuery);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${API_TOKEN}` },
    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.

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.