Cómo integrar datos de menús con la API del agente de IA de pedidos de comida

En esta guía, se explica cómo estructurar, transformar y transferir los datos del menú de tu restaurante a la API de Menu del agente de IA de pedidos de comida. De esta manera, permites que el agente de IA comprenda las ofertas de tu menú y tome pedidos de los clientes con precisión.

Antes de comenzar

Antes de que puedas transferir y administrar menús con la API del agente de IA para pedidos de comida, primero debes hacer lo siguiente:

  1. Habilita la API de Food Ordering AI Agent:

      gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT

  2. Asegúrate de tener los permisos de IAM necesarios. Otorga el siguiente rol de Identity and Access Management (IAM) al usuario o la cuenta de servicio que interactúa con la API:

    • Administrador del agente de pedidos de comida (roles/foodorderingaiagent.admin): Este rol proporciona acceso completo para crear, leer, actualizar y borrar todos los recursos del agente de IA para pedidos de comida, incluidas las marcas, las tiendas y los menús.

    Puedes otorgar roles de IAM con la consola de Google Cloud , la herramienta de línea de comandos de gcloud o la API de IAM. Para obtener más información, consulta Otorga un rol de IAM.

    Para otorgar el rol con la consola de Google Cloud , haz lo siguiente:

    1. En la consola de Google Cloud , dirígete a la página IAM.
    2. Haz clic en Agregar.
    3. Ingresa la entidad principal (correo electrónico de usuario o cuenta de servicio).
    4. Selecciona el rol Administrador del agente de IA de Pedidos de comida.
    5. Haz clic en Guardar.

    Sin los permisos adecuados, se rechazan las llamadas a la API para crear o modificar marcas, tiendas o menús. El rol Food Ordering Agent Viewer no es suficiente para las tareas que se describen en esta guía, ya que solo otorga acceso de solo lectura.

Descripción general

La API de Menu del agente de IA para pedidos de comida está diseñada para ser flexible y adaptarse a diversas estructuras de menú, desde listas cortas de elementos independientes hasta menús complejos con modificadores anidados y comidas combinadas. La API se basa en algunos conceptos clave:

  • Menú: Es el contenedor de nivel superior para todas las entidades que se pueden pedir.
  • Artículo: Representa un producto de nivel superior del menú que se puede pedir, como una comida, un plato principal o cualquier producto que se pueda pedir por separado. Los Items pueden hacer referencia a los ModifierGroups.
  • ModifierGroup: Es una colección de opciones de Modifier que se pueden aplicar a un Item o a otro Modifier (lo que permite el anidamiento). Por ejemplo, "Elige tu acompañamiento", "Agrega ingredientes" o "Selecciona el sabor de la bebida".
  • Modificador: Es una opción individual dentro de un ModifierGroup, como "Papas fritas", "Queso extra" o "Cola". Los modificadores pueden ajustar el precio y también pueden tener sus propios ModifierGroup anidados.
  • MenuCategory: Se usa para organizar los objetos Item en secciones para su visualización y comprensión (p.ej., “Aperitivos”, “Hamburguesas” y “Bebidas”).

Conceptos y estructura clave

En esta sección, se detallan los componentes principales del esquema de la API del menú del agente de IA para pedidos de comida y cómo se estructuran. Comprender estos conceptos es fundamental para modelar correctamente los datos de tu menú.

Elementos

Cada elemento distinto de tu menú debe definirse como un Item. Entre los campos clave, se incluyen los siguientes:

  • id: Es un identificador único dentro del menú.
  • display_name: Es el nombre visible para el cliente.
  • base_price: Es el precio base del artículo.
  • modifier_groups: Son referencias a ModifierGroups que se pueden aplicar a este elemento.
  • category_ids: Son referencias a los IDs de MenuCategory a los que pertenece este elemento.
  • availability: Especifica cuándo está disponible el elemento (p.ej., por estado o franja horaria). El valor predeterminado es STATUS_AVAILABLE si no se especifica.

Modificadores y ModifierGroups

Los modificadores permiten personalizar elementos.

  • Los ModifierGroup definen un conjunto de opciones, incluidas restricciones como selecciones mínimas o máximas. Debe contener al menos un Modifier.
  • Las Modifier representan las opciones reales. Pueden tener un price_adjustment y pueden hacer referencia de forma recursiva a otros ModifierGroup para personalizaciones anidadas (p.ej., un Item de "Combo de comida" podría tener un ModifierGroup de "Elige tu bebida", y el Modifier de "Soda" dentro de ese grupo podría tener un ModifierGroup de "Elige el sabor").

Ejemplo 1: Complementos

Una "hamburguesa de queso con tocino" Item podría hacer referencia a "Ingredientes" ModifierGroup. Este ModifierGroup contendría Modifiers como "Queso extra", "Sin cebolla", etcétera.

Ejemplo 2: Comidas combinadas (combos)

Algunos menús tienen estructuras complejas que constan de varias opciones anidadas, como comidas combinadas o "combos". Los combos se pueden modelar como un Item con varios ModifierGroup que representan los componentes del combo. Por ejemplo, un Item de "Combo de hamburguesa", que consiste en una entrada fija combinada con varias opciones de acompañamiento y bebida, se podría modelar de la siguiente manera:

  • Un ModifierGroup para el lado (p.ej., "Guarniciones").
    • Cada opción lateral se modela como un Modifier (p.ej., "Papas fritas", "Ensalada").
      • Cada opción de bebida puede hacer referencia a ModifierGroup anidados (p.ej., "Opciones de hielo", "Tamaño de la bebida"), que a su vez hace referencia a Modifiers (p.ej., "Sin hielo", "Bebida grande", respectivamente).
  • Un ModifierGroup para la bebida (p.ej., "Bebidas").
    • Cada opción de bebida se modela como un Modifier.
      • Cada opción de bebida puede hacer referencia a ModifierGroup anidados (p.ej., "Opciones de hielo", "Tamaño de la bebida"), que a su vez hace referencia a Modifiers (p.ej., "Sin hielo", "Bebida grande").
  • Un ModifierGroup para los ingredientes de la entrada. (p. ej., "Extra Cheese", "Bacon").

Disponibilidad

El mensaje Availability en los Item y Modifier te permite especificar lo siguiente:

  • status: STATUS_AVAILABLE, STATUS_OUT_OF_STOCK, etc.
  • daypart_availability: Vincula a IDs de segmentos del día específicos si el elemento solo está disponible en ciertos horarios (p.ej., "Menú de desayuno").

Atributos de integración

Los mensajes Item, Modifier y ModifierGroup contienen un campo integration_attributes. Este campo (ItemIntegrationAttributes, ModifierIntegrationAttributes, etc.) contiene un google.protobuf.Struct llamado custom_integration_attributes. Puedes usarlo para almacenar datos arbitrarios de clave-valor, como los siguientes:

  • Son los IDs de tu sistema de punto de venta (PdV).
  • SKU o cualquier otro código interno
  • Cualquier otro metadato necesario para el procesamiento de pedidos posterior o la integración del POS

El agente de IA pasa estos datos de forma opaca.

Etiquetas

Puedes usar el campo labels en el recurso Menu para adjuntar metadatos a los menús y facilitar la integración y la depuración.

Las etiquetas son una función de conveniencia y no tienen ningún efecto en el comportamiento del agente de IA.

Cómo crear un menú

Los menús se transfieren con la llamada a RPC CreateMenu dentro de MenuService.

Pasos

  1. Transforma tus datos: Convierte los datos de tu menú existentes (de tu POS, API o cualquier otra fuente) en la estructura definida por el mensaje google.cloud.foodorderingaiagent.v1beta.Menu. Esto implica asignar tus elementos, modificadores, categorías y precios a los tipos de mensajes de la API correspondientes.
  2. Construye el CreateMenuRequest:
    • Configura el campo parent (p.ej., projects/PROJECT/locations/LOCATION).
    • Propaga el campo menu con tu objeto Menu transformado.
    • También puedes proporcionar un menu_id.
  3. Llama a la API: Envía el CreateMenuRequest al extremo MenuService.CreateMenu. Primero, la API limpiará el menú, luego lo validará y, por último, devolverá el objeto Menu final.
  4. Cómo controlar las actualizaciones del menú: Cada vez que se actualicen los datos de origen del menú (p.ej., cuando se lanza un producto nuevo o cuando un producto deja de estar disponible), se debe crear un nuevo objeto Menu que refleje los datos de origen actualizados, siguiendo los pasos para controlar las actualizaciones del menú.

Orientación para la transformación de datos

La lógica específica para transformar los datos de tu menú dependerá del formato y la estructura de tu sistema fuente (p.ej., API de POS, esquema de base de datos). A continuación, se muestra un enfoque general:

  • Exportar datos: Obtén una exportación completa de los datos de tu menú, incluidos todos los elementos, modificadores, precios y relaciones.
  • Entidades de mapa:
    • Identifica las entidades correspondientes en el esquema de la API del agente de IA para pedidos de comida para cada elemento de tus datos de origen. Por ejemplo, es probable que los "elementos del menú" de tu POS se asignen a objetos Item. Las "opciones de pedido" o los "complementos" se asignarán a Modifier y ModifierGroup.
    • Establece relaciones con IDs. Por ejemplo, vincula los Items a sus respectivos ModifierGroups con el campo de referencia modifier_groups.
  • Cómo controlar estructuras anidadas: Si tu menú tiene modificadores anidados (p.ej., elegir el sabor de una bebida para el refresco de una comida combinada), modela esto haciendo que Modifier haga referencia a otros ModifierGroup.
  • Completa los atributos: Completa los campos como display_name, base_price, price_adjustment y availability según los datos de origen.
  • Incluye IDs de PdV: Es fundamental que almacenes los IDs internos del PdV o del sistema para cada artículo, modificador y grupo en el campo custom_integration_attributes. Esto te permite traducir el Order que produce el agente a la representación de un pedido final o un carrito en curso de tu aplicación.
  • Secuencias de comandos: Es probable que debas escribir una secuencia de comandos (p.ej., en Python, Node.js o Go) para recuperar datos de tu fuente, realizar la transformación y llamar al método CreateMenu. Esta secuencia de comandos usará las Google Cloud bibliotecas cliente para la autenticación y la interacción con la API.

Flujo de trabajo de transformación conceptual:

En este flujo de trabajo, se describe el proceso de transformación de los datos del menú de un sistema fuente al formato de la API del agente de IA para pedidos de comida:

  1. Extrae y asigna categorías:
    • Identifica categorías o secciones en tus datos de origen (p.ej., "Aperitivos", "Platos principales").
    • Transforma cada uno en un objeto MenuCategory con un id y un display_name únicos.
  2. Extract and Map Items:
    • Identifica los artículos vendibles en tus datos de origen.
    • Transforma cada uno en un objeto Item y completa id, display_name, base_price y availability.
    • Asigna cada Item a sus categorías con el campo category_ids.
    • Almacena los identificadores del sistema fuente (como PLU o SKU) en item.integration_attributes.custom_integration_attributes.
  3. Extract and Map Modifiers:
    • Identifica las personalizaciones, las opciones o los complementos de los artículos en tus datos de origen.
    • Agrupa las opciones relacionadas (p.ej., "Opciones de acompañamiento", "Opciones de bebidas", "Coberturas adicionales") en objetos ModifierGroup Define reglas de selección mínimas y máximas en cada ModifierGroup.
    • Transforma cada opción individual (p.ej., "Papas fritas", "Cola", "Queso extra") en objetos Modifier dentro del ModifierGroup adecuado. Propaga price_adjustment si corresponde.
    • Almacena los identificadores del sistema fuente en modifier_group.integration_attributes.custom_integration_attributes y modifier.integration_attributes.custom_integration_attributes.
  4. Establece relaciones:
    • Para cada Item, completa su campo modifier_groups con referencias a los id de los ModifierGroup que se aplican a él.
    • Si un Modifier permite una mayor personalización (p.ej., elegir un sabor para un modificador de "Soda"), completa su campo modifier_groups para crear modificadores anidados.
  5. Ensambla y procesa:
    • Combina todos los objetos MenuCategory, Item, ModifierGroup y Modifier en las listas dentro de un solo mensaje Menu.
    • Llama a la RPC CreateMenu con el mensaje Menu completamente ensamblado como entrada.

Cómo controlar las actualizaciones del menú

El menú es inmutable. Una vez que se crea un menú con la llamada a RPC CreateMenu, no se puede modificar. Para propagar las actualizaciones del menú en un menú, como cambiar los precios de los elementos, modificar las opciones o ajustar la disponibilidad, debes crear un nuevo recurso de menú llamando a CreateMenu nuevamente. Cada versión de tu menú debe transferirse como un recurso Menu nuevo con un menu_id único.

El proceso para transferir una nueva versión de un menú es idéntico al de transferir el menú por primera vez y se somete a los mismos pasos de saneamiento y validación. Cuando maneje pedidos, el comportamiento del agente siempre reflejará el Menu creado más recientemente asociado con el Store al que se hace referencia en la configuración de la sesión.

Limpieza automática del menú

La API de CreateMenu realiza automáticamente varios pasos de saneamiento para corregir problemas comunes y garantizar que el contenido del menú se represente de manera coherente en toda la API. Las validaciones se aplican después de estas sanitizaciones para simplificar la integración del menú para los clientes:

  • Disponibilidad predeterminada: Los Item y los Modifier sin un Availability.Status explícito se establecen en STATUS_AVAILABLE.
  • Descarta las entidades sin referencia: Los Modifier y los ModifierGroup a los que no se hace referencia de forma transitiva desde ningún Item se quitan del menú, ya que no se pueden ordenar.
  • Se descartan los grupos de modificadores vacíos: Se descartan los ModifierGroup que no contienen modifier_ids y se quitan todas las referencias a ellos.

Después de la sanitización, la API valida el menú según un conjunto estricto de reglas para garantizar que esté bien formado y que el agente de IA lo pueda usar de manera confiable. Si la validación falla, la llamada a CreateMenu devolverá un error que detalla los problemas. Las validaciones clave incluyen las siguientes:

  • Campos obligatorios: Garantiza que estén presentes todos los campos obligatorios, como id, display_name y availability.status.
  • IDs únicos: Todos los Item, Modifier y ModifierGroup deben tener IDs únicos dentro del menú.
  • Nombres visibles únicos:
    • Todos los Item deben tener display_name únicos.
    • Dentro de cualquier ModifierGroup determinado, todos los Modifier incluidos deben tener display_names únicos.
  • Integridad de referencia:
    • Todos los modifier_group_ids a los que hacen referencia los Item o los Modifier deben existir en el menú.
    • Todos los modifier_ids a los que hacen referencia los ModifierGroup deben existir en el menú.
    • Los modificadores predeterminados especificados en ModifierGroupReference deben existir en el ModifierGroup al que se hace referencia.
    • Si un Modifier usa item_id para hacer referencia a un Item, ese Item debe existir.
  • Restricciones de grupos de modificadores:
    • Los campos ModifierGroup no pueden estar vacíos.
    • Se verifica la coherencia lógica de los recuentos de selección mínimos o máximos dentro de los ModifierGroups.
    • Los niveles Item o Modifier de modifier_constraints se validan en función de las restricciones de recuento de selección de los ModifierGroup a los que se hace referencia para garantizar que se puedan satisfacer.
  • Profundidad de anidamiento: La profundidad de los modificadores anidados es limitada (p.ej., Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier… hasta un máximo de 5 niveles
  • Validación de segmentos del día: Si se usan segmentos del día en Availability, deben definirse en el recurso Store asociado.
  • Referencias a elementos modificadores: Los Modifier que hacen referencia a un Item con item_id no pueden tener campos como display_name o availability establecidos, ya que se heredan del Item al que se hace referencia.

Si no se cumple alguna de estas reglas de validación, no se podrá crear ni actualizar el menú. El mensaje de error proporcionará detalles sobre las entidades que causan el incumplimiento.

Referencia de la API

Para obtener detalles completos sobre todos los mensajes y campos, consulta la referencia de RPC de la API del agente de IA para pedidos de comida.

Prácticas recomendadas

  • IDs únicos: Asegúrate de que todos los campos id dentro del alcance de Menu (para Item, Modifier, ModifierGroup, MenuCategory) sean únicos.
  • Nombres claros: Usa display_names claros y fáciles de entender para los clientes. Proporciona display_names distintos para productos semánticamente diferentes, de modo que el agente pueda desambiguar de forma adecuada.
  • Combos de modelos de manera eficaz: Combina modelos como un Item con ModifierGroups que representan guarniciones, bebidas y otras opciones, como se describe en combos de modelos. Esto garantiza que el agente pueda guiar correctamente a los clientes en la selección de combos.
  • Usa atributos de integración: Almacena los identificadores necesarios del sistema interno o del POS en custom_integration_attributes para facilitar la integración de pedidos sin problemas.
  • Administra la disponibilidad: Mantén actualizado el estado Availability.
  • Hacer pruebas exhaustivas: Después de la transferencia, prueba la comprensión del menú por parte del agente con varias combinaciones de pedidos.