Integrar dados de cardápio usando a API do agente de IA do Pedido de comida

Este guia explica como estruturar, transformar e ingerir os dados do cardápio do restaurante na API Menu do agente de IA para pedidos de comida. Assim, o agente de IA entende as opções do cardápio e pode receber pedidos dos clientes com precisão.

Antes de começar

Antes de ingerir e gerenciar cardápios usando a API Food Ordering AI Agent, faça o seguinte:

1. Ative a API Food Ordering AI Agent:

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

2. Verifique se você tem as permissões necessárias do IAM. Conceda o seguinte papel do Identity and Access Management (IAM) ao usuário ou à conta de serviço que interage com a API:

   • Administrador do agente de pedidos de comida (roles/foodorderingaiagent.admin): esse papel oferece acesso total para criar, ler, atualizar e excluir todos os recursos do agente de IA para pedidos de comida, incluindo marcas, lojas e cardápios.

   É possível conceder papéis do IAM usando o console do Google Cloud , a ferramenta de linha de comando gcloud ou a API IAM. Para mais informações, consulte Conceder um papel do IAM.

   Para conceder o papel usando o console Google Cloud :

   1. No console do Google Cloud , acesse a página IAM.
   2. Clique em Adicionar.
   3. Insira o principal (e-mail do usuário ou da conta de serviço).
   4. Selecione a função Administrador do agente de IA para pedidos de comida.
   5. Clique em Salvar.

   Sem as permissões adequadas, as chamadas de API para criar ou modificar marcas, lojas ou menus são negadas. A função Food Ordering Agent Viewer não é suficiente para as tarefas descritas neste guia, já que ela concede apenas acesso de leitura.

Visão geral

A API Menu do agente de IA para pedidos de comida foi projetada para ser flexível e acomodar várias estruturas de cardápio, desde listas curtas de itens independentes até cardápios complexos com modificadores aninhados e refeições combinadas. A API foi criada com base em alguns conceitos principais:

• Menu:o contêiner de nível superior para todas as entidades ordenáveis.
• Item:representa um produto de nível superior do menu que pode ser pedido, como uma refeição, um prato principal ou qualquer produto que possa ser pedido sozinho. Os Items podem fazer referência aos ModifierGroups.
• ModifierGroup:uma coleção de opções Modifier que podem ser aplicadas a um Item ou outro Modifier (permitindo o aninhamento). Por exemplo, "Escolha seu acompanhamento", "Adicionar complementos" ou "Selecione o sabor da bebida".
• Modificador:uma opção individual em um ModifierGroup, como "Batata frita", "Queijo extra" ou "Refrigerante". Os modificadores podem ajustar o preço e também ter seus próprios ModifierGroups aninhados.
• MenuCategory:usado para organizar Items em seções para exibição e compreensão (por exemplo, "Aperitivos", "Hambúrgueres", "Bebidas").

Principais conceitos e estrutura

Esta seção detalha os principais componentes do esquema da API Menu do agente de IA para pedidos de comida e como eles são estruturados. Entender esses conceitos é fundamental para modelar corretamente os dados do menu.

Itens

Cada item diferente no menu precisa ser definido como um Item. Os principais campos incluem:

• id: um identificador exclusivo no menu.
• display_name: o nome voltado ao cliente.
• base_price: o preço base do item.
• modifier_groups: referências a ModifierGroups que podem ser aplicadas a este item.
• category_ids: referências aos IDs de MenuCategory a que este item pertence.
• availability: especifica quando o item está disponível (por exemplo, por status ou período do dia). O padrão é STATUS_AVAILABLE se não for especificado.

Modifiers e ModifierGroups

Os modificadores permitem a personalização de itens.

• ModifierGroups definem um conjunto de opções, incluindo restrições como seleções mínimas ou máximas. Precisa conter pelo menos um Modifier.
• Os Modifiers representam as opções reais. Eles podem ter um price_adjustment e referenciar recursivamente outros ModifierGroups para personalizações aninhadas. Por exemplo, um Item "Combo de refeição" pode ter um ModifierGroup "Escolha sua bebida", e o Modifier "Refrigerante" dentro desse grupo pode ter um ModifierGroup "Escolha o sabor".

Dica: o agente trabalha ativamente com os clientes para atender às restrições especificadas em cada ModifierGroup. Por exemplo, se um Item (por exemplo, "Fajitas para dois") faz referência a um ModifierGroup com min_selection_count 2 (por exemplo, "Duas bebidas"), e um cliente pede Item sem especificar uma seleção para esse ModifierGroup (por exemplo, "Quero as fajitas para duas pessoas"), o agente trabalha com o cliente para atender às restrições (por exemplo, "Quais duas bebidas você quer com isso?").

Exemplo 1: coberturas

Um "X-búrguer com bacon" Item pode fazer referência a uma "Cobertura" ModifierGroup. Esse ModifierGroup teria Modifiers como "Mais queijo", "Sem cebola" etc.

Exemplo 2: refeições combinadas (combos)

Alguns menus têm estruturas complexas com várias opções aninhadas, como refeições combinadas ou "combos". Os combos podem ser modelados como um Item com vários ModifierGroups representando os componentes do combo. Por exemplo, um Item "Combo de hambúrguer", que consiste em um prato principal fixo com várias opções de acompanhamento e bebida, pode ser modelado com:

• Um ModifierGroup para o lado (por exemplo, "Opções laterais").
  • Cada opção de lado é modelada como um Modifier (por exemplo, "Fries", "Salad").
    • Cada opção de bebida pode fazer referência a ModifierGroups aninhados (por exemplo, "Opções de gelo", "Tamanho da bebida"), que, por sua vez, faz referência a Modifiers (por exemplo, "Sem gelo", "Bebida grande", respectivamente).
• Um ModifierGroup para a bebida (por exemplo, "Bebidas").
  • Cada opção de bebida é modelada como um Modifier.
    • Cada opção de bebida pode fazer referência a ModifierGroups aninhados (por exemplo, "Opções de gelo", "Tamanho da bebida"), que, por sua vez, faz referência a Modifiers (por exemplo, "Sem gelo", "Bebida grande").
• Um ModifierGroup para os acompanhamentos do prato principal. (por exemplo, "Extra Cheese", "Bacon").

Disponibilidade

A mensagem Availability em Items e Modifiers permite especificar:

• status: STATUS_AVAILABLE, STATUS_OUT_OF_STOCK, etc.
• daypart_availability: links para IDs de período do dia específicos se o item estiver disponível apenas em determinados horários (por exemplo, "Cardápio do café da manhã").

Atributos de integração

As mensagens Item, Modifier e ModifierGroup contêm um campo integration_attributes. Esse campo (ItemIntegrationAttributes, ModifierIntegrationAttributes etc.) contém um google.protobuf.Struct chamado custom_integration_attributes. Você pode usar isso para armazenar dados arbitrários de chave-valor, como:

• IDs do seu sistema de ponto de venda (PDV).
• SKUs ou outros códigos internos.
• Qualquer outro metadado necessário para o processamento de pedidos downstream ou integração com PDV.

Esses dados são transmitidos de forma opaca pelo agente de IA.

Rótulos

Você pode usar o campo labels no recurso Menu para anexar metadados aos menus e ajudar na integração e depuração.

Os rótulos são um recurso de conveniência e não afetam o comportamento do agente de IA.

Dica: use rótulos para anotar um Menu com o identificador de versão associado, o carimbo de data/hora efetivo ou um URL de onde os dados do menu foram recuperados. Isso é útil para rastrear nuances do comportamento do agente até dados de origem específicos do menu.

Criação de um menu

Os menus são ingeridos usando a chamada de RPC CreateMenu no MenuService.

Etapas

1. Transforme seus dados:converta os dados do menu (do seu PDV, API ou outra fonte) na estrutura definida pela mensagem google.cloud.foodorderingaiagent.v1beta.Menu. Isso envolve mapear seus itens, modificadores, categorias e preços para os tipos de mensagens de API correspondentes.
2. Construa o CreateMenuRequest:
   • Defina o campo parent (por exemplo, projects/PROJECT/locations/LOCATION).
   • Preencha o campo menu com o objeto Menu transformado.
   • Opcionalmente, forneça um menu_id.
3. Chame a API:envie o CreateMenuRequest para o endpoint MenuService.CreateMenu. Primeiro, a API higieniza e valida o menu e retorna o objeto Menu final.
4. Processar atualizações do menu:a cada atualização dos dados de origem do menu (por exemplo, quando um novo produto é lançado ou quando um produto fica indisponível), um novo Menu precisa ser criado refletindo os dados de origem atualizados, seguindo processamento de atualizações do menu.

Orientação para a transformação de dados

A lógica específica para transformar os dados do menu depende do formato e da estrutura do sistema de origem (por exemplo, API de PDV, esquema de banco de dados). Confira uma abordagem geral:

• Exportar dados:obtenha uma exportação completa dos dados do seu cardápio, incluindo todos os itens, modificadores, preços e relações.
• Entidades de mapa:
  • Identifique as entidades correspondentes no esquema da API do agente de IA para pedidos de comida para cada elemento nos seus dados de origem. Por exemplo, os "itens de menu" do seu PDV provavelmente serão mapeados para objetos Item. "Opções de pedido" ou "complementos" serão mapeados para Modifiers e ModifierGroups.
  • Estabeleça relações usando IDs. Por exemplo, vincule Items aos ModifierGroups aplicáveis usando o campo de referência modifier_groups.
• Lidar com estruturas aninhadas:se o menu tiver modificadores aninhados (por exemplo, escolher um sabor de bebida para o refrigerante de um combo), modele isso fazendo com que Modifiers referenciem outros ModifierGroups.
• Preencher atributos:preencha campos como display_name, base_price, price_adjustment e availability com base nos dados de origem.
• Inclua IDs de PDV:armazene os IDs internos de PDV ou do sistema para cada item, modificador e grupo no campo custom_integration_attributes. Isso permite traduzir o Order produzido pelo agente de volta para a representação de um pedido final ou carrinho em andamento do seu aplicativo.
• Scripting:provavelmente será necessário escrever um script (por exemplo, em Python, Node.js, Go) para buscar dados da sua origem, realizar a transformação e chamar o método CreateMenu. Esse script usa as bibliotecas de cliente Google Cloud para autenticação e interação com a API.

Fluxo de trabalho de transformação conceitual:

Este fluxo de trabalho descreve o processo de transformação de dados de cardápio de um sistema de origem para o formato da API Food Ordering AI Agent:

1. Extrair e mapear categorias:
   • Identifique categorias ou seções nos dados de origem (por exemplo, "Entradas", "Pratos principais").
   • Transforme cada um em um objeto MenuCategory com um id e um display_name exclusivos.
2. Extrair e mapear itens:
   • Identifique os itens vendáveis nos dados de origem.
   • Transforme cada um em um objeto Item, preenchendo id, display_name, base_price e availability.
   • Mapeie cada Item para as categorias usando o campo category_ids.
   • Armazene identificadores do sistema de origem (como PLU ou SKU) em item.integration_attributes.custom_integration_attributes.
3. Extrair e mapear modificadores:
   • Identifique personalizações, opções ou complementos de itens nos seus dados de origem.
   • Agrupe opções relacionadas (por exemplo, "Opções de acompanhamento", "Opções de bebida", "Coberturas extras") em objetos ModifierGroup. Defina regras de seleção mínima e máxima em cada ModifierGroup.
   • Transforme cada opção individual (por exemplo, "Fries", "Cola", "Extra Cheese") em objetos Modifier no ModifierGroup apropriado. Preencha price_adjustment se aplicável.
   • Armazene os identificadores do sistema de origem em modifier_group.integration_attributes.custom_integration_attributes e modifier.integration_attributes.custom_integration_attributes.
4. Estabelecer relações:
   • Para cada Item, preencha o campo modifier_groups com referências aos ids de ModifierGroups aplicáveis.
   • Se um Modifier permitir mais personalização (por exemplo, escolher um sabor para um modificador "Refrigerante"), preencha o campo modifier_groups dele para criar modificadores aninhados.
5. Montagem e ingestão:
   • Combine todos os objetos MenuCategory, Item, ModifierGroup e Modifier nas listas em uma única mensagem Menu.
   • Chame a RPC CreateMenu com a mensagem Menu totalmente montada como entrada.

Como lidar com atualizações de cardápio

O menu é imutável. Depois que um menu é criado usando a chamada de RPC CreateMenu, ele não pode ser modificado. Para propagar atualizações em um menu, como mudar preços de itens, modificar opções ou ajustar a disponibilidade, é preciso criar um novo recurso de menu chamando CreateMenu novamente. Cada versão do seu menu precisa ser ingerida como um novo recurso Menu com um menu_id exclusivo.

O processo para ingerir uma nova versão de um cardápio é idêntico ao de ingerir o cardápio pela primeira vez e passa pelas mesmas etapas de higienização e validação. Ao processar pedidos, o comportamento do agente sempre reflete o Menu criado mais recentemente associado ao Store referenciado na configuração da sessão.

Dica: rótulos são uma maneira útil de associar metadados que distinguem Menus relacionados. Diagnosticar problemas operacionais é mais fácil quando cada Menu é anotado com informações que identificam o evento que acionou a criação e a origem do conteúdo.

Limpeza automática de menus

A API CreateMenu executa automaticamente várias etapas de limpeza para corrigir problemas comuns e garantir que o conteúdo do menu seja representado de forma consistente em toda a API. As validações são aplicadas após essas sanitizações para simplificar a integração do menu para os clientes:

• Disponibilidade padrão:Items e Modifiers sem um Availability.Status explícito são definidos como STATUS_AVAILABLE.
• Remover entidades não referenciadas:Modifiers e ModifierGroups que não são referenciados de forma transitiva por nenhum Item são removidos do menu porque não podem ser ordenados.
• Descartar grupos de modificadores vazios:os ModifierGroups que não contêm modifier_ids são descartados, e todas as referências a eles são removidas.

Validação de menu

Após a higienização, a API valida o menu com um conjunto estrito de regras para garantir que ele esteja bem formado e possa ser usado de maneira confiável pelo agente de IA. Se a validação falhar, a chamada CreateMenu vai retornar um erro detalhando os problemas. As principais validações incluem:

• Campos obrigatórios:garante que todos os campos obrigatórios, como id, display_name e availability.status, estejam presentes.
• IDs exclusivos:todos os Items, Modifiers e ModifierGroups precisam ter IDs exclusivos no menu.
• Nomes de exibição exclusivos:
  • Todos os Items precisam ter display_names exclusivos.
  • Em qualquer ModifierGroup, todos os Modifiers contidos precisam ter display_names exclusivos.
• Integridade referencial:
  • Todos os modifier_group_ids referenciados por Items ou Modifiers precisam estar no menu.
  • Todos os modifier_ids referenciados por ModifierGroups precisam estar no menu.
  • Os modificadores padrão especificados em ModifierGroupReference precisam existir no ModifierGroup referenciado.
  • Se um Modifier usar item_id para fazer referência a um Item, esse Item precisará existir.
• Restrições de grupo de modificadores:
  • Os ModifierGroups não podem ficar em branco.
  • As contagens mínimas ou máximas de seleção em ModifierGroup são verificadas para consistência lógica.
  • Os níveis Item ou Modifier modifier_constraints são validados em relação às restrições de contagem de seleção dos ModifierGroups referenciados para garantir que sejam satisfatórios.
• Profundidade de aninhamento:a profundidade de modificadores aninhados é limitada (por exemplo, Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier...) até um máximo de cinco níveis.
• Validação de períodos do dia:se os períodos do dia forem usados em Availability, eles precisarão ser definidos no recurso Store associado.
• Referências de itens modificadores:Modifiers que referenciam um Item usando item_id não podem ter campos como display_name ou availability definidos, já que eles são herdados do Item referenciado.

Se alguma dessas regras de validação falhar, o menu não será criado nem atualizado. A mensagem de erro vai fornecer detalhes sobre quais entidades estão causando a violação.

Referência da API

Para detalhes completos sobre todas as mensagens e campos, consulte a Referência de RPC da API do agente de IA para pedidos de comida.

Práticas recomendadas

• IDs exclusivos:verifique se todos os campos id no escopo Menu (para Item, Modifier, ModifierGroup, MenuCategory) são exclusivos.
• Nomes claros:use display_names claros e fáceis de entender para os clientes. Forneça display_names distintos para produtos semanticamente diferentes e oriente o agente a fazer a desambiguação de maneira adequada.
• Combos de modelos de forma eficaz:modele refeições combinadas como um Item com ModifierGroups representando acompanhamentos, bebidas e outras opções, conforme descrito em refeições combinadas. Isso garante que o agente possa orientar corretamente os clientes nas seleções de combos.
• Use atributos de integração:armazene todos os identificadores necessários de PDV ou sistema interno no custom_integration_attributes para facilitar a integração de pedidos.
• Gerenciar disponibilidade:mantenha o status Availability atualizado.
• Teste exaustivamente:depois da ingestão, teste a compreensão do menu pelo agente com várias combinações de pedidos.