Menüdaten mit der Food Ordering AI Agent API einbinden

In diesem Leitfaden wird beschrieben, wie Sie die Daten Ihrer Speisekarte strukturieren, transformieren und in die Food Ordering KI-Agent Menu API einbinden. So kann der KI-Agent Ihre Speisekarte verstehen und Bestellungen von Kunden korrekt aufnehmen.

Hinweis

Bevor Sie Speisekarten mit der Food Ordering AI Agent API aufnehmen und verwalten können, müssen Sie Folgendes tun:

  1. Aktivieren Sie die Food Ordering KI-Agent API:

      gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT
    
  2. Prüfen Sie, ob Sie die erforderlichen IAM-Berechtigungen haben. Weisen Sie dem Nutzer oder Dienstkonto, der bzw. das mit der API interagiert, die folgende IAM-Rolle (Identity and Access Management) zu:

    • Food Ordering Agent Admin (roles/foodorderingaiagent.admin): Diese Rolle bietet vollständigen Zugriff zum Erstellen, Lesen, Aktualisieren und Löschen aller Food Ordering KI-Agent-Ressourcen, einschließlich Marken, Geschäften und Speisekarten.

    Sie können IAM-Rollen über die Google Cloud Console, das gcloud-Befehlszeilentool oder die IAM API zuweisen. Weitere Informationen finden Sie unter IAM-Rolle zuweisen.

    So weisen Sie die Rolle über die Google Cloud Console zu:

    1. Rufen Sie in der Google Cloud Console die Seite IAM auf.
    2. Klicken Sie auf Hinzufügen.
    3. Geben Sie das Hauptkonto (E-Mail-Adresse des Nutzers oder Dienstkontos) ein.
    4. Wählen Sie die Rolle Food Ordering KI-Agent-Administrator aus.
    5. Klicken Sie auf Speichern.

    Ohne die entsprechenden Berechtigungen werden API-Aufrufe zum Erstellen oder Ändern von Marken, Geschäften oder Speisekarten abgelehnt. Die Rolle Food Ordering Agent Viewer reicht für die in diesem Leitfaden beschriebenen Aufgaben nicht aus, da sie nur Lesezugriff gewährt.

Übersicht

Die Food Ordering AI Agent Menu API ist flexibel und kann verschiedene Speisekartenstrukturen verarbeiten, von kurzen Listen mit eigenständigen Artikeln bis hin zu komplexen Speisekarten mit verschachtelten Modifikatoren und Kombinationsgerichten. Die API basiert auf einigen wichtigen Konzepten:

  • Menü: Der übergeordnete Container für alle bestellbaren Entitäten.
  • Artikel: Ein bestellbares Produkt auf oberster Ebene aus der Speisekarte, z. B. ein Gericht, eine Vorspeise oder ein Produkt, das einzeln bestellt werden kann. Items können auf ModifierGroups verweisen.
  • ModifierGroup: Eine Sammlung von Modifier-Optionen, die auf ein Item oder ein anderes Modifier angewendet werden können (Verschachtelung möglich). Beispiele: „Beilage auswählen“, „Zutaten hinzufügen“ oder „Geschmacksrichtung des Getränks auswählen“.
  • Modifikator: Eine einzelne Option innerhalb einer ModifierGroup, z. B. „Pommes frites“, „Extra Käse“ oder „Cola“. Modifikatoren können den Preis anpassen und auch eigene verschachtelte ModifierGroups haben.
  • MenuCategory: Wird verwendet, um Items in Abschnitte für die Anzeige und das Verständnis der Anzeige zu unterteilen (z.B. „Vorspeisen“, „Burger“, „Getränke“).

Wichtige Konzepte und Struktur

In diesem Abschnitt werden die Kernkomponenten des Schemas der Food Ordering AI Agent Menu API und ihre Struktur beschrieben. Das Verständnis dieser Konzepte ist entscheidend, um Ihre Speisekarten-Daten korrekt zu modellieren.

Elemente

Jeder einzelne Artikel auf Ihrer Speisekarte sollte als Item definiert werden. Wichtige Felder:

  • id: Eine eindeutige Kennung innerhalb der Speisekarte.
  • display_name: Der Name, der für Kunden sichtbar ist.
  • base_price: Der Basispreis des Artikels.
  • modifier_groups: Verweise auf ModifierGroups, die auf diesen Artikel angewendet werden können.
  • category_ids: Verweise auf MenuCategory-IDs, zu denen dieses Element gehört.
  • availability: Gibt an, wann der Artikel verfügbar ist (z.B. nach Status oder Tageszeit). Wenn keine Angabe gemacht wird, ist der Standardwert STATUS_AVAILABLE.

Modifikatoren und Modifikatorgruppen

Mit Modifikatoren können Artikel angepasst werden.

  • ModifierGroups definieren eine Reihe von Auswahlmöglichkeiten, einschließlich Einschränkungen wie Mindest- oder Höchstauswahl. Muss mindestens ein Modifier enthalten.
  • Modifiers stehen für die tatsächlichen Optionen. Sie können einen price_adjustment haben und rekursiv auf andere ModifierGroups für verschachtelte Anpassungen verweisen (z.B. kann ein Item „Menü“ eine ModifierGroup „Getränk auswählen“ haben und die Modifier „Limonade“ in dieser Gruppe kann eine ModifierGroup „Geschmacksrichtung auswählen“ haben).

Beispiel 1: Toppings

Ein „Bacon Cheeseburger“ Item kann auf „Toppings“ ModifierGroup verweisen. Diese ModifierGroup würde Modifiers wie „Extra Käse“, „Keine Zwiebeln“ usw. enthalten.

Beispiel 2: Kombi-Menüs

Einige Menüs haben komplexe Strukturen, die aus mehreren verschachtelten Auswahlmöglichkeiten bestehen, z. B. Kombinationsgerichte oder „Kombis“. Kombinationen können als Item mit mehreren ModifierGroups modelliert werden, die die Komponenten der Kombination darstellen. Beispiel: Ein „Burger-Menü“ (Item), das aus einem festen Hauptgericht und mehreren Optionen für Beilage und Getränk besteht, könnte so modelliert werden:

  • Eine ModifierGroup für die Beilage (z.B. „Beilagen“).
    • Jede Beilage wird als Modifier modelliert (z.B. „Pommes frites“, „Salat“).
      • Jede Getränkeoption kann auf verschachtelte ModifierGroups verweisen (z.B. „Eisoptionen“, „Getränkegröße“), die wiederum auf Modifiers verweisen (z.B. „Kein Eis“, „Großes Getränk“).
  • Eine ModifierGroup für das Getränk (z.B. „Getränke“).
    • Jede Getränkeoption wird als Modifier modelliert.
      • Jede Getränkeoption kann auf verschachtelte ModifierGroups verweisen (z.B. „Eisoptionen“, „Getränkegröße“), die wiederum auf Modifiers verweisen (z.B. „Kein Eis“, „Großes Getränk“).
  • Ein ModifierGroup für Toppings auf dem Hauptgericht. (z.B. „Extra Käse“, „Bacon“).

Verfügbarkeit

Mit der Nachricht Availability für Items und Modifiers können Sie Folgendes angeben:

  • status: STATUS_AVAILABLE, STATUS_OUT_OF_STOCK usw.
  • daypart_availability: Links zu bestimmten Tageszeit-IDs, wenn der Artikel nur zu bestimmten Zeiten verfügbar ist (z.B. „Frühstücksmenü“).

Integrationsattribute

Item-, Modifier- und ModifierGroup-Nachrichten enthalten ein integration_attributes-Feld. Dieses Feld (ItemIntegrationAttributes, ModifierIntegrationAttributes usw.) enthält einen google.protobuf.Struct namens custom_integration_attributes. Sie können damit beliebige Schlüssel/Wert-Daten speichern, z. B.:

  • IDs aus Ihrem Kassensystem.
  • SKUs oder andere interne Codes
  • Alle anderen Metadaten, die für die nachgelagerte Bestellverarbeitung oder POS-Integration erforderlich sind.

Diese Daten werden vom KI-Agenten undurchsichtig weitergegeben.

Labels

Sie können das Feld labels in der Ressource Menu verwenden, um Metadaten an Menüs anzuhängen, die bei der Integration und Fehlerbehebung helfen.

Labels sind eine praktische Funktion und haben keine Auswirkungen auf das Verhalten des KI-Agenten.

Speisekarte erstellen

Speisekarten werden über den RPC-Aufruf CreateMenu in der MenuService aufgenommen.

Schritte

  1. Daten transformieren: Wandeln Sie Ihre vorhandenen Speisekarten-Daten (aus Ihrem Kassensystem, Ihrer API oder einer anderen Quelle) in die durch die google.cloud.foodorderingaiagent.v1beta.Menu-Nachricht definierte Struktur um. Dazu müssen Sie Ihre Artikel, Modifikatoren, Kategorien und Preise den entsprechenden API-Nachrichtentypen zuordnen.
  2. CreateMenuRequest erstellen:
    • Legen Sie das Feld parent fest (z.B. projects/PROJECT/locations/LOCATION).
    • Füllen Sie das Feld menu mit Ihrem transformierten Menu-Objekt aus.
    • Geben Sie optional einen menu_id an.
  3. API aufrufen: Senden Sie die CreateMenuRequest an den Endpunkt MenuService.CreateMenu. Die API bereinigt zuerst die Speisekarte, validiert sie dann und gibt das endgültige Menu-Objekt zurück.
  4. Speisekartenaktualisierungen verarbeiten: Bei jeder Aktualisierung der Quelldaten der Speisekarte (z. B. wenn ein neues Produkt eingeführt wird oder ein Produkt nicht mehr verfügbar ist) sollte eine neue Menu erstellt werden, die die aktualisierten Quelldaten widerspiegelt. Folgen Sie dazu der Anleitung unter Speisekartenaktualisierungen verarbeiten.

Anleitung zur Datentransformation

Die genaue Logik für die Transformation Ihrer Speisekarten-Daten hängt vom Format und der Struktur Ihres Quellsystems ab (z.B. POS-API, Datenbankschema). Hier ist ein allgemeiner Ansatz:

  • Daten exportieren: Sie können einen vollständigen Export Ihrer Speisekartendaten erhalten, einschließlich aller Artikel, Modifikatoren, Preise und Beziehungen.
  • Entitäten zuordnen:
    • Identifizieren Sie die entsprechenden Entitäten im API-Schema des KI-Agenten für Food Ordering für jedes Element in Ihren Quelldaten. Beispielsweise werden die „Menüpunkte“ Ihres Kassensystems wahrscheinlich Item-Objekten zugeordnet. „Bestelloptionen“ oder „Add-ons“ werden Modifiers und ModifierGroups zugeordnet.
    • Beziehungen mithilfe von IDs herstellen. Verknüpfe beispielsweise Items mit den entsprechenden ModifierGroups über das Referenzfeld modifier_groups.
  • Verschachtelte Strukturen verarbeiten: Wenn Ihre Speisekarte verschachtelte Modifikatoren enthält (z.B. die Auswahl einer Geschmacksrichtung für das Getränk eines Kombi-Menüs), können Sie dies modellieren, indem Sie Modifiers auf andere ModifierGroups verweisen lassen.
  • Attribute ausfüllen: Füllen Sie Felder wie display_name, base_price, price_adjustment und availability anhand Ihrer Quelldaten aus.
  • POS-IDs angeben: Speichern Sie Ihre internen POS- oder System-IDs für jeden Artikel, jede Modifikation und jede Gruppe im Feld custom_integration_attributes. So können Sie die vom Agenten erstellte Order wieder in die Darstellung einer endgültigen Bestellung oder eines laufenden Einkaufswagens in Ihrer Anwendung übersetzen.
  • Scripting: Sie müssen wahrscheinlich ein Script schreiben (z.B. in Python, Node.js, Go), um Daten aus Ihrer Quelle abzurufen, die Transformation durchzuführen und die Methode CreateMenu aufzurufen. Dieses Skript verwendet die Clientbibliotheken von Google Cloud für die Authentifizierung und API-Interaktion.

Konzeptioneller Transformationsworkflow:

In diesem Workflow wird beschrieben, wie Speisekarten-Daten aus einem Quellsystem in das Format der Food Ordering KI-Agent API umgewandelt werden:

  1. Kategorien extrahieren und zuordnen:
    • Identifizieren Sie Kategorien oder Abschnitte in Ihren Quelldaten (z.B. „Vorspeisen“, „Hauptgerichte“).
    • Wandeln Sie jedes Objekt in ein MenuCategory-Objekt mit einer eindeutigen id und display_name um.
  2. Elemente extrahieren und zuordnen:
    • Identifizieren Sie verkaufbare Artikel in Ihren Quelldaten.
    • Wandeln Sie jedes Objekt in ein Item-Objekt um und füllen Sie id, display_name, base_price und availability aus.
    • Ordnen Sie jede Item mithilfe des Felds category_ids den entsprechenden Kategorien zu.
    • Speichern Sie Quellsystemkennungen (z. B. PLU oder SKU) in item.integration_attributes.custom_integration_attributes.
  3. Modifikatoren extrahieren und zuordnen:
    • Identifizieren Sie Artikelanpassungen, Optionen oder Add-ons in Ihren Quelldaten.
    • Gruppieren Sie zusammengehörige Optionen (z.B. „Beilagen“, „Getränke“, „Zusätzliche Toppings“) in ModifierGroup-Objekten. Definieren Sie Regeln für die minimale und maximale Auswahl für jede ModifierGroup.
    • Wandeln Sie jede einzelne Option (z.B. „Pommes“, „Cola“, „Extra Käse“) in Modifier-Objekte innerhalb der entsprechenden ModifierGroup um. Füllen Sie price_adjustment aus, falls zutreffend.
    • Speichern Sie die Kennungen des Quellsystems in modifier_group.integration_attributes.custom_integration_attributes und modifier.integration_attributes.custom_integration_attributes.
  4. Beziehungen aufbauen:
    • Füllen Sie für jede Item das Feld modifier_groups mit Verweisen auf die ids der ModifierGroups, die für sie gelten.
    • Wenn ein Modifier weitere Anpassungen zulässt (z.B. die Auswahl einer Geschmacksrichtung für einen Modifikator „Limonade“), füllen Sie das Feld modifier_groups aus, um verschachtelte Modifikatoren zu erstellen.
  5. Zusammenstellen und aufnehmen:
    • Kombinieren Sie alle MenuCategory-, Item-, ModifierGroup- und Modifier-Objekte in den Listen innerhalb einer einzigen Menu-Nachricht.
    • Rufen Sie den RPC CreateMenu mit der vollständig zusammengestellten Nachricht Menu als Eingabe auf.

Umgang mit Menüaktualisierungen

Menu ist unveränderlich. Nachdem eine Speisekarte mit dem RPC-Aufruf CreateMenu erstellt wurde, kann sie nicht mehr geändert werden. Wenn Sie Änderungen an einem Menü vornehmen möchten, z. B. Artikelpreise, Optionen oder Verfügbarkeit anpassen, müssen Sie eine neue Menüressource erstellen. Rufen Sie dazu noch einmal CreateMenu auf. Jede Version Ihrer Speisekarte sollte als neue Menu-Ressource mit einer eindeutigen menu_id aufgenommen werden.

Der Prozess zum Aufnehmen einer neuen Version einer Speisekarte ist identisch mit der erstmaligen Aufnahme der Speisekarte. Es werden dieselben Schritte zur Bereinigung und Validierung durchgeführt. Bei der Bearbeitung von Bestellungen entspricht das Verhalten des KI-Agenten immer der zuletzt erstellten Menu, die mit der Store verknüpft ist, auf die in der Konfiguration der Sitzung verwiesen wird.

Automatische Bereinigung von Speisekarten

Die CreateMenu API führt automatisch mehrere Bereinigungsschritte aus, um häufige Probleme zu beheben und dafür zu sorgen, dass Menüinhalte in der gesamten API einheitlich dargestellt werden. Die Validierungen werden nach diesen Bereinigungen angewendet, um die Menüintegration für Kunden zu vereinfachen:

  • Standardverfügbarkeit: Items und Modifiers ohne explizite Availability.Status werden auf STATUS_AVAILABLE gesetzt.
  • Nicht referenzierte Entitäten verwerfen: Modifiers und ModifierGroups, die nicht transitiv von einem Item referenziert werden, werden aus der Speisekarte entfernt, da sie nicht bestellt werden können.
  • Leere Modifikatorgruppen verwerfen: ModifierGroups, die keine modifier_ids enthalten, werden verworfen und alle Verweise darauf werden entfernt.

Nach der Bereinigung validiert die API die Speisekarte anhand strenger Regeln, um sicherzustellen, dass sie korrekt formatiert ist und vom KI-Agenten zuverlässig verwendet werden kann. Wenn die Validierung fehlschlägt, wird beim Aufruf von CreateMenu ein Fehler mit Details zu den Problemen zurückgegeben. Zu den wichtigsten Validierungen gehören:

  • Pflichtfelder: Es wird geprüft, ob alle Pflichtfelder wie id, display_name und availability.status vorhanden sind.
  • Eindeutige IDs: Alle Items, Modifiers und ModifierGroups müssen innerhalb der Speisekarte eindeutige IDs haben.
  • Eindeutige Anzeigenamen:
    • Alle Items müssen eindeutige display_names haben.
    • Innerhalb einer bestimmten ModifierGroup müssen alle enthaltenen Modifiers eindeutige display_names haben.
  • Referenzielle Integrität:
    • Alle modifier_group_ids, auf die von Items oder Modifiers verwiesen wird, müssen in der Speisekarte vorhanden sein.
    • Alle modifier_ids, auf die von ModifierGroups verwiesen wird, müssen in der Speisekarte vorhanden sein.
    • In ModifierGroupReference angegebene Standardmodifikatoren müssen im referenzierten ModifierGroup vorhanden sein.
    • Wenn ein Modifier mit item_id auf ein Item verweist, muss dieses Item vorhanden sein.
  • Einschränkungen für Modifikatorgruppen:
    • ModifierGroups dürfen nicht leer sein.
    • Die minimale oder maximale Anzahl der Auswahlen innerhalb von ModifierGroups wird auf logische Konsistenz geprüft.
    • Item oder Modifier der Ebene modifier_constraints werden anhand der Einschränkungen für die Anzahl der Auswahlen der referenzierten ModifierGroups validiert, um sicherzustellen, dass sie erfüllt werden können.
  • Verschachtelungstiefe: Die Tiefe verschachtelter Modifikatoren ist auf maximal 5 Ebenen begrenzt (z.B. Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier...).
  • Tageszeitvalidierung: Wenn Tageszeiten in Availability verwendet werden, müssen sie in der zugehörigen Store-Ressource definiert werden.
  • Verweise auf Modifikatorelemente: Für Modifiers, die mit item_id auf ein Item verweisen, können keine Felder wie display_name oder availability festgelegt werden, da diese vom referenzierten Item übernommen werden.

Wenn eine dieser Validierungsregeln nicht erfüllt wird, kann die Speisekarte nicht erstellt oder aktualisiert werden. Die Fehlermeldung enthält Details dazu, welche Entitäten den Verstoß verursachen.

API-Referenz

Ausführliche Informationen zu allen Nachrichten und Feldern finden Sie in der RPC-Referenz zur Food Ordering KI-Agent API.

Best Practices

  • Eindeutige IDs: Achten Sie darauf, dass alle id-Felder im Menu-Bereich (für Item, Modifier, ModifierGroup, MenuCategory) eindeutig sind.
  • Klare Namen: Verwenden Sie klare, kundenfreundliche display_names. Geben Sie für semantisch unterschiedliche Produkte unterschiedliche display_names an, damit der Agent die Mehrdeutigkeit entsprechend auflösen kann.
  • Kombinationsmenüs effektiv modellieren: Modellieren Sie Kombinationsmenüs als Item mit ModifierGroups, die Beilagen, Getränke und andere Optionen darstellen, wie unter Kombinationsmenüs beschrieben. So können Kundenservicemitarbeiter Kunden korrekt durch die Auswahl von Kombis führen.
  • Integrationsattribute verwenden: Speichern Sie alle erforderlichen POS- oder internen Systemkennungen im custom_integration_attributes, um eine nahtlose Bestellintegration zu ermöglichen.
  • Verfügbarkeit verwalten: Halten Sie den Status Availability auf dem neuesten Stand.
  • Nur bestellbare Artikel aufnehmen: Lassen Sie Einträge weg, die Kunden nicht über den Kanal bestellen können, z. B. Artikel, die nur geliefert werden, doppelte Artikel und Einträge, die keine Lebensmittel oder Getränke sind. Große Menüs können die Menge an Eingaben überschreiten, die das Modell des KI-Agenten akzeptiert. Weitere Informationen finden Sie unter Agent wiederholt eine Wiederholungsnachricht und beendet dann die Sitzung.
  • Gründlich testen: Testen Sie nach der Aufnahme, ob der Agent die Speisekarte versteht, indem Sie verschiedene Bestellkombinationen ausprobieren.