Erstellen einer neuen Aktion create-action-from-scratch

Fügen Sie eine Funktion hinzu, die von der Plattform nicht erstellt wurde. Definieren Sie die Aktion in LLM Apps, schreiben Sie den Handler in das verknüpfte Repository und fügen Sie bei Bedarf ein Widget hinzu.

In diesem Handbuch Erfahren Sie, wie Sie eine Aktion definieren, ihren Handler implementieren und ein optionales Widget verbinden. Testen Sie die Aktion lokal, stellen Sie die App bereit und versuchen Sie die Aktion in einer unterstützten LLM-Plattform.

Beginnen Sie bei Ihrer ersten Mobile App mit Einrichten der Infrastruktur und Erstellen von Aktionen. Im Handbuch Aktionen erstellen werden die automatische Erstellung auf einer Website und die manuelle Erstellung erläutert.

Voraussetzungen

Sie benötigen:

Planen der Aktion

Entwerfen Sie jede Aktion für eine klare Benutzeraufgabe. Bevor Sie die Benutzeroberfläche öffnen, definieren Sie Folgendes:

Verwenden Sie diesen Plan beispielsweise für eine Aktion Produkte suchen:

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. Verwenden Sie separate Aktionen für die Produktsuche und den Produktkauf, da die Aufgaben unterschiedliche Eingaben, Risiken und Bestätigungsanforderungen aufweisen.

Erstellen der Aktionsmetadaten

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

Das Erstellungsdialogfeld enthält die Registerkarten Aktion und Widget-). Erweitern Sie jeden Abschnitt, um seine Felder zu konfigurieren.

Einfache Informationen eingeben

Geben Sie Folgendes ein:

Das Dialogfeld leitet eine Code-Kennung vom Namen ab, z. B. search-products. Die Kennung wird nach der Erstellung korrigiert und muss in der App eindeutig sein. Verwenden Sie die genaue Kennung für den Handler-Ordner.

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. Die Widget-Beschreibung unterscheidet sich von der Aktionsbeschreibung:

LLM Apps wendet die Widget-Beschreibung als Komponentenmetadaten an. Geben Sie die Beschreibung nicht vom Handler zurück.

Sichtbarkeit konfigurieren

Wählen Sie für eine Aktion, die nur Text enthält, auch Kein Widget unter Widget-Metadaten > Typ. Bei der Steuerung der Sichtbarkeit wird nicht der Widget-Typ der Aktion ausgewählt.

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 configure-analytics

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

Wenn Sie Ihre eigene Adobe Analytics oder Customer Journey Analytics einrichten, wird auch die Benutzerabsicht an diese gesendet. Siehe Einrichten von Adobe Analytics und Customer Journey Analytics.

Die Benutzerabsichtserfassung ist standardmäßig aktiviert. Lesen Sie Beschreibung der Benutzerabsicht, die die Anweisungen zum Anfordern der Zusammenfassung enthält. Beschränken Sie die Anweisungen auf einen nicht vertraulichen, anonymisierten Zweck und beschreiben Sie Ihre Datenerfassung in Ihrer Datenschutzerklärung. Die Beschreibung akzeptiert bis zu 2.000 Zeichen.

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

Konfigurieren des Widgets

Für eine Aktion, die nur Text enthält, öffnen Sie Widget-Metadaten und setzen Sie Typ auf Kein Widget. Überspringen Sie dann die verbleibenden Widget-Einstellungen.

Öffnen Sie Widget-Metadaten.

Konfigurieren:

Erweitern Sie Vorlagen-URLs und geben Sie Folgendes ein:

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.

Erweitern Sie Berechtigungen (MCP-spezifisch) nur, wenn das Widget Browser-Funktionen wie Geolokalisierung benötigt. Lassen Sie nicht verwendete Berechtigungen deaktiviert.

Fügen unter „CSP-" die Ursprünge hinzu, die für Assets- und Netzwerkanfragen erforderlich sind. Ein Widget, das externe Ressourcen lädt, wird möglicherweise nicht gerendert, wenn sein CSP unvollständig ist.

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.

Beim Speichern werden die Metadaten erstellt, für die Aktion ist jedoch ein Handler erforderlich.

Wenn Sie die gespeicherte Aktion erneut öffnen, verfügt der Editor über LLM-Widget- Details , Aktionsdetails und Analytics. Um spätere Änderungen zu speichern, wählen Sie Änderungen speichern. Das Erstellungsdialogfeld und der Editor für gespeicherte Aktionen haben unterschiedliche Layouts.

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

Die LLM-Plattform liest content als Textfallback:

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

Das Widget nutzt structuredContent als einfaches Objekt:

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

API-Aufrufe im Server-seitigen Handler behalten. In diesem Beispiel wird eine öffentliche Produkt-API aufgerufen. Konfigurieren Sie den HTTPS-Ursprung der API in einer App-Variablen namens PRODUCT_API_ORIGIN. Das Beispiel akzeptiert die oben definierten query- und category, erfordert mindestens einen Parameter und erfordert keine Anmeldeinformationen.

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

Geben Sie keine API-Anmeldeinformationen in Quell-Code, Aktionsmetadaten, Widget-JavaScript, Protokolle oder benutzerseitige Fehler ein. Die Benutzeroberfläche Variablen und Geheimnisse unterstützt derzeit nur nicht vertrauliche Variablen und keine geheimen Daten. Speichern Sie kein API-Token in einer Variablen. Wenn Ihre Upstream-API Anmeldeinformationen erfordert, vereinbaren Sie einen Mechanismus für genehmigte Server-seitige Anmeldeinformationen, bevor Sie sie verbinden.

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.