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:

• gRPC: conversationalSearchService
• REST: conversationalSearch

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 principais padrão da Pesquisa, 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 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 pesquisa do agente de comércio conversacional e filtragem de produtos por conversa.

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

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.

Endpoint 2: solicitação da 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 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 os 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 Entender 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.
• 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 entre 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 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 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 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 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 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 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á no primeiro bloco, seu sistema sabe imediatamente que nenhuma resposta de LLM será enviada. 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 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 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 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 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, incluindo horário de funcionamento 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 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 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 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 extraia 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 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 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 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 com 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 conversacionais 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. 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 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 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 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 Conversational 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

• 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 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 no comércio com 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 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, 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

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.

Visualizar tabela

Processamento de sessões	Descrição	Integração da API de conversa
Iniciar uma conversa	Para iniciar uma nova conversa, o cliente omite o conversation_id da solicitação de API.	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: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" Exemplo de resposta da API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
Continuar a conversa	A API Conversational retorna um conversation_id como parte da resposta da API. Esse ID pode ser enviado nas 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.	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" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" Exemplo de resposta da API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
Como garantir a consistência dos resultados da pesquisa	Para garantir que as respostas do LLM sejam consistentes com os resultados da pesquisa mostrados, o cliente precisa usar SearchParams na solicitação da API Conversational. Esses parâmetros de pesquisa precisam ter a mesma configuração da API Search principal.	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" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" search_params { filter: "filter" canonical_filter: "canonical_filter" sort_by: "sort_by" boost_spec { condition_boost_specs { condition: "condition" } } }

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 da Web tiver um botão explícito Iniciar novo chat 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 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 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 forma idêntica ao SearchRequest usado para a pesquisa de produtos principais.

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.

Observação: se o conversationId é mantido ou redefinido para uma nova consulta do usuário final depende das suas escolhas específicas de UX e da experiência do usuário selecionada. O conversationId funciona como a memória do sistema para uma determinada sessão de conversa.

• 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 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 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/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 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 Vertex AI para Pesquisa em E-commerce

A inclusão de tag de evento é 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. 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 de 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 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 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 Conversational e a filtragem de produtos conversacionais para oferecer uma experiência de compras 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 o agente de comércio conversacional e a filtragem conversacional de produtos estão ativados, o sistema aproveita os pontos fortes de cada um. O agente de comércio conversacional lida com consultas gerais, fornece respostas geradas com IA e refina as intenções iniciais. Já a filtragem conversacional de produtos orienta os usuários nas seleções de atributos específicos usando um modelo de interação simplificado baseado 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 comando do usuário: Me ajude a planejar uma festa

Para ativar o agente de comércio conversacional e a filtragem conversacional de produtos, verifique se o ConversationalSearchRequest inclui esta configuração:

Solicitação da 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: definir esse campo como ENABLED no seu conversationalFilteringSpec 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 for 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 opção followupQuestion: Que tipo de festa você está planejando?
4. Permitir a entrada livre do usuário para avançar na 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 da API 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 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 de 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ção 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 conversacional.

Exemplo de comando do usuário: Tema de princesa

Solicitação da API 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"
  }
}

Possíveis resultados para a pesquisa de produtos principais

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 deve 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": [
      { "answer": "Balloons", "query": "princess birthday balloons" },
      { "answer": "Streamers", "query": "princess birthday streamers" },
      { "answer": "Tablecloths", "query": "princess birthday tablecloths" }
    ]
  },
  "state": "SUCCEEDED"
}

Ação

A consulta agora foi classificada como SIMPLE_PRODUCT_SEARCH. Nesse caso, ela aciona a filtragem conversacional de produtos. No entanto, pode ser que 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 do tipo 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 Retail Search usando 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 em todos os momentos, inclusive durante um fluxo de filtragem conversacional de produtos. 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.

Observação:essa escolha de design está alinhada ao princípio fundamental de que a entrada de texto livre é processada pela API Conversational Commerce, enquanto os cliques em respostas sugeridas são processados pela filtragem de produtos conversacionais.

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 da 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 Retail Search.
• Mostrar os resultados do produto final 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.

Recomendações de interface do usuário e opções de design

A interação entre o agente de comércio conversacional e a filtragem conversacional de produtos oferece muita flexibilidade. Confira algumas considerações importantes de UX para criar uma experiência tranquila e intuitiva:

• Barra de entrada única: deve haver apenas uma barra de entrada de texto livre para toda a experiência. Não há uma barra de entrada separada e dedicada para a filtragem conversacional de produtos. Isso simplifica a interface do usuário e mantém a interação consistente.
• Transições perfeitas: crie sua interface da Web para que as transições entre respostas de conversação, consultas sugeridas e opções de filtragem pareçam naturais e intuitivas.
• Orientação clara: use pistas visuais, como estilos de botões distintos para respostas sugeridas em vez de entrada geral, e instruções claras para orientar o usuário sobre como interagir em cada etapa.
• Equilibrar o controle: o usuário precisa sempre sentir que está no controle da direção da conversa.
• Filtragem x formato livre: a barra de entrada de texto livre única permanece ativa o tempo todo. Assim, o usuário tem uma escolha constante: clicar em uma resposta sugerida para continuar refinando a pesquisa ou digitar uma nova consulta na barra de texto para iniciar uma nova conversa. Esse design garante que, mesmo durante um fluxo de filtragem, o usuário possa mudar para um assunto diferente se as necessidades dele mudarem.
• Opção de redefinição: ofereça uma opção clara de Iniciar nova conversa ou Redefinir filtros para permitir que os usuários reiniciem o processo de pesquisa ou filtragem.
• Persistência visual: mesmo ao fazer a transição para a filtragem de produtos, manter o histórico da conversa na janela de chat, como mostrar perguntas e respostas anteriores, pode melhorar o contexto e a experiência do usuário.

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 precisa e treinamento de modelo. 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 reais dos produtos. 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 resultados de produtos diretamente.
• Design da interface do usuário: crie sua interface da Web para apresentar claramente as opções conversational_text_response, followup_question e refined_search de maneira intuitiva e orientar o usuário.

A seguir

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