Erstellen einer Aktion von Grund auf create-action-from-scratch

Verwenden Sie dieses Handbuch, um eine Funktion hinzuzufügen, die von der Plattform nicht erstellt wurde. Sie definieren die Aktion in LLM Apps, schreiben den Handler in das verknüpfte Repository, fügen bei Bedarf ein Widget hinzu, testen sie und stellen sie bereit.

Journey: Planen Sie die Aktion, → die Metadaten zu erstellen → den Handler zu schreiben → das Widget zu verbinden → lokal zu testen → das Plug-in bereitzustellen und zu testen.

Beginnen Sie Ihre erste App mit Erste App automatisch erstellen.

Bevor Sie beginnen

Sie benötigen:

Planen der Aktion

Eine Aktion sollte nur eine einzige klare Benutzeraufgabe ausführen. Bevor Sie die Benutzeroberfläche öffnen, definieren Sie Folgendes:

Eine Aktion Produkte suchen könnte beispielsweise Folgendes verwenden:

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

Verwandte, aber unterschiedliche Aufgaben getrennt halten. Produktsuche und Produktkauf sollten nicht eine Aktion sein, da sie unterschiedliche Eingaben, Risiken und Bestätigungsanforderungen haben.

Erstellen der Aktionsmetadaten

Öffnen Sie die App und wählen Sie Aktionen und dann Aktion erstellen aus.

Der Editor enthält die Registerkarten Aktion und Widget-).

Einfache Informationen eingeben

Geben Sie Folgendes ein:

Eine nützliche Beschreibung ist spezifisch:

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

Vermeiden Sie vage Beschreibungen wie Abrufen von Produktinformationen. Die LLM-Plattform verwendet die Beschreibung zur Auswahl zwischen Aktionen.

Auswählen von Anmerkungen

Anmerkungen beschreiben das Verhalten der Aktion:

Wählen Sie nur Anmerkungen aus, die wahr sind. Beispielsweise ist die Produktsuche normalerweise schreibgeschützt, idempotent und offen.

OpenAI-Metadaten hinzufügen

Geben Sie kurze Nachrichten ein, die während und nach Abschluss der Aktion angezeigt werden:

Invoking: Searching products...
Invoked: Products found

Für Aktionen mit Widgets fügen Sie Widget-Beschreibung hinzu. Dies unterscheidet sich von der Aktionsbeschreibung:

LLM Apps gilt als Komponentenmetadaten. Geben Sie sie nicht vom Handler zurück.

Sichtbarkeit konfigurieren

Widget-Sichtbarkeit deaktivieren, wenn die Aktion nur Text zurückgibt.

Eingabeparameter hinzufügen

Fügen Sie für jeden Wert, den der Handler akzeptiert, einen Parameter hinzu. Jeder Parameter benötigt:

Für Produkte suchen:

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

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

Verwenden Sie stabile Parameternamen. Zum Ändern eines Namens müssen auch der Handler und seine Tests geändert werden.

Analytics konfigurieren

Aktivieren Sie Benutzerabsicht erfassen wenn Sie möchten, dass Analytics eine Zusammenfassung der Konversation enthält, die zu der Aktion geführt hat.

Vollständige Felddefinitionen finden Sie unter Aktion und Widget-Felder.

Konfigurieren des Widgets

Überspringen Sie diesen Abschnitt für eine Aktion, die nur Text enthält.

Öffnen Sie Widget-Metadaten.

Konfigurieren:

Typische URLs sind:

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

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

Gewähren Sie nur erforderliche Browser-Berechtigungen und CSP-Domains.

Wenn das EDS-Projekt oder die Widget-Seite noch nicht vorhanden ist, schließen Sie Eigenes EDS-Projekt ​) ab und kehren Sie dann zur Aktion zurück.

Speichern der Aktion

Wählen Sie Neue Aktion erstellen aus. Die Aktion wird auf der Seite Aktionen mit dem Badge Nicht bereitgestellt angezeigt.

An dieser Stelle sind die Metadaten vorhanden, für die Aktion ist jedoch weiterhin ein Handler erforderlich.

Implementieren des Handlers

Klonen Sie das verknüpfte Handler-Repository und installieren Sie dessen Abhängigkeiten:

npm install

Erstellen:

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

Der Ordnername muss mit der Code-Kennung der Aktion übereinstimmen, die im Aktionseditor angezeigt wird.

Die vollständige Beziehung zwischen Ergebnisvertrag und Handler-Widget finden Sie unter Anpassen eines generierten Handlers.

Händlervertrag

Exportieren Sie eine asynchrone Funktion:

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

Der Handler empfängt die in der Benutzeroberfläche definierten Parameter.

content

content ist der von der LLM-Plattform gelesene Fallback-Text:

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

Geben Sie immer nützliche content zurück, auch wenn die Aktion über ein Widget verfügt.

structuredContent

structuredContent ist ein einfaches Objekt, das vom Widget genutzt wird:

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

Die Form muss mit dem übereinstimmen, was der EDS-Block aus bridge.toolResult liest.

Verbinden einer API

Schützen Sie den API-Zugriff im Server-seitigen Handler. Laden Sie die Konfiguration aus der Laufzeitumgebung und verwenden Sie eine feste HTTPS-Herkunft.

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

Geben Sie keine API-Anmeldeinformationen in Quell-Code, Aktionsmetadaten, Widget-JavaScript, Protokolle oder benutzerseitige Fehler ein.

Für Produktions-Code validieren Sie die vollständige Upstream-Antwort, bevor Sie genehmigte Felder structuredContent zuordnen.

Hinzufügen von Handler-Tests

Erstellen Sie den passenden Test:

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

Mindestens testen:

Ausführen:

npm test

Informationen zum Projektlayout und zu lokalen MCP-Tests finden Sie unter Lokale Handlerentwicklung und -tests.

Lokales Testen der Aktion

Ausführen:

npm run dev:local

Ohne eine lokale actions.json erkennt der Server den Handler mit minimalen Metadaten und ohne Validierung des Eingabeschemas.

Verwenden Sie MCP Inspector oder curl, um:

Verbinden und Testen des Widgets

Wenn die Aktion über ein Widget verfügt:

Siehe Eigenes EDS-Projekt ​.

Bereitstellen und Testen

Wenn Metadaten ohne übereinstimmenden Handler vorhanden sind, registriert die Bereitstellung die Aktion mit einem Standard-Stub. Fügen Sie den Handler hinzu, bevor Sie die Aktion den Benutzern zur Verfügung stellen.