Guia para desenvolvedores de pesquisa conversacional

Este guia detalha como fazer a integração com a API Conversational para oferecer experiências de chat dinâmicas e com tecnologia de IA aos seus clientes. Ao entender diferentes tipos de consultas e aproveitar as respostas da API, você pode oferecer pesquisas de produtos relevantes, responder às dúvidas dos clientes e orientar os usuários finais na jornada de compra.

O conversationalFilteringMode na API Conversacional deixa claras as diferenças entre a pesquisa conversacional e a filtragem de produtos conversacionais.

Fluxo de chamada e configuração da API

A API Conversational é compatível com a pesquisa conversacional:

A API Conversational permite uma experiência de chat em que os usuários enviam consultas e o sistema retorna uma resposta de texto, tipos de consultas classificadas e possíveis opções de pesquisa refinada.

Essa API funciona como um serviço de streaming, permitindo a detecção precoce da intenção da consulta. As interações subsequentes na conversa exigem a anexação de um conversation_id.

Para retornar resultados da pesquisa, a API AI Commerce Search legada precisa ser chamada em paralelo com a API Conversational.

Enviar uma consulta do usuário final

Esta seção descreve como iniciar uma experiência de pesquisa conversacional. Por exemplo, o usuário pode digitar Me ajude a planejar uma festa no campo de pesquisa.

Enviar uma solicitação para a AI Commerce Search

Há dois endpoints de API diferentes:

  1. A API Conversational precisa ser usada para buscar a experiência de conversa.
  2. A API Search principal precisa ser usada para buscar resultados de pesquisa.

Endpoint 1: solicitação de API de conversação

  • Crie uma solicitação de pesquisa conversacional definindo a entrada do usuário como a consulta.
  • A solicitação precisa ser enviada como uma solicitação HTTP POST para o endpoint projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Método HTTP e endpoint

  POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

Solicitação de API Conversacional:

Consulta inicial

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/default_catalog/branches/default_branch",
  "placement": "projects/{project_id}/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your core Search API calls to ensure consistency between LLM answers and search results.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
    // Example: "userId": "user123", "userAgent": "Chrome/120.0"
  },
  "conversationalFilteringSpec": {
    // Optional: Controls conversational filtering behavior. Defaults to DISABLED if unset.
    // "conversational_filtering_mode": "DISABLED" - Otherwise you can also explicitly set to disabled.
}
  • placement: o nome do recurso da posição (como projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Esse é um parâmetro de caminho e é obrigatório.
  • query: a consulta de pesquisa bruta do usuário. Esse campo é obrigatório.
  • branch: o nome do recurso de ramificação, como projects/P/locations/L/catalogs/C/branches/B. Se não for definido, default_branch será usado. Esse campo é obrigatório.
  • visitorId: um identificador exclusivo para rastrear visitantes. Esse campo é obrigatório.
  • conversationId: um ID exclusivo para rastrear sessões de conversa. Para a solicitação initial em uma nova conversa, esse campo precisa estar vazio. Para solicitações subsequentes na mesma conversa, ele precisa ser definido como o conversation_id recebido no ConversationalSearchResponse anterior.
  • searchParams: (opcional) parâmetros padrão da Pesquisa principal, como filter, canonicalFilter, sortBy e boostSpec. É fundamental que esses parâmetros reflitam a configuração usada nas chamadas principais da API Search para garantir a consistência entre as respostas do LLM e os resultados da pesquisa de produtos exibidos.
  • userInfo: (opcional) informações do usuário para personalização avançada. Pode incluir userId, user_agent, direct_user_request (booleano).
  • conversationalFilteringSpec: (opcional) especifica o modo de filtragem de conversas. Se não for definido, o padrão será "DISABLED".

    mode: integre a API Conversational usando um destes três modos para controlar a filtragem de produtos de conversação:

    • DISABLED: nesse modo, o cliente implementa apenas a pesquisa conversacional. Esse é o modo preferido para este guia de implementação da pesquisa conversacional.

      • Exemplo de solicitação de API

              placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: DISABLED
        }

      Exemplo de resposta da API

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
    • ENABLED: nesse modo, o cliente implementa todos os recursos de conversa, incluindo a pesquisa conversacional e a filtragem conversacional de produtos.

      • Consulte o guia adicional sobre como integrar os dois produtos de conversa.

      Exemplo de solicitação de API

              placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: ENABLED
        }

      Exemplo de resposta da API

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
        conversational_filtering_result: {
            followup_question{
              followup_question: "What is the size?"
              suggested_answers {
                product_attribute_value {
                  name: "size",
                  value: "12oz"
                }
              }
        }
        }
    • CONVERSATIONAL_FILTER_ONLY: se escolhido, o cliente apenas implementa a filtragem de produtos conversacional. Com esse modo selecionado, o usuário tem acesso apenas à filtragem conversacional de produtos, sem gerar uma resposta de LLM, classificação de consulta ou consultas de pesquisa sugeridas.

      • Consulte o guia para desenvolvedores de filtros de produtos conversacionais para mais informações.

Endpoint 2: solicitação de API Core Search

Há duas abordagens principais para mostrar resultados de pesquisa na sua interface da Web.

Opção 1: sempre mostrar os resultados da pesquisa

Se o design da experiência do usuário determinar que os resultados da pesquisa devem sempre ser mostrados, independentemente da saída da conversa, como em uma área dedicada de resultados da pesquisa ao lado do chat, envie a consulta original do usuário para a API principal Pesquisa de produtos com sua chamada para a API Conversational. Isso ajuda a garantir que as informações dos produtos estejam disponíveis imediatamente.

Opção 2: mostrar resultados da pesquisa com base na saída da conversa

Se o design da experiência do usuário for mais dinâmico e você só quiser mostrar resultados da pesquisa dependendo da resposta da API Conversacional, como apenas para consultas SIMPLE_PRODUCT_SEARCH ou sempre que sugestões refined_search forem fornecidas, aguarde a resposta da API Conversacional antes de enviar qualquer consulta à API Pesquisa de produtos principal. Se houver uma resposta, use a consulta refined_search fornecida para buscar resultados de produtos.

Independente da opção de interface do usuário escolhida, quando você precisar buscar resultados reais de produtos, poderá fazer uma chamada para a API AI Commerce Search. Para mais informações, consulte Entender a classificação da intenção do usuário e as ações do varejista.

Método HTTP e endpoint

    POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search

Solicitação principal da API Product Search:

Consulta inicial

    {
      "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search",
        // Or if using legacy placements:
        // "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
      "query": "Help me plan a party", // This is the original user query
      "visitorId": "your_visitor_id",
      "branch": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch",
      "pageSize": 20, // Optional: Number of results to return per page
      "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")", // Mirroring the filter from the Conversational Commerce API
      "orderBy": "relevance DESC", // Optional
      "userInfo": {
        // Optional: User information for enhanced personalization, should mirror Conversational Commerce API
        // "userId": "user123", "userAgent": "Chrome/120.0"
      },
      "searchMode": "PRODUCT_SEARCH" // Typically for product searches
    }
  • placement (obrigatório): o nome do recurso da configuração de exibição da AI Commerce Search ou do posicionamento legado. Exemplo: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
  • query: obrigatório. A consulta de pesquisa. Pode ser a entrada bruta do usuário, como Me ajude a planejar uma festa, ou um refinedSearch.query mais otimizado, como suprimentos e decorações para planejamento de festas, obtido da resposta da API Conversational Commerce.
  • visitorId: obrigatório. Um identificador exclusivo para rastrear visitantes. Isso precisa ser consistente com o visitorId enviado à API Conversational Commerce para o mesmo usuário final.
  • branch (obrigatório): o nome do recurso de ramificação, como projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
  • pageSize (opcional): o número máximo de produtos a serem retornados.
  • filter (opcional): usado para filtrar os resultados da pesquisa. É aqui que você aplica os filtros que espelham o que você envia em "searchParams" para a API Conversational Commerce, garantindo a consistência.
  • orderBy (opcional): especifica a ordem em que os produtos são retornados (por relevância ou preço, por exemplo).
  • userInfo (opcional): informações do usuário para personalização, que precisam ser consistentes com a chamada de API Conversational Commerce.
  • searchMode (opcional): define o comportamento da pesquisa. PRODUCT_SEARCH é comum para consultas gerais de produtos.

Entender a resposta

Este exemplo de código demonstra uma resposta da API Conversational Commerce.

A resposta da API (ConversationalSearchResponse) inclui query_types, conversational_text_response (se aplicável), opções de refined_search e, possivelmente, um followup_question ou conversational_filtering_result. O conversation_id é essencial para continuar a sessão.

Resposta da AI Commerce Search

Este exemplo de código demonstra uma resposta da API Conversational:

Resposta inicial

    {
      "userQueryTypes": ["INTENT_REFINEMENT"],
      "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
      "followupQuestion": {
        "followupQuestion": "What kind of party are you planning?"
      },
      "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
      "refinedSearch": [
        { "query": "Decorations" },
        { "query": "Snacks" },
        { "query": "Party Supplies" },
        { "query": "Drinks" },
        { "query": "Cake" }
      ],
      "state": "SUCCEEDED"
    }

O que os varejistas devem fazer com a resposta (geral)

Renderize estes campos da resposta:

  • user_query_types: esse campo fornece as classificações da intenção do usuário. Para ações detalhadas com base nesses tipos, consulte Entender a classificação da intenção do usuário e as ações do varejista.
  • conversation_id: você pode armazenar esse ID exclusivo no armazenamento de sessão do navegador ou em um armazenamento semelhante do lado do cliente para manter a sessão de conversa com o servidor. Isso é crucial para distinguir entre várias conversas em andamento de um único comprador. Seu modelo retém o contexto para um determinado conversation_id. O envio de um novo conversation_id inicia uma nova sessão. Recomendamos definir a duração da sessão, como 30 minutos de inatividade.
  • refined_search: é uma lista de consultas de pesquisa refinadas propostas usadas para buscar os resultados relevantes. Para SIMPLE_PRODUCT_SEARCH, é sempre uma única consulta. Para outras consultas que buscam respostas de LLM, é um ou mais. As consultas refined_search podem ser usadas para chamadas à API Search principal (SearchService.Search) ou também podem ser mostradas ao usuário como sugestões.
  • conversational_text_response: mostre esse texto ao usuário como a principal resposta gerada com IA para a consulta dele.
  • followup_question: opcional. O followup_question é exibido.
  • state: esse campo indica o estado da geração de respostas ("STREAMING" ou "SUCCEEDED"). Você pode usar isso para feedback da experiência do usuário, como mostrar um indicador de carregamento até "SUCCEEDED". Mais detalhes sobre isso na próxima seção.

Entender a API de streaming

A API Conversational Commerce funciona como um serviço de streaming. Isso significa que o usuário recebe partes da resposta em vários blocos, em vez de uma única carga completa.

  • Por que fazer transmissões ao vivo? A geração de texto com LLM pode levar algum tempo. O streaming permite que você aja mais rápido.
  • Primeiro trecho da resposta (instantâneo):
  • Contém consultas userQueryTypes e refinedSearch.
  • state: "STREAMING"
  • Próximos trechos:
  • Conter partes do conversationalTextResponse à medida que ele é gerado.
  • Último trecho:
  • Contém o conversationalTextResponse completo.
  • state: "SUCCEEDED"
  • Insight útil:você pode determinar a intenção do usuário imediatamente no primeiro bloco e começar a buscar resultados de produtos em paralelo enquanto a resposta de texto da IA ainda está carregando.

O primeiro bloco da resposta inclui as consultas query_types e refined_search, e o state é indicado como STREAMING. Essa detecção precoce de intenção e a disponibilidade imediata de refinamentos de pesquisa permitem que seu modelo tome decisões rápidas sobre como lidar com a consulta do usuário e gerenciar a experiência dele em relação à latência das respostas do LLM:

  • Para tipos de consulta que não esperam uma resposta de texto conversacional, como SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT:
    • Como query_types está no primeiro bloco, o sistema sabe imediatamente que não vai receber uma resposta do LLM. Você pode continuar com o processamento predefinido para esses tipos, como mostrar uma mensagem estática ou redirecionar para o suporte, sem esperar mais respostas da conversa.
    • Especificamente para SIMPLE_PRODUCT_SEARCH, seu sistema pode fazer uma chamada direta para a API Search principal usando a consulta refined_search recebida no primeiro bloco. Isso ajuda a garantir que os resultados da pesquisa sejam mostrados com o mínimo de atraso, atendendo aos SLAs típicos da experiência de pesquisa.
  • Para tipos de consulta que não esperam uma resposta de texto conversacional, como INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT:
    • Você recebe as consultas query_types e refined_search no bloco inicial. Você pode iniciar imediatamente uma chamada paralela para a API Search principal usando essas consultas refined_search para começar a carregar os resultados de produtos.
    • Os próximos blocos são transmitidos, contendo diferentes seções da resposta de texto da conversa. Durante esse período, o state permanece "STREAMING".
    • Por fim, o último bloco inclui a resposta completa em texto da conversa, e o state muda para "COMPLETED".
    • Essa abordagem de streaming permite uma experiência fluida para o usuário final, em que os resultados da pesquisa podem começar a ser carregados enquanto o resumo de IA é gerado. Você pode mostrar um indicador de carregamento para a resposta da conversa ou apresentar a resposta depois que ela for totalmente transmitida.

Entender a classificação da intenção do usuário e as ações do varejista

O classificador de intents decide como processar a consulta do usuário e qual modo de conversa iniciar.

O campo query_types na resposta é uma lista que indica a classificação ou as classificações da intenção do usuário. Seu sistema precisa lidar com eles da seguinte maneira. Observação: conversational_text_response se refere à resposta de linguagem natural gerada com IA da API.

O campo userQueryTypes (no primeiro bloco de resposta) é o mais importante para determinar a próxima ação do seu aplicativo:

  • SIMPLE_PRODUCT_SEARCH: vestido vermelho
    • Resposta da API: nenhum conversational_text_response. Retorna uma única consulta refinedSearch.
    • Sua ação: chame imediatamente a API Search com o refinedSearch.query. Transição para uma página de resultados da pesquisa padrão ou mostrar resultados.
  • INTENT_REFINEMENT / PRODUCT_COMPARISON / BEST_PRODUCT: planejar uma festa
    • Resposta da API: fornece consultas conversationalTextResponse, refinedSearch e talvez um followupQuestion.
    • Sua ação: mostre a resposta de texto da IA. Use as consultas refinedSearch para preencher carrosséis ou sugestões de produtos. Exiba o followupQuestion.
  • Consultas de suporte: inclua ORDER_SUPPORT e STORE_RELEVANT.
    • Resposta da API: nenhum conversational_text_response.
    • Sua ação: redirecione o usuário para a página adequada, como Rastreamento de pedidos, Localizador de lojas, ou mostre uma resposta predefinida.

A pesquisa conversacional usa categorias de consultas de pesquisa para determinar se uma resposta baseada em LLM é gerada e como as consultas do usuário final são processadas pelas APIs Conversational e Search nestes cenários:

Categorias Classificações de consulta
#1. Consultas irrelevantes que não exigem uma resposta de LLM
  • QUERY_TYPE_UNSPECIFIED: tipo de consulta não especificado.
  • RETAIL_IRRELEVANT: consultas irrelevantes para o domínio de varejo, por exemplo, uma consulta adversária (como como fazer uma bomba),uma consulta de conversa (como como você está?) ou uma consulta de jailbreak (como escreva um poema).
  • BLOCKLISTED: consultas explicitamente bloqueadas pelos clientes de comércio, como Quais são os efeitos colaterais do Advil?
#2. Consultas de suporte e informações
  • ORDER_SUPPORT: consulta complementar ou de suporte (como Rastrear meu pedido, Status do pedido 12345).
  • DEALS_AND_COUPONS: consultas relevantes para ofertas, promoções, ofertas de produtos e descontos (como Há alguma oferta para o Dia de Ação de Graças?).
  • STORE_RELEVANT: consultas relevantes para localização da loja, incluindo horário de trabalho e disponibilidade de estoque de produtos (como Temos leite em estoque?).
  • RETAIL_SUPPORT: consultas relevantes para compras, incluindo formas de pagamento (Qual forma de pagamento vocês aceitam?).
#3. Pesquisas de palavras-chave que não exigem LLM

Solicitação de API de conversa:

Consulta inicial

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "show me some monster energy drinks",
  "visitorId": "test"
}

Resposta da API de conversa:

Resposta inicial

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9",
  "refinedSearch": [
    {
      "query": "monster energy drinks"
    }
  ]
}

Solicitação de API Search:

Consulta complementar

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "monster energy drinks",
  "visitorId": "test"
}
  • SIMPLE_PRODUCT_SEARCH: pesquisa básica de produtos, como Vestido vermelho ou Mostre alguns energéticos Monster.
#4. Consultas de busca de respostas do LLM

Solicitação de API de conversa:

Consulta inicial

  {
    "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
    "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
    "query": "Compare 1% milk with 2% milk",
    "visitorId": "test"
  }

Resposta da API de conversa:

Resposta inicial

{
  "userQueryTypes": ["PRODUCT_COMPARISON"],
  "conversationalTextResponse": "1% milk contains 110 calories, 1.5 g of saturated fat, and 140 mg of sodium per cup. 2% milk is reduced fat with 37% less fat than regular milk and contains vitamins A & D.",
  "conversationId": "0e1cfdac-802f-422d-906e-9fc9f9d733ba",
  "refinedSearch": [
    {
      "query": "1% milk"
    },
    {
      "query": "2% milk"
    }
  ]
}

Solicitação de API Search:

Consulta complementar

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "1% milk",
  "visitorId": "test"
}
  • PRODUCT_DETAILS: o usuário está procurando detalhes e especificações do produto, como mostre as especificações de [nome do produto], qual é o teor de proteína do leite com 2% de gordura?
  • PRODUCT_COMPARISON: comparação de produtos, como compare [nome do produto] e [nome do produto], compare leite com 1% e 2% de gordura.
  • BEST_PRODUCT: consultas com o padrão mais correspondente, como Qual é o biscoito mais saudável? Qual é a melhor marca de leite?
#5. Refinamento de intents

Solicitação de API de conversa:

Consulta inicial

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "Help me plan a party",
  "visitorId": "test"
}

Resposta da API de conversa:

Resposta inicial

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}
  • INTENT_REFINEMENT: o tipo não está claro e pode ser necessário uma conversa ou refinamento para esclarecer, como Me ajude a planejar uma festa. Essa é geralmente a intenção mais usada nas conversas.

Categoria 1. Consultas irrelevantes que não exigem uma resposta de LLM

  • QUERY_TYPE_UNSPECIFIED:
    • Nenhum conversational_text_response é fornecido.
    • Ação: processe como um caso padrão ou de erro. Você pode pedir esclarecimentos ao usuário ou direcioná-lo para onde ele pode receber ajuda geral.
  • RETAIL_IRRELEVANT:
    • Nenhum conversational_text_response é fornecido.
    • Ação: mostre uma mensagem adequada, como Não posso responder a essa pergunta ou Sou um assistente de compras. Como posso ajudar?, conforme definido pelo design do seu aplicativo.
  • BLOCKLISTED:
    • Nenhum conversational_text_response é fornecido.
    • Ação: siga sua política de lista de bloqueio, geralmente mostrando uma mensagem genérica de não é possível atender a esta solicitação.

Categoria 2. Consultas de suporte e informações

Para esses tipos, a API não fornece um conversational_text_response direto por padrão, mas você tem opções para direcionar aos links ou recursos certos.

  • ORDER_SUPPORT:
    • Ação padrão: nenhum conversational_text_response é fornecido. Sua interface da Web precisa mostrar uma mensagem padrão, links relevantes ou redirecionar a consulta para sua própria API de suporte dedicada ou canal de atendimento ao cliente.
  • DEALS_AND_COUPONS:
    • Ação padrão: nenhum conversational_text_response é fornecido. Sua interface da Web precisa mostrar uma mensagem padrão, links relevantes ou redirecionar a consulta para seu sistema de ofertas ou promoções.
  • STORE_RELEVANT:
    • Ação padrão: nenhum conversational_text_response é fornecido. Sua interface da Web precisa mostrar uma mensagem padrão, links relevantes ou redirecionar a consulta para seu próprio localizador de lojas ou sistema de informações.
  • RETAIL_SUPPORT:
    • Ação padrão: nenhum conversational_text_response é fornecido. Sua interface da Web precisa mostrar uma mensagem padrão, links relevantes ou redirecionar a consulta para seu próprio sistema de perguntas frequentes e informações.

Categoria 3. Pesquisas por palavras-chave que não exigem respostas de LLM

  • SIMPLE_PRODUCT_SEARCH:
    • Nenhuma resposta de texto conversacional é gerada.
    • Ação: a resposta da API sempre retorna uma única consulta refined_search. Essa consulta refinada funciona como um termo de pesquisa sugerido. Faça uma chamada direta para a API Search principal (SearchService.Search) e busque resultados de produtos relevantes usando a consulta original ou a consulta refined_search. O refined_search.query pode não ser diretamente da entrada do usuário final atual, mas também pode ser derivado do contexto do histórico de chat. Por exemplo, se um usuário final refinou vestido de festa para vermelhos, a consulta refinada pode se tornar vestido de festa vermelho.
      • Para interfaces de conversação (como bots de chat): é altamente recomendável usar o refined_search.query fornecido pela API. Em um fluxo de conversa, consultas em linguagem natural, como "você pode me ajudar a encontrar bananas", são otimizadas automaticamente pela API em um termo de pesquisa de produto preciso ("bananas"), resultando em resultados de produtos mais relevantes.
      • Para experiências de pesquisa principais (como a página de resultados da pesquisa): você pode usar o refined_search.query da API ou a consulta original fornecida pelo usuário final, porque é mais provável que a consulta original já seja um termo de pesquisa de produto preciso. Escolha a opção que melhor se adapta à sua interface da Web e à estratégia de exibição de resultados da pesquisa.
    • Opções de experiência do usuário: a conversa não precisa terminar para consultas de SIMPLE_PRODUCT_SEARCH. O usuário pode continuar a conversa transmitindo o conversation_id em solicitações subsequentes.
      • Opção A: encerrar a interface da Web de conversa: muitos varejistas optam por fazer a transição do usuário para uma página de resultados da pesquisa padrão assim que um SIMPLE_PRODUCT_SEARCH é detectado, fechando a janela de chat. Nesse cenário, se o usuário final inserir uma nova consulta na caixa de pesquisa padrão sem o conversation_id anterior, ela será tratada como uma conversa nova e separada, e um novo conversation_id será emitido.
      • Opção B: continuar a interface da Web de conversa: os varejistas podem manter a janela de chat aberta. Isso permite que o usuário volte para um modo de conversa. A decisão de implementar a opção A ou B depende totalmente da experiência do usuário preferida pelo varejista.

    Para atribuir consultas de pesquisa a interações de conversa e usar todos os recursos de análise na AI Commerce Search, é fundamental fazer a inclusão de tags de eventos corretamente:

    1. Recuperar conversation_id. Quando você faz uma chamada de API conversationalSearch, o ConversationalSearchResponse.conversation_id é retornado.
    2. Adicionar tag aos eventos do usuário. Nos casos em que a resposta da conversa leva a uma consulta de pesquisa, como se o sistema executar automaticamente uma pesquisa com base na consulta refinada para SIMPLE_PRODUCT_SEARCH, você precisa incluir uma tag no evento de usuário de pesquisa subsequente (UserEvent) com o mesmo conversation_id recebido no ConversationalSearchResponse.

Ao fazer a inclusão de tag correta de UserEvent.conversation_id, sua análise pode atribuir com precisão as consultas de pesquisa às interações de conversa anteriores, fornecendo insights valiosos sobre o comportamento do usuário e os caminhos de conversão.

Categoria 4. Consultas de busca de respostas de LLM

Para esses tipos de consulta, a API gera uma conversational_text_response (resposta do LLM) e também pode fornecer uma ou mais consultas refined_search. A conversa não termina, e o usuário final pode continuar.

  • PRODUCT_DETAILS:
    • Ação: o conversational_text_response fornece os detalhes do produto solicitado. Seu sistema precisa mostrar essas informações de forma clara para o usuário.
    • A resposta também inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para buscar resultados da pesquisa usando a API Search principal.
  • PRODUCT_COMPARISON:
    • Ação: o conversational_text_response oferece uma comparação dos produtos especificados. Seu sistema precisa mostrar essas informações de forma clara para o usuário.
    • A resposta inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para buscar resultados da pesquisa usando a API Search principal.
  • BEST_PRODUCT:
    • Ação: o conversational_text_response oferece recomendações ou informações sobre os produtos que melhor correspondem à consulta. Seu sistema vai mostrar essas informações.
    • A resposta inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para buscar resultados da pesquisa usando a API Search principal.

Categoria 5. Refinamento de intents

  • INTENT_REFINEMENT:
    • Ação: a resposta inclui conversational_text_response, um followup_question e refined_search (uma ou mais consultas de pesquisa sugeridas). A ordem de exibição recomendada é a seguinte:
      1. conversational_text_response
      2. Sugestões de refined_search: elas são ordenadas e classificadas. Por isso, é importante mostrá-las na mesma ordem da resposta.
      3. Followup_question
    • A resposta inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para buscar resultados da pesquisa usando a API Search principal.
    • Para interações subsequentes, envie a resposta do usuário junto com o conversation_id.

Mostrar consultas sugeridas para produtos

Veja como configurar a Pesquisa Google para mostrar perguntas e sugestões de produtos na pesquisa conversacional.

Quando a API Conversational retorna consultas refinedSearch, elas representam excelentes oportunidades para orientar o usuário final a produtos relevantes. Isso é particularmente útil para a categoria 4 (consultas de busca de respostas de LLM) e a categoria 5 (INTENT_REFINEMENT).

Recomendação

  • Mostrar: apresente as principais consultas N (1 a 3, pendente de teste sobre o número ideal para sua interface da Web) refinedSearch ao usuário.
  • Mecanismo: essas consultas sugeridas precisam ser executadas pela API Search principal (SearchService.Search) em segundo plano ou após a interação do usuário.
  • Apresentação: mostre os resultados como carrosséis interativos ou cards clicáveis, permitindo que o usuário navegue por categorias de produtos relacionados ou itens específicos. Isso oferece valor imediato e ajuda a diminuir a distância entre a interação por conversa e a descoberta de produtos.

Solicitação de API Search:

Consulta complementar

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Decorations",
  "visitorId": "test"
}

Eventos a serem enviados para a AI Commerce Search

É importante atribuir com precisão as consultas de pesquisa às interações conversacionais e usar todos os recursos de análise na Pesquisa de comércio com IA usando a inclusão de tags de eventos adequada:

  1. Recuperar conversation_id. Quando você faz uma chamada de API conversationalSearch, o ConversationalSearchResponse.conversation_id é retornado.
  2. Adicionar tag aos eventos do usuário. Nos casos em que a resposta da conversa leva a uma consulta de pesquisa, como ao exibir uma sugestão refined_search em que o usuário final clica, ou se o sistema executa automaticamente uma pesquisa com base na consulta refinada, marque esse evento de usuário de pesquisa subsequente (UserEvent) com o mesmo conversation_id recebido no ConversationalSearchResponse.

Ao fazer a inclusão de tag correta de UserEvent.conversation_id, sua análise pode atribuir com precisão as consultas de pesquisa às interações conversacionais anteriores, fornecendo insights valiosos sobre o comportamento do usuário e os caminhos de conversão.

Continuar a conversa

Esta seção descreve como as sessões de pesquisa conversacional são mantidas pela API Conversational e continuam nesta etapa final.

A API Conversational usa um conversation_id para gerenciar conversas em andamento. Para garantir a consistência entre as respostas do LLM e os resultados da pesquisa, as solicitações Conversational API subsequentes precisam incluir SearchParams que reflitam a configuração das chamadas principais da API Search.

Processamento de sessões

  • Inicie uma conversa:
    • Descrição: para iniciar uma nova conversa, o cliente omite o conversationId da solicitação de API.
    • Quando iniciar uma nova conversa: um cliente pode querer iniciar uma nova conversa, recebendo um novo conversationId da resposta da API, em vários cenários comuns de experiência do usuário:
      • Nova guia ou sessão: quando um cliente abre seu site em uma nova guia do navegador ou inicia uma sessão completamente nova.
      • Nova consulta original: em alguns designs de UX, se um cliente inserir uma consulta nova e não relacionada, você poderá reiniciar o fluxo de conversa para garantir o contexto mais relevante.
      • Botão "Reiniciar conversa": se a interface da Web tiver um botão explícito Iniciar nova conversa ou Redefinir conversa, clicar nele vai acionar uma nova sessão de conversa.
    • Integração da API de conversa: a resposta da API inclui um novo conversationId usado para solicitações subsequentes.
  • Continuar a conversa:
    • Descrição: o Conversational API retorna um conversation_id como parte da resposta da API. Esse ID precisa ser enviado em solicitações de acompanhamento para continuar a mesma conversa. Isso ajuda a garantir que a pesquisa conversacional responda às consultas do usuário com base no histórico da conversa nessa sessão, abrangendo o query do usuário final, o conversational_text_response e o followup_question.
    • Integração da API Conversational: o cliente transmite o conversation_id da resposta anterior no ConversationalSearchRequest.
  • Garanta a consistência dos resultados da pesquisa:
    • Descrição: para garantir que as respostas do LLM sejam consistentes com os resultados da pesquisa mostrados ao usuário, o cliente precisa usar searchParams na solicitação Conversational API. Esses parâmetros de pesquisa precisam ter a mesma configuração (por exemplo, filtros, ordem de classificação) das chamadas Search API feitas para recuperar resultados de produtos.
    • Integração da API Conversational: o objeto searchParams em ConversationalSearchRequest precisa ser preenchido de maneira idêntica ao SearchRequest usado para a pesquisa principal de produtos.

Enviar uma solicitação para a AI Commerce Search

Você pode extrair o conversation_id do armazenamento de sessão. A solicitação precisa incluir o novo query do cliente, que pode ser uma resposta à pergunta da resposta anterior. A solicitação também precisa incluir o refined_search.query mais recente da resposta anterior se o usuário final estiver agindo com base em uma consulta refinada. Caso contrário, ela precisa incluir uma consulta completamente nova e não relacionada, além do conversationId. Não se esqueça de incluir searchParams consistentes.

  • Cenário 1: barra de pesquisa única e conversa persistente: se a interface de pesquisa tiver apenas uma barra de pesquisa principal ou uma janela de conversa persistente, o conversationId não será redefinido, mesmo que o usuário final digite uma consulta nova e aparentemente não relacionada. O sistema usa o histórico de conversa atual (vinculado ao conversationId) para fornecer respostas contextualmente relevantes.
  • Cenário 2: janela de conversa e janela de consulta separadas: se a interface de pesquisa oferecer uma janela de chat de conversa distinta e uma barra de consulta de pesquisa padrão separada (como uma caixa de pesquisa em todo o site), inserir uma nova consulta na barra de pesquisa padrão pode sinalizar implicitamente a intenção de iniciar uma nova pesquisa não relacionada, o que pode levar à redefinição do conversationId para essa ação de pesquisa específica. No entanto, na janela de conversa dedicada, o conversationId precisa ser mantido para garantir a continuidade.

Em última análise, a decisão de quando reutilizar ou redefinir o conversationId é uma escolha de design para otimizar a experiência de conversa dos seus clientes.

Método HTTP e endpoint (igual à consulta inicial)

POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

Solicitação de API Conversacional:

Consulta complementar

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {
    "filter": "categories:(\"Birthday Party Supplies\")"
  }
}

Resposta da API de conversa:

Resposta de acompanhamento

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

Exemplos de um usuário final que continua recebendo perguntas:

  • Pergunta do usuário: Me ajude a planejar uma festa.
  • Resposta do sistema: Que tipo de festa você está planejando?
  • Resposta do usuário: Uma festa de aniversário.

O que os varejistas devem fazer com a resposta

A maneira de renderizar campos é semelhante à resposta inicial, mas observe as mudanças que refletem a conversa contínua:

  • refined_search: esse campo contém consultas atualizadas que incorporam a entrada mais recente do usuário final. Atualize o console do cliente para a consulta atual de acordo com a mudança (por exemplo, mostrando que a consulta voltada ao usuário mudou de "decorações" para "decorações de festa de aniversário" ou "itens de festa de aniversário"). As consultas refined_search podem ser usadas para chamadas à API Search principal (SearchService.Search) ou também podem ser mostradas ao usuário final como sugestões.
  • conversational_text_response: mostra a nova resposta de texto gerada por IA relevante para a última interação.
  • followup_question: se a conversa precisar continuar para mais refinamentos, um novo followup_question será fornecido.

Eventos a serem enviados para a AI Commerce Search

A inclusão de tags de eventos é importante para atribuir consultas de pesquisa com precisão a interações de conversa e usar os recursos de análise da Pesquisa de agentes para comércio.

Há duas etapas no processo de inclusão de tag de evento:

  1. Recuperar conversation_id. Quando você faz uma chamada de API conversationalSearch, o ConversationalSearchResponse.conversation_id é retornado.

  2. Adicionar tag aos eventos do usuário. Nos casos em que a resposta da conversa leva a uma consulta de pesquisa, como ao mostrar uma sugestão refined_search, ou se o sistema executa automaticamente uma pesquisa com base na consulta refinada, marque esse evento de usuário de pesquisa subsequente (UserEvent) com o mesmo onversation_id recebido no ConversationalSearchResponse.

Ao fazer a inclusão de tag correta de UserEvent.conversation_id, sua análise pode atribuir com precisão as consultas de pesquisa às interações conversacionais anteriores, fornecendo insights valiosos sobre o comportamento do usuário final e os caminhos de conversão.

Integrar o agente à filtragem de produtos por conversa

Este guia descreve como fazer a integração com a API Conversacional e a filtragem de produtos conversacionais para oferecer uma experiência de compra com tecnologia de IA. Quando conversationalFilteringSpec.mode é definido como ENABLED, seu sistema pode fazer a transição direta entre interações conversacionais abertas e filtragem guiada de produtos, oferecendo uma jornada do usuário altamente refinada.

Entender a interação

Quando a pesquisa conversacional e a filtragem conversacional de produtos estão ativadas, o sistema aproveita os pontos fortes de cada uma. A pesquisa conversacional lida com consultas amplas, fornece respostas geradas com IA e refina as intenções iniciais. Já a filtragem conversacional de produtos orienta os usuários na seleção de atributos do produto específicos usando um modelo de interação simplificado com base em chips ou blocos.

O ponto de interação e possível transição entre esses dois modos ocorre quando a classificação da API Conversational Commerce leva a uma pesquisa orientada a produtos, especificamente SIMPLE_PRODUCT_SEARCH. Nesse ponto, a API pode fornecer uma consulta de pesquisa direta ou, se a intenção do usuário puder ser mais refinada, ela vai acionar um fluxo de filtragem guiada usando a filtragem conversacional de produtos.

Um princípio fundamental dessa integração é que todas as entradas de texto livre são processadas pela API Conversational Commerce, enquanto os cliques em respostas sugeridas que aparecem como chips são processados pela filtragem de produtos conversacionais.

Enviar consulta do usuário

Exemplo de entrada do usuário: Me ajude a planejar uma festa

Para ativar a pesquisa conversacional e a filtragem conversacional de produtos, verifique se o ConversationalSearchRequest inclui esta configuração:

Solicitação de API Conversational Commerce: consulta inicial

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query, or populate for ongoing conversation
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your Commerce Search API calls to ensure consistency.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
  },
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED" // Crucial for enabling product filtering
  }
}

As principais configurações são:

  • Conversational_filtering_mode: ENABLED: ao definir esse campo como ENABLED no seu conversationalFilteringSpec, você informa à API que seu sistema pode processar a filtragem de produtos conversacionais, permitindo que a API forneça respostas relevantes específicas para a filtragem.

Resposta inicial: refinamento de intent

O campo userQueryTypes continua sendo fundamental para entender a intenção do usuário. Para uma consulta inicial ampla como Me ajude a planejar uma festa,a API provavelmente vai classificar como INTENT_REFINEMENT se uma pesquisa de produto mais específica não estiver imediatamente clara.

Resposta do Google

Resposta da API Conversational Commerce: consulta inicial

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}

Ação

  1. Exiba o conversationalTextResponse.
  2. Apresente as sugestões de refinedSearch como ícones clicáveis para Decorações, Snacks. Como alternativa, chame a API Commerce Search em paralelo usando as consultas refined_search para mostrar resultados de produtos relevantes, como Decorações, Snacks em um carrossel, ao lado da troca de mensagens.
  3. Mostre a followupQuestion: Que tipo de festa você está planejando?
  4. Permitir que a entrada livre do usuário avance a conversa.

Inclusão de tags e análise de eventos

Para garantir análises e atribuições precisas na interação inicial da conversa:

  • Recuperar conversation_id. Capture o conversation_id do ConversationalSearchResponse. Esse ID é crucial para vincular todas as ações subsequentes a essa sessão de conversa específica.
  • Adicionar tag aos eventos do usuário. Se a resposta da conversa levar a uma consulta de pesquisa, como quando seu sistema executa automaticamente uma pesquisa com base em uma consulta refined_search, ou se o usuário clicar em uma sugestão refined_search, marque esse evento de usuário de pesquisa subsequente (UserEvent) com o mesmo conversation_id.

Consulta complementar

Quando o usuário responde ao followupQuestion, a conversa é refinada.

Exemplo de entrada do usuário: Uma festa de aniversário

Refinamento de intenção | Snippets de código

Solicitação de API do Conversational Commerce: consulta de acompanhamento

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Resposta da API Conversational Commerce: consulta de acompanhamento

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

Ação

  1. Assim como na resposta inicial, atualize a interface da Web com as novas sugestões de conversationalTextResponse, refinedSearch e followupQuestion.
  2. Continue o fluxo da conversa, pedindo mais detalhes.

Inclusão de tags e análise de eventos

Quando o usuário continua a conversa:

  • Recuperar conversation_id. Verifique se o conversation_id do ConversationalSearchResponse anterior foi transmitido no ConversationalSearchRequest atual.
  • Adicionar tag aos eventos do usuário. Se a resposta da conversa levar a uma nova consulta de pesquisa, como quando um usuário clica em uma sugestão refined_search ou seu sistema faz uma chamada de pesquisa paralela, marque esse evento de usuário de pesquisa subsequente (UserEvent) com o mesmo conversation_id. Isso ajuda a acompanhar a jornada de conversa em vários turnos.

Transição para a filtragem conversacional de produtos

À medida que a conversa se torna mais específica, o sistema pode classificar a intenção como SIMPLE_PRODUCT_SEARCH e, se for adequado, acionar a filtragem de produtos por conversa.

Exemplo de entrada do usuário: Tema de princesa

Solicitação de API do Conversational Commerce: consulta de acompanhamento

{
  "query": "Princess theme",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Quando uma consulta é classificada como SIMPLE_PRODUCT_SEARCH, há duas respostas possíveis da API, dependendo se o filtro de produtos conversacional é acionado. A principal diferença está na presença e no conteúdo do campo conversationalFilteringResult.

Resultado 1: a filtragem é acionada

Isso acontece quando a consulta é essencial o suficiente para ser refinada ainda mais por atributos do produto. A resposta inclui conversationalFilteringResult, que sua interface da Web precisa priorizar.

Resposta da API Conversational Commerce: transição para a filtragem de produtos: 

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday decorations" }
  ],
  "conversationalFilteringResult": {
    "followupQuestion": "What specific type of princess decoration are you looking for?",
    "suggestedAnswers": [
      {
        "productAttributeValue": {
          "name": "attributes.type",
          "value": "Balloons"
        }
      },
      {
        "productAttributeValue": {
          "name": "attributes.type",
          "value": "Streamers"
        }
      },
      {
        "productAttributeValue": {
          "name": "attributes.type",
          "value": "Tablecloths"
        }
      }
    ]
  },
  "state": "SUCCEEDED"
}

Ação

A consulta foi classificada como SIMPLE_PRODUCT_SEARCH. Nesse caso, ela aciona a filtragem conversacional de produtos. No entanto, talvez ele não acione a filtragem conversacional de produtos.

  • Priorize a interface da Web de filtragem de produtos conversacional:quando conversationalFilteringResult é preenchido, isso indica que você entrou no modo de filtragem de produtos. Sua interface da Web precisa enfatizar o followupQuestion, que aparece na interface do usuário como algo parecido com Que tipo específico de decoração de princesa você está procurando?, e o suggestedAnswers, como botões clicáveis para Balões, serpentinas, toalhas de mesa.
  • Mostrar resultados de produtos: chame imediatamente a API AI Commerce Search usando o refined_search.query (decorações de aniversário de princesa) para mostrar os resultados iniciais de produtos junto com as opções de filtragem.
  • Prática recomendada de experiência do usuário: deve haver uma única barra de entrada de texto livre persistente para toda a experiência. Essa barra permanece ativa o tempo todo, inclusive durante um fluxo de filtragem de produtos de conversa. Quando o conversationalFilteringResult está ativo e você mostra respostas sugeridas como ícones clicáveis, os usuários têm duas opções claras:
    • Continue o fluxo de filtragem clicando em uma resposta sugerida.
    • Inicie uma nova conversa digitando uma nova consulta na barra de texto ativa. Essa nova entrada sempre aciona uma nova chamada para a API Conversational Commerce, encerrando o fluxo de filtragem atual.

Resultado 2: nenhum filtro é acionado

Se a consulta já for específica o suficiente ou não permitir mais filtragem, a resposta não vai incluir o campo conversationalFilteringResult. Nesse caso, faça uma pesquisa padrão.

Ação

  • Trate a interação como o fim do fluxo de conversa e use a consulta refined_search para chamar a API Retail Search e mostrar uma página padrão de resultados de produtos.

Inclusão de tags e análise de eventos

Quando a conversa passa para a filtragem de produtos:

  • Recuperar conversation_id. Continue usando o mesmo conversation_id.
  • Adicionar tag aos eventos do usuário. Se a transição levar a uma pesquisa imediata, marque essa UserEvent com o conversation_id. É importante lembrar que, quando o usuário interage com o suggestedAnswers, por exemplo, quando um usuário final clica em Balões, essa ação também deve acionar um UserEvent, como um evento filter ou um novo evento search, que é marcado com o mesmo conversation_id. Isso permite a atribuição de ações de filtragem no fluxo de conversa.

Continuar na filtragem conversacional de produtos

Quando o usuário selecionar um suggestedAnswer, envie um novo ConversationalSearchRequest.

Exemplo de entrada do usuário (clicar em uma resposta sugerida): Balões

Pesquisa simples de produtos | Snippets de código

Solicitação de API Conversational Commerce: continuar filtrando 

{
  "query": "Balloons", // The selected answer
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // Maintain conversation ID
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Resposta da API Conversational Commerce: continuar filtrando 

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday balloons" }
  ],
  "state": "SUCCEEDED"
}

Ação

A API responde com uma consulta SIMPLE_PRODUCT_SEARCH, mas sem o campo conversationalFilteringResult, indicando que o fluxo de filtragem guiada foi concluído.

  • Use a consulta final refinedSearch (balões de aniversário de princesa) para fazer uma chamada direta à API AI Commerce Search.
  • Mostrar os resultados finais do produto ao usuário. Nesse ponto, a conversa pode terminar ou o usuário pode inserir uma nova consulta para iniciar uma nova rodada.

Inclusão de tags e análise de eventos

Para cada etapa do processo de filtragem de produtos:

  • Recuperar conversation_id. Sempre use o mesmo conversation_id para todas as solicitações na sessão de filtragem.
  • Adicionar tag aos eventos do usuário. Cada interação do usuário com um suggestedAnswer, como um clique, deve acionar um UserEvent relevante, como um evento filter ou um novo evento search se uma nova consulta for formada. Esse UserEvent precisa ser marcado com o conversation_id para acompanhar com precisão a jornada de filtragem e o impacto dela na conversão.

Arquitetura de referência

Este é o design arquitetônico de referência da Pesquisa de e-commerce com IA em Google Cloud. Esta arquitetura de referência descreve o fluxo de dados e serviços para uma pesquisa conversacional. O diagrama mostra como os eventos do usuário, os dados do catálogo de produtos e os registros operacionais são processados, transformados e integrados a um índice de IA generativa e ao serviço do Adaptador do varejo para lidar com operações de pesquisa e atender às intenções do usuário para retornar resultados da pesquisa. A arquitetura conecta vários projetos para ativar uma funcionalidade abrangente de pesquisa de comércio com tecnologia de IA.

Arquitetura de referência da IA para e-commerce

Recursos de prévia: invocação do agente e Reasoning Engine

Esta prévia apresenta novos recursos para estender a pesquisa conversacional com fluxos de trabalho com agentes, usando o mecanismo de raciocínio da Vertex AI para gerenciamento de sessões e permitindo a integração com ferramentas externas.

Para ativar os recursos de pré-lançamento, consulte Inscrever-se.

Novos recursos

  • Integração do Reasoning Engine:usa sessões do mecanismo de pesquisa conversacional da Vertex AI para gerenciar sessões persistentes. Isso permite que a pesquisa conversacional mantenha o contexto em conversas de vários turnos usando a persistência de sessão do "Vertex AI Agent Engine".
  • Suporte a ferramentas do MCP:adiciona suporte para invocar ferramentas do Protocolo de Contexto de Modelo (MCP), permitindo que a pesquisa conversacional recupere informações de fontes externas e realize ações além dos recursos padrão de pesquisa no varejo.

Alterações na API

As mensagens ConversationalSearchRequest e ConversationalSearchResponse foram atualizadas para oferecer suporte a esses recursos: Campos de solicitação:

  • enableAgentInvocation (booleano): se definido como "true", o serviço vai ativar o fluxo de trabalho de invocação da pesquisa conversacional para a solicitação.
  • reasoningEngine (string): o nome do recurso do mecanismo de raciocínio (mecanismo de pesquisa conversacional) que hospeda as sessões de pesquisa conversacional, formatado como projects/*/locations/*/reasoningEngines/*.

Campos de resposta:

  • agentInvocations: contém detalhes da invocação da pesquisa conversacional, incluindo respostas das ferramentas do MCP.

Pré-requisitos

Antes de usar os novos recursos, verifique se você configurou os pré-requisitos.

Como configurar sessões persistentes

Para usar sessões permanentes com um mecanismo de raciocínio, configure seu projeto "Google Cloud" da seguinte maneira:

  1. Ative a API Vertex AI no seu projeto (mais detalhes).
  2. Conceda permissões do IAM:conceda à conta de serviço cloud-ml-consumeragent-server@system.gserviceaccount.com o papel de Usuário da Vertex AI no seu projeto.
  3. Crie um mecanismo de agente:você precisa criar uma instância do mecanismo de raciocínio para processar sessões. Você pode seguir os exemplos da documentação da Vertex AI ou usar o seguinte script Python, que a inicializa.
import vertexai

from vertexai.preview import reasoning_engines

PROJECT_ID = "your-project-id"
LOCATION = "us-central1"
DISPLAY_NAME = "Session-Engine"
vertexai.init(project=PROJECT_ID, location=LOCATION)
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
my_agent_engine_instance = client.agent_engines.create(
    config={
        "display_name": DISPLAY_NAME
    }
)

print(f"Successfully created Agent Engine: {my_agent_engine.resource_name}")

Configurar ferramentas do MCP

Você pode estender a pesquisa conversacional com sua pesquisa personalizada ao abrir seu próprio servidor MCP e compartilhar os seguintes detalhes com a gente:

  1. Endereço do servidor MCP.
  2. Método de autenticação do servidor MCP.
  3. Ferramenta responsável pela pesquisa.

Exemplo de uso da API

O exemplo a seguir demonstra como chamar a API de pesquisa conversacional com a invocação da pesquisa conversacional ativada. Se você configurou um mecanismo de raciocínio, inclua o nome do recurso para manter a sessão. 

{
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/default_catalog/branches/default_branch",
  "placement": "projects/{project_id}/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Help me plan a party",
  "visitorId": "your_visitor_id",
  "enableAgentInvocation": true,
  "reasoningEngine": "projects/{project_id}/locations/{location_id}/reasoningEngines/{reasoning_engine_id}"
}

SDKs de pré-lançamento particular

Acesse os SDKs particulares desses recursos aqui: link do Google Drive.

Se você não tiver acesso à pasta, solicite usando o Google Drive.

Inscreva-se

Use o formulário de acesso antecipado para se inscrever no recurso.

A seguir

Para mais recursos de suporte, consulte as respostas a perguntas sobre os recursos de conversa.