Guia para desenvolvedores de agentes de comércio 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 Conversational deixa claras as diferenças entre o agente de comércio conversacional e a filtragem de produtos conversacionais.

Configuração

A API Conversational é compatível com o recurso de agente de comércio 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 Retail 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 agente de comércio conversacional. Por exemplo, o usuário pode digitar Quero ajuda para planejar uma festa no campo de pesquisa.

Enviar uma solicitação para a Vertex AI para Pesquisa em E-commerce

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 da API Conversational

  • Crie uma solicitação de agente de comércio 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/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

Solicitação de API de conversa:

Consulta inicial

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/799252947591/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 (por exemplo, filter, canonicalFilter, sortBy, 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 estiver 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 do agente de comércio conversacional. Esse é o modo preferencial para este guia de implementação na pesquisa de agentes de comércio conversacional.

      • Exemplo de solicitação da 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 de agentes de comércio conversacional e a filtragem de produtos conversacionais.

      • Exemplo de solicitação da 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. Consulte o guia adicional sobre como integrar os dois produtos de conversa.

Endpoint 2: solicitação da API Core Search

Há duas abordagens principais para mostrar resultados da pesquisa na sua UI:

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

    Se o design da experiência do usuário determinar que os resultados da pesquisa devem ser sempre exibidos, 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 Product Search 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ê quiser mostrar resultados da pesquisa apenas 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 consultas à API Product Search 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 Retail. Para mais informações, consulte Etapa 2c. Entenda os tipos de consulta e as ações do varejista.

Método HTTP e endpoint

    POST https://retail.googleapis.com/v2beta/{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 Pesquisa varejo 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 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 da 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 Vertex AI para Pesquisa para Commerce

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 os tipos de consulta e as ações do varejista](#step-2c).
  • 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 é fundamental para distinguir várias conversas em andamento de um único comprador. O modelo retém o contexto para um determinado conversation_id. Enviar 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 será uma única consulta. Para outras consultas que buscam respostas de LLM, será uma 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 por IA à 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 UI, como mostrar um indicador de carregamento até SUCCEEDED. Confira mais detalhes na Etapa 2b. Entender a API de streaming

Entender a API de streaming

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

O primeiro trecho da resposta inclui as consultas query_types e refined_search, e o state é indicado como STREAMING. Essa detecção precoce de intenção e disponibilidade imediata de refinamentos de pesquisa permite 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ão no primeiro bloco, seu sistema sabe imediatamente que não vai receber uma resposta do LLM. Você pode continuar com o processamento predefinido para esses tipos, como exibir 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 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 está sendo gerado. Você pode escolher mostrar um indicador de carregamento para a resposta da conversa ou apresentar a resposta depois que ela for totalmente transmitida.

Entender os tipos de consultas e as ações dos varejistas

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. conversational_text_response se refere à resposta de linguagem natural gerada por IA da API.

O agente de comércio 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 Conversacional e de pesquisa 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 tudo bem com você?) 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 locais de lojas, horários de funcionamento, disponibilidade de estoque de produtos etc. (como Temos leite em estoque?).
  • RETAIL_SUPPORT: consultas relevantes para compras, formas de pagamento etc. (como 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 da 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 da 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 um acompanhamento 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 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 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 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 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 do 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 pode ser derivado do contexto do histórico de chat também. 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 estratégia de exibição de resultados da pesquisa e da UI.
    • Opções de experiência do usuário: a conversa não precisa terminar para consultas do SIMPLE_PRODUCT_SEARCH. O usuário pode continuar a conversa transmitindo o conversation_id em solicitações subsequentes.
      • Opção A: encerrar a interface de usuário conversacional: 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 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 Vertex AI para Pesquisa no comércio, é 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. Adicione tags aos eventos do usuário: quando a resposta da conversa leva a uma consulta de pesquisa, como se o sistema executa automaticamente uma pesquisa com base na consulta refinada para SIMPLE_PRODUCT_SEARCH, você precisa adicionar tags ao evento de usuário de pesquisa subsequente (UserEvent) com o mesmo conversation_id recebido no ConversationalSearchResponse.

Ao incluir tags corretamente em UserEvent.conversation_id, suas análises podem 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 do 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 vai fornecer os detalhes do produto solicitados. Seu sistema precisa mostrar essas informações de forma clara para o usuário.
    • A resposta também vai incluir refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para buscar resultados com a API Search principal.
  • PRODUCT_COMPARISON:
    • Ação: o conversational_text_response vai fornecer uma comparação dos produtos especificados. Seu sistema precisa mostrar essas informações de forma clara para o usuário.
    • A resposta vai incluir refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para buscar resultados com a API Search principal.
  • BEST_PRODUCT:
    • Ação: o conversational_text_response fornece recomendações ou informações sobre os "melhores" produtos com base na 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 com a API Search principal.

Categoria 5. Refinamento de intents

  • INTENT_REFINEMENT:
    • Ação: a resposta vai incluir 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 vai incluir refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para buscar resultados com a API Search principal.
    • Para interações subsequentes, envie a resposta do usuário com o conversation_id.

Mostrar consultas sugeridas para produtos

Veja como configurar a Pesquisa Google para mostrar perguntas e sugestões de produtos no agente de comércio conversacional.

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

Recomendação

  • Tela: apresente as N principais consultas (1 a 3, pendente de teste sobre o número ideal para sua UI) 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 da 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 Vertex AI para Pesquisa em E-commerce

É importante atribuir com precisão as consultas de pesquisa às interações de conversa e usar todos os recursos de análise na Vertex AI para Pesquisa para e-commerce 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. Adicione tags 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 em que o usuário final clica ou se o sistema executa automaticamente uma pesquisa com base na consulta refinada, adicione uma tag ao 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, suas análises podem 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.

Continuar a conversa

Nesta seção, descrevemos como as sessões do agente de comércio 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

  • Iniciar 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 assim 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 fornecer um botão explícito "Iniciar novo chat" ou "Reiniciar conversa", clicar nele vai acionar uma nova sessão de conversa.
    • Integração da API Conversational: a resposta da API vai incluir 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 o agente de comércio conversacional responda às consultas do usuário com base no histórico de conversas da sessão, abrangendo o usuário final query, o conversational_text_response e o followup_question.
    • Integração da API Conversacional: 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 forma idêntica ao SearchRequest usado para a pesquisa do produto principal.

Enviar uma solicitação para a Vertex AI para Pesquisa em E-commerce

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, você não vai redefinir o conversationId, mesmo que o usuário final digite uma consulta nova e aparentemente não relacionada. O sistema vai usar o histórico de conversas 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 tiver 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 pesquisa nova e 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/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

Solicitação de API de conversa:

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 continuidade da conversa:

  • 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 (por exemplo, mostrando que a consulta voltada ao usuário mudou de "decorações" para "decorações de festa de aniversário" ou "itens para 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 Vertex AI para Pesquisa em E-commerce

A inclusão de tags de eventos é importante para atribuir consultas de pesquisa a interações de conversação com precisão e usar os recursos de análise da Vertex AI para Pesquisa no 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. Adicione tags 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 de refined_search, ou se o sistema executa automaticamente uma pesquisa com base na consulta refinada, adicione uma tag ao evento de usuário de pesquisa subsequente (UserEvent) com o mesmo conversation_id recebido no ConversationalSearchResponse.

Ao incluir tags corretamente em 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 final e os caminhos de conversão.

Outras considerações e práticas recomendadas

Outras considerações e práticas recomendadas precisam ser consideradas ao implementar a interface do seu agente de comércio conversacional:

  • Consistência do ID do visitante: ajuda a garantir que um visitor_id exclusivo seja enviado de maneira consistente com cada solicitação de um determinado usuário final. Isso é vital para a personalização e treinamento de modelo precisos. O ideal é que esse identificador permaneça consistente para um usuário final em todas as sessões e estados de login ou logout.
  • Gerenciamento de ramificações: embora default_branch seja comum, use o ID de ramificação correto se o catálogo de produtos tiver várias ramificações.
  • Interação com a API Search: para SIMPLE_PRODUCT_SEARCH e qualquer caso em que refined_search seja fornecido, faça uma chamada separada para a API Search principal (SearchService.Search) usando o query do campo refined_search ou a consulta original para receber as informações do produto reais. A API Conversacional se concentra principalmente na experiência de conversa e na compreensão da intenção do usuário, em vez de retornar diretamente os resultados do produto.
  • Design da interface do usuário: crie uma interface que apresente claramente as opções conversational_text_response, followup_question e refined_search de maneira intuitiva para orientar o usuário.

A seguir

Para mais recursos de suporte, consulte as perguntas frequentes sobre recursos de conversa.