Guía para desarrolladores de agentes de comercio conversacional

En esta guía, se detalla cómo realizar la integración con la API de Conversational para proporcionar experiencias de chat dinámicas potenciadas por IA a tus clientes. Si comprendes los diferentes tipos de búsquedas y aprovechas las respuestas de la API, puedes ofrecer búsquedas de productos relevantes, responder las consultas de tus clientes y guiar a tus usuarios finales en su recorrido de compra.

El objeto conversationalFilteringMode en la API de Conversational deja en claro las diferencias entre el agente de comercio conversacional y el filtrado de productos conversacional.

Configuración

La API de Conversational admite la función de agente de Conversational Commerce:

• gRPC: conversationalSearchService
• REST: conversationalSearch

La API de Conversational permite una experiencia de chat en la que los usuarios envían consultas y el sistema devuelve una respuesta de texto, tipos de consultas clasificadas y posibles opciones de búsqueda refinadas.

Esta API funciona como un servicio de transmisión, lo que permite la detección anticipada de la intención de la búsqueda. Las interacciones posteriores en la conversación requieren adjuntar un conversation_id.

Para devolver resultados de la búsqueda, se debe llamar a la API de Retail heredada en paralelo con la API de Conversational.

Envía una consulta desde el usuario final

En esta sección, se describe cómo iniciar una experiencia de agente de comercio conversacional. Por ejemplo, el usuario podría ingresar Ayúdame a planificar una fiesta en el campo de búsqueda.

Envía una solicitud a Vertex AI Search for Commerce

Existen dos extremos de API diferentes:

1. Se debe usar la API de Conversación para recuperar la experiencia de conversación.
2. Se debe usar la API de Search principal para recuperar los resultados de la búsqueda.

Extremo 1: Solicitud a la API de Conversational

• Debes crear una solicitud de agente de comercio conversacional configurando la entrada del usuario como la consulta.
• La solicitud debe enviarse como una solicitud HTTP POST al extremo projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Método y extremo HTTP

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

Solicitud a la API conversacional:

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: Es el nombre del recurso de la posición (por ejemplo, projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Este es un parámetro de ruta de acceso y es obligatorio.
• query: Es la búsqueda sin procesar de tu usuario. Este campo es obligatorio.
• branch: Es el nombre del recurso de la rama, como projects/P/locations/L/catalogs/C/branches/B. Si no se establece, se usa default_branch. Este campo es obligatorio.
• visitorId: Es un identificador único para hacer un seguimiento de los visitantes. Este campo es obligatorio.
• conversationId: Es un ID único para hacer un seguimiento de las sesiones de conversación. Para la solicitud initial en una conversación nueva, este campo debe estar vacío. Para las solicitudes posteriores dentro de la misma conversación, se debe establecer en el conversation_id recibido en el ConversationalSearchResponse anterior.
• searchParams: (Opcional) Parámetros de búsqueda principales estándar (p.ej., filter, canonicalFilter, sortBy, boostSpec). Es fundamental que estos parámetros reflejen la configuración que se usa en las llamadas principales a la API de Search para garantizar la coherencia entre las respuestas del LLM y los resultados de la búsqueda de productos que se muestran.
• userInfo: (Opcional) Es la información del usuario para una personalización mejorada. Puede incluir userId, user_agent y direct_user_request (booleano).
• conversationalFilteringSpec: (Opcional) Especifica el modo de filtrado conversacional. Si no se configura, se establecerá de forma predeterminada como INHABILITADO.

  mode: Integra la API de Conversational con uno de estos tres modos para controlar el filtrado de productos conversacionales:

• DISABLED: En este modo, el cliente solo implementa la búsqueda de agentes de comercio conversacional. Este es el modo preferido para esta guía de implementación sobre la búsqueda de agentes de comercio conversacional.

Solicitud a la API de muestra

        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
        }
      

Ejemplo de respuesta de la API

        user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
      

• ENABLED: En este modo, el cliente implementa todas las capacidades conversacionales, lo que incluye la búsqueda de agentes de comercio conversacional y el filtrado de productos conversacional.

Solicitud a la API de muestra

        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
        }
      

Ejemplo de respuesta de la 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: Si se elige, el cliente solo implementa el filtrado de productos conversacional. Con este modo seleccionado, el usuario solo experimenta el filtrado conversacional de productos sin generar una respuesta de LLM, una clasificación de búsqueda ni búsquedas sugeridas.

Para obtener más información, consulta la guía para desarrolladores de filtros de productos conversacionales. Consulta la guía adicional sobre cómo integrar ambos productos conversacionales.

Extremo 2: Solicitud a la API de Core Search

Existen dos enfoques principales para mostrar los resultados de la búsqueda en tu IU:

• Opción 1: Mostrar siempre los resultados de la búsqueda

  Si el diseño de la experiencia del usuario indica que los resultados de la búsqueda siempre deben mostrarse independientemente del resultado conversacional, como en un área dedicada a los resultados de la búsqueda junto al chat, envía la búsqueda original del usuario a la API principal de Product Search con tu llamada a la API de Conversational. Esto ayuda a garantizar que las fichas de productos estén disponibles de inmediato.

• Opción 2: Mostrar resultados de la búsqueda basados en la respuesta conversacional

Si el diseño de la experiencia del usuario es más dinámico y solo deseas mostrar los resultados de la búsqueda según la respuesta de la API de Conversational, por ejemplo, solo para las búsquedas de SIMPLE_PRODUCT_SEARCH o cuando se proporcionan sugerencias de refined_search, espera la respuesta de la API de Conversational antes de enviar cualquier búsqueda a la API principal de Product Search. Si hay una respuesta, usa la búsqueda refined_search proporcionada para recuperar los resultados de productos.

Independientemente de la opción de interfaz de usuario que elijas, cuando necesites recuperar resultados de productos reales, puedes llamar a la API de Retail. Para obtener más información, consulta el paso 2c. Comprende los tipos de búsquedas y las acciones de los comercios.

Método y extremo HTTP

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

Solicitud a la API de Core 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 (obligatorio): Es el nombre del recurso de la configuración de publicación de la Búsqueda de Retail o de la posición heredada. Ejemplo: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
• query: Obligatorio. Es la búsqueda. Puede ser la entrada sin procesar del usuario, como Ayúdame a planificar una fiesta, o un refinedSearch.query más optimizado (como suministros para la planificación de fiestas, decoraciones) que se obtiene de la respuesta de la API de Conversational Commerce.
• visitorId: Obligatorio. Es un identificador único para hacer un seguimiento de los visitantes. Debe ser coherente con el objeto visitorId que se envía a la API de Conversational Commerce para el mismo usuario final.
• branch (obligatorio): Es el nombre del recurso de la rama, como projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
• pageSize (opcional): Es la cantidad máxima de productos que se mostrarán.
• filter (opcional): Se usa para filtrar los resultados de la búsqueda. Aquí es donde aplicarías los filtros que reflejan lo que envías en `searchParams` a la API de Conversational Commerce para garantizar la coherencia.
• orderBy (opcional): Especifica el orden en el que se muestran los productos (por ejemplo, por relevancia o por precio).
• userInfo (opcional): Es la información del usuario para la personalización, que debe ser coherente con la llamada a la API de Conversational Commerce.
• searchMode (opcional): Define el comportamiento de la búsqueda. PRODUCT_SEARCH se usa con frecuencia para las consultas generales sobre productos.

Comprende la respuesta

En este muestra de código, se muestra una respuesta de la API de Conversational Commerce.

La respuesta de la API (ConversationalSearchResponse) incluye query_types, conversational_text_response (si corresponde), opciones de refined_search y, posiblemente, un followup_question o un conversational_filtering_result. El conversation_id es fundamental para continuar la sesión.

Respuesta de Vertex AI Search for Commerce

En este muestra de código, se muestra una respuesta de la API de Conversational:

Respuesta 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"
    }
    

Qué deben hacer los minoristas con la respuesta (general)

Renderiza estos campos de la respuesta:

• user_query_types: Este campo proporciona las clasificaciones de la intención del usuario. Para obtener información detallada sobre las acciones basadas en estos tipos, consulta [Comprende los tipos de búsquedas y las acciones del comercio](#step-2c).
• conversation_id: Puedes almacenar este ID único en el almacenamiento de sesión de tu navegador o en un almacenamiento similar del cliente para mantener la sesión de conversación con el servidor. Esto es fundamental para distinguir entre varias conversaciones en curso de un solo comprador. Tu modelo conserva el contexto para un conversation_id determinado. Si envías un nuevo conversation_id, se iniciará una sesión nueva. Se recomienda definir la duración de la sesión, por ejemplo, 30 minutos de inactividad.
• refined_search: Es una lista de búsquedas refinadas propuestas que se usan para recuperar los resultados de la búsqueda pertinentes. En el caso de SIMPLE_PRODUCT_SEARCH, siempre será una sola búsqueda. Para otras búsquedas que buscan respuestas de LLM, será una o más. Las búsquedas de refined_search se pueden usar para llamadas a la API de Search principal (SearchService.Search) o también se pueden mostrar a tu usuario como sugerencias.
• conversational_text_response: Muestra este texto al usuario como la respuesta principal generada por IA a su búsqueda.
• followup_question: Opcional. Se muestra el followup_question.
• state: Este campo indica el estado de la generación de respuesta (STREAMING o SUCCEEDED). Puedes usarlo para proporcionar comentarios en la IU, como mostrar un indicador de carga hasta que se muestre SUCCEEDED. Encontrarás más detalles sobre este tema en el paso 2b. Información sobre la API de transmisión

Información sobre la API de transmisión

La API de Conversational Commerce funciona como una API de transmisión. Esto significa que tu usuario recibe partes de la respuesta en varios fragmentos en lugar de una sola carga útil completa.

El primer fragmento de la respuesta incluye las búsquedas de query_types y refined_search, y su state se indica como STREAMING. Esta detección temprana de la intención y la disponibilidad inmediata de los refinamientos de la búsqueda permiten que tu modelo tome decisiones rápidas sobre cómo controlar la búsqueda del usuario y cómo administrar su experiencia en relación con la latencia de las respuestas del LLM:

• Para los tipos de búsqueda que _no_ esperan una respuesta de texto conversacional (como SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT): Debido a que los query_types se encuentran en el primer fragmento, tu sistema sabe de inmediato que no se generará una respuesta de LLM. Puedes continuar con el manejo predefinido para estos tipos, como mostrar un mensaje estático o redireccionar al equipo de asistencia, sin esperar más resultados conversacionales.
• Específicamente para SIMPLE_PRODUCT_SEARCH, tu sistema puede realizar de inmediato una llamada directa a la API de Search principal con la búsqueda refined_search que se recibió en el primer fragmento. Esto ayuda a garantizar que los resultados de la búsqueda se muestren con una demora mínima, lo que cumple con los ANS típicos de la experiencia de búsqueda.
• Para los tipos de preguntas que sí esperan una respuesta de texto conversacional (como INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT)
• Recibirás las búsquedas query_types y refined_search en el fragmento inicial. Puedes iniciar de inmediato una llamada paralela a la API de Search principal con estas búsquedas de refined_search para comenzar a cargar los resultados de los productos.
• Luego, se transmiten fragmentos posteriores que contienen diferentes secciones de la respuesta de texto conversacional. Durante este tiempo, el state permanece "STREAMING".
• Por último, el último fragmento incluye la respuesta de texto conversacional completa y su state cambia a "COMPLETED".
• Este enfoque de transmisión permite una experiencia fluida para el usuario final, en la que los resultados de la búsqueda pueden comenzar a cargarse mientras se genera el resumen de IA. Puedes elegir mostrar un indicador de carga para la respuesta conversacional o presentar la respuesta conversacional después de que se transmita por completo.

Comprende los tipos de búsquedas y las acciones de los comercios

El campo query_types de la respuesta es una lista que indica las clasificaciones de la intención del usuario. Tu sistema debe controlar estos casos de la siguiente manera. Ten en cuenta que conversational_text_response hace referencia a la respuesta de lenguaje natural generada por IA de la API.

El agente de Conversational Commerce usa categorías de búsquedas para determinar si se genera una respuesta basada en LLM y cómo las APIs de Conversational y Search manejan las búsquedas de los usuarios finales en los siguientes casos:

Categorías	Clasificaciones de búsquedas
#1. Consultas irrelevantes que no requieren una respuesta de LLM	QUERY_TYPE_UNSPECIFIED: Tipo de consulta no especificado. RETAIL_IRRELEVANT: Son las búsquedas irrelevantes para el dominio de venta minorista, por ejemplo, una búsqueda adversarial (como cómo hacer una bomba),una búsqueda conversacional (como ¿cómo estás?) o una búsqueda de jailbreak (como escribe un poema). BLOCKLISTED: Son las búsquedas que los clientes de comercio electrónico bloquean de forma explícita (por ejemplo, ¿Cuáles son los efectos secundarios del Advil?).
#2. Consultas de asistencia e información	ORDER_SUPPORT: Consulta complementaria o de asistencia (como Hacer un seguimiento de mi pedido, estado del pedido 12345) DEALS_AND_COUPONS: Son las búsquedas relevantes para ofertas, promociones, ofertas de productos y descuentos (como ¿Hay ofertas para el Día de Acción de Gracias?). STORE_RELEVANT: Son las búsquedas relevantes para las ubicaciones de las tiendas, los horarios de atención, la disponibilidad de productos en stock, etcétera (por ejemplo, ¿Tenemos leche en stock?). RETAIL_SUPPORT: Son las búsquedas relevantes para compras, formas de pago, etcétera (por ejemplo, ¿Qué formas de pago aceptan?).
#3. Búsquedas de palabras clave que no requieren un LLM Solicitud a la API conversacional: 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" } Respuesta de la API de conversación: Respuesta inicial { "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"], "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9", "refinedSearch": [ { "query": "monster energy drinks" } ] } Solicitud a la API de búsqueda: Consulta de seguimiento { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "monster energy drinks", "visitorId": "test" }	SIMPLE_PRODUCT_SEARCH: Búsqueda básica de productos, como Vestido rojo o Mostrar algunas bebidas Monster.
#4. Preguntas que buscan respuestas de LLM Solicitud a la API conversacional: 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" } Respuesta de la API de conversación: Respuesta 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" } ] } Solicitud a la API de búsqueda: Consulta de seguimiento { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "1% milk", "visitorId": "test" }	PRODUCT_DETAILS: El usuario busca detalles y especificaciones del producto, como Muéstrame las especificaciones de [nombre del producto]. ¿Cuál es el contenido de proteínas de la leche al 2%? PRODUCT_COMPARISON: Comparación de productos, como compara [nombre del producto] y [nombre del producto], compara leche al 1% con leche al 2%). BEST_PRODUCT: Son las búsquedas con el patrón más coincidente, como ¿Cuál es la galleta más saludable? ¿Qué marca de leche es la mejor?).
5. Refinamiento del intent Solicitud a la API conversacional: 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" } Respuesta de la API de conversación: Respuesta 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: El tipo no está claro y es posible que se necesite una conversación de seguimiento o una definición más precisa para aclarar el tipo, como Ayúdame a planificar una fiesta. Esta suele ser la intención más popular en las conversaciones.

Categoría 1 Consultas irrelevantes que no requieren una respuesta del LLM

• QUERY_TYPE_UNSPECIFIED:
• No se proporciona ningún conversational_text_response.
• Acción: Controla como caso predeterminado o de error. Puedes pedirle al usuario que aclare su duda o dirigirlo a donde puede recibir ayuda general.
• RETAIL_IRRELEVANT:
• No se proporciona ningún conversational_text_response.
• Acción: Para controlar esto, muestra un mensaje adecuado, como No puedo responder esa pregunta o Soy un asistente de compras. ¿En qué puedo ayudarte?, según lo defina el diseño de tu aplicación.
• BLOCKLISTED:
• No se proporciona ningún conversational_text_response.
• Acción: Controla la solicitud según tu política de lista de bloqueo. Por lo general, se muestra un mensaje genérico que indica que no se puede completar la solicitud.

Categoría 2. Consultas de asistencia e información

En el caso de estos tipos, la API no proporciona un conversational_text_response directo de forma predeterminada, pero tienes opciones para dirigir a los vínculos o recursos correctos.

• ORDER_SUPPORT:
• Acción predeterminada: No se proporciona ningún conversational_text_response. Tu IU debe mostrar algún mensaje estándar, vínculos relevantes o redireccionar la búsqueda a tu propia API de asistencia dedicada o canal de atención al cliente.
• DEALS_AND_COUPONS:
• Acción predeterminada: No se proporciona ningún conversational_text_response. Tu IU debe mostrar algún mensaje estándar, vínculos relevantes o redireccionar la búsqueda a tu sistema de ofertas o promociones.
• STORE_RELEVANT:
• Acción predeterminada: No se proporciona ningún conversational_text_response. Tu IU debe mostrar algún mensaje estándar, vínculos relevantes o redireccionar la búsqueda a tu propio localizador de tiendas o sistema de información.
• RETAIL_SUPPORT:
• Acción predeterminada: No se proporciona ningún conversational_text_response. Tu IU debe mostrar algún mensaje estándar, vínculos relevantes o redireccionar la búsqueda a tu propio sistema de preguntas frecuentes y de información.

Categoría 3. Búsquedas por palabras clave que no requieren respuestas de LLM

• SIMPLE_PRODUCT_SEARCH:
• No se genera ninguna respuesta de texto conversacional.
• Acción: La respuesta de la API siempre devuelve una sola búsqueda de refined_search. Esta consulta refinada actúa como un término de búsqueda sugerido. Realiza una llamada directa a la API de Search principal (SearchService.Search) y recupera los resultados de productos relevantes con la consulta original o la consulta refined_search. La refined_search.query puede no provenir directamente de la entrada del usuario final actual, sino que también puede derivarse del contexto del historial de chat, por ejemplo, si un usuario final refinó previamente vestido de fiesta a vestidos rojos, la búsqueda refinada podría convertirse en vestido rojo de fiesta.
• Para interfaces de conversación (como chatbots): Se recomienda mucho usar el objeto refined_search.query que proporciona la API. En un flujo de conversación, la API optimiza automáticamente las búsquedas en lenguaje natural, como "¿puedes ayudarme a encontrar bananas?", y las convierte en un término de búsqueda de productos preciso ("bananas"), lo que genera resultados de productos más relevantes.
• Para las experiencias de búsqueda principales (como la página de resultados de la búsqueda): Tienes la flexibilidad de usar el refined_search.query de la API o la búsqueda original proporcionada por el usuario final, ya que es más probable que la búsqueda original ya sea un término de búsqueda de productos preciso. Elige la opción que mejor se adapte a tu estrategia de visualización de la IU y los resultados de la búsqueda.
• Opciones de experiencia del usuario: La conversación no necesita finalizar para las búsquedas de SIMPLE_PRODUCT_SEARCH. Tu usuario puede continuar la conversación pasando el conversation_id en solicitudes posteriores.
• Opción A: Finalizar la IU conversacional: Muchos minoristas optan por dirigir al usuario a una página de resultados de búsqueda estándar una vez que se detecta un SIMPLE_PRODUCT_SEARCH, lo que cierra la ventana de chat. En esta situación, si el usuario final ingresa una nueva búsqueda en el cuadro de búsqueda estándar sin el conversation_id anterior, se trata como una conversación nueva y separada, y se emite un nuevo conversation_id.
• Opción B: Continuar con la IU conversacional: Los comercios pueden optar por mantener abierta la ventana de chat. Esto permite que el usuario vuelva a un modo conversacional. La decisión de implementar la opción A o B depende por completo de la experiencia del usuario que prefiera el comercio.

Para atribuir con precisión las búsquedas a las interacciones conversacionales y usar todas las capacidades de análisis en Vertex AI Search para el comercio, es fundamental etiquetar los eventos de forma adecuada:

1. Recupera conversation_id: Cuando realizas una llamada a la API de conversationalSearch, se devuelve ConversationalSearchResponse.conversation_id.
2. Etiqueta eventos del usuario: En los casos en que la respuesta conversacional genere una búsqueda, por ejemplo, si tu sistema ejecuta automáticamente una búsqueda basada en la búsqueda refinada de SIMPLE_PRODUCT_SEARCH, debes etiquetar ese evento del usuario de búsqueda posterior (UserEvent) con el mismo conversation_id que se recibió en ConversationalSearchResponse.

Si etiquetas correctamente UserEvent.conversation_id, tus estadísticas podrán atribuir con precisión las búsquedas a las interacciones conversacionales anteriores, lo que te proporcionará estadísticas valiosas sobre el comportamiento de los usuarios y las rutas de conversión.

Categoría 4. Preguntas que buscan respuestas de LLM

Para estos tipos de búsquedas, la API genera una conversational_text_response (respuesta de LLM) y también puede proporcionar una o más búsquedas refined_search. La conversación no finaliza y el usuario final puede continuarla.

• PRODUCT_DETAILS:
• Acción: conversational_text_response proporcionará los detalles del producto solicitados. Tu sistema debe mostrar esta información claramente al usuario.
• La respuesta también incluirá refined_search (una o más sugerencias de búsquedas, ordenadas y clasificadas) que se deben usar para recuperar los resultados de la búsqueda con la API principal de Search.
• PRODUCT_COMPARISON:
• Acción: conversational_text_response proporcionará una comparación de los productos especificados. Tu sistema debe mostrar esta información claramente al usuario.
• La respuesta incluirá refined_search (una o más búsquedas sugeridas, ordenadas y clasificadas) que se deben usar para recuperar los resultados de la búsqueda con la API principal de Search.
• BEST_PRODUCT:
• Acción: conversational_text_response proporciona recomendaciones o información sobre los productos "mejores" según la búsqueda. El sistema debería mostrar esta información.
• La respuesta incluye refined_search (una o más sugerencias de búsquedas, ordenadas y clasificadas) que se deben usar para recuperar los resultados de la búsqueda con la API principal de Search.

Categoría 5. Perfeccionamiento del intent

• INTENT_REFINEMENT:
• Acción: La respuesta incluirá conversational_text_response, un followup_question y refined_search (una o más sugerencias de búsquedas). El orden de visualización recomendado es el siguiente:
1. conversational_text_response
2. Sugerencias de refined_search: Se ordenan y clasifican, por lo que es importante mostrarlas en el mismo orden que la respuesta.
3. Followup_question
• La respuesta incluirá refined_search (una o más búsquedas sugeridas, ordenadas y clasificadas) que se deben usar para recuperar los resultados de la búsqueda con la API principal de Search.
• Para las interacciones posteriores, envía la respuesta del usuario junto con el conversation_id.

Mostrar sugerencias de búsquedas para productos

Así es como se configura la Búsqueda de Google para mostrar preguntas y sugerencias de productos en el agente de comercio conversacional.

Cuando la API de Conversational devuelve búsquedas de refinedSearch, estas representan excelentes oportunidades para guiar al usuario final hacia productos relevantes. Esto es especialmente valioso para la categoría 4 (búsquedas de respuestas de LLM) y la categoría 5 (INTENT_REFINEMENT).

Recomendación

• Mostrar: Presenta las principales búsquedas de N (de 1 a 3, según las pruebas sobre la cantidad ideal para tu IU) refinedSearch a tu usuario.
• Mecanismo: Estas búsquedas sugeridas deben ejecutarse a través de la API de Search principal (SearchService.Search) en segundo plano o cuando el usuario interactúa con ellas.
• Presentación: Muestra los resultados como carruseles interactivos o tarjetas en las que se puede hacer clic, lo que permite que el usuario navegue por categorías de productos relacionadas o elementos específicos. Esto proporciona valor inmediato y ayuda a cerrar la brecha entre la interacción conversacional y el descubrimiento de productos.

Solicitud a la API de búsqueda:

Consulta de seguimiento

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

Eventos que se envían a Vertex AI Search for Commerce

Es importante atribuir con precisión las búsquedas a las interacciones conversacionales y usar todas las capacidades de análisis en Vertex AI Search for Commerce con el etiquetado de eventos adecuado:

1. Recupera conversation_id: Cuando realizas una llamada a la API de conversationalSearch, se devuelve ConversationalSearchResponse.conversation_id.
2. Etiqueta los eventos del usuario: En los casos en que la respuesta conversacional genere una búsqueda, por ejemplo, cuando se muestra una sugerencia de refined_search en la que el usuario final hace clic o si tu sistema ejecuta automáticamente una búsqueda basada en la búsqueda refinada, debes etiquetar ese evento del usuario de búsqueda posterior (UserEvent) con el mismo conversation_id que se recibió en el ConversationalSearchResponse.

Si etiquetas correctamente UserEvent.conversation_id, tus estadísticas podrán atribuir con precisión las búsquedas a las interacciones conversacionales anteriores, lo que te proporcionará estadísticas valiosas sobre el comportamiento del usuario y las rutas de conversión.

Continúa la conversación

En esta sección, se describe cómo la API de Conversational mantiene las sesiones del agente de comercio conversacional y cómo estas continúan en este paso final.

La API de Conversational usa un conversation_id para administrar las conversaciones en curso. Para garantizar la coherencia entre las respuestas del LLM y los resultados de la búsqueda, las solicitudes Conversational API posteriores deben incluir SearchParams que reflejen la configuración de las llamadas principales a la API de Search.

Ver tabla

Control de sesiones	Descripción	Integración de la API de Conversational
Iniciar una nueva conversación	Para iniciar una conversación nueva, el cliente omite el campo conversation_id de la solicitud a la API.	Solicitud a la API de muestra 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" Ejemplo de respuesta de la 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" }
Continúa la conversación	La API de Conversational devuelve un conversation_id como parte de la respuesta de la API. Este ID se puede enviar en las solicitudes de seguimiento para continuar la misma conversación. Esto ayuda a garantizar que el agente de Conversational Commerce responda a las preguntas del usuario en función del historial de conversaciones de esa sesión.	Solicitud a la API de muestra 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" Ejemplo de respuesta de la 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" }
Cómo garantizar la coherencia de los resultados de la búsqueda	Para garantizar que las respuestas del LLM sean coherentes con los resultados de la búsqueda que se muestran, el cliente debe usar SearchParams en la solicitud de la API de Conversational. Estos parámetros de búsqueda deben tener la misma configuración que la API de Search principal.	Solicitud a la API de muestra 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" } } }

Control de sesiones

• Sigue estos pasos para iniciar una conversación nueva:
  • Descripción: Para comenzar una conversación nueva, el cliente omite el conversationId de la solicitud a la API.
  • Cuándo iniciar una conversación nueva: Un cliente querrá iniciar una conversación nueva (y, así, obtener un conversationId nuevo de la respuesta de la API) en varios casos comunes de experiencia del usuario:
    • Pestaña o sesión nuevas: Cuando un cliente abre tu sitio en una pestaña del navegador nueva o inicia una sesión completamente nueva
    • Nueva búsqueda original: En algunos diseños de UX, si un cliente ingresa una búsqueda nueva no relacionada, puedes optar por reiniciar el flujo de conversación para garantizar el contexto más pertinente.
    • Botón para reiniciar la conversación: Si tu IU proporciona un botón explícito para "Iniciar un chat nuevo" o "Restablecer conversación", hacer clic en él activaría una nueva sesión de conversación.
  • Integración de la API de Conversational: La respuesta de la API incluirá un nuevo conversationId que se usará para las solicitudes posteriores.
• Continúa la conversación:
  • Descripción: Conversational API devuelve un conversation_id como parte de la respuesta de la API. Este ID se debe enviar en las solicitudes de seguimiento para continuar con la misma conversación. Esto ayuda a garantizar que el agente de Conversational Commerce responda a las preguntas del usuario en función del historial de conversaciones de esa sesión, lo que abarca el query, el conversational_text_response y el followup_question del usuario final.
  • Integración de la API conversacional: El cliente pasa el conversation_id de la respuesta anterior en el ConversationalSearchRequest.
• Asegúrate de que los resultados de la búsqueda sean coherentes:
  • Descripción: Para garantizar que las respuestas del LLM sean coherentes con los resultados de la búsqueda que se muestran al usuario, el cliente debe usar searchParams en la solicitud de Conversational API. Estos parámetros de búsqueda deben tener la misma configuración (por ejemplo, filtros y orden de clasificación) que las llamadas a Search API que se realizan para recuperar los resultados de los productos.
  • Integración de la API de Conversational: El objeto searchParams dentro de ConversationalSearchRequest debe completarse de forma idéntica al objeto SearchRequest que se usa para la búsqueda de productos principal.

Envía una solicitud a Vertex AI Search for Commerce

Puedes recuperar el conversation_id del almacenamiento de sesión. La solicitud debe incluir el nuevo query del cliente, que podría ser una respuesta a la pregunta de la respuesta anterior. La solicitud también debe incluir el refined_search.query más reciente de la respuesta anterior si el usuario final está actuando en función de una búsqueda refinada. De lo contrario, debe incluir una búsqueda completamente nueva y no relacionada, y el conversationId. Recuerda incluir siempre searchParams coherentes.

Nota: Si se mantiene o restablece el conversationId para una nueva búsqueda del usuario final, depende de tus elecciones específicas de UX y de la experiencia del usuario seleccionada. El objeto conversationId actúa como la memoria del sistema para una sesión de conversación determinada.

• Situación 1: Barra de búsqueda única y conversación persistente: Si tu interfaz de búsqueda tiene solo una barra de búsqueda principal o una ventana de conversación persistente, no restablecerás el conversationId, incluso si el usuario final escribe una búsqueda nueva que parece no estar relacionada. El sistema usará el historial de conversación existente (vinculado a conversationId) para proporcionar respuestas pertinentes según el contexto.
• Situación 2: Ventana de conversación y ventana de búsqueda separadas: Si tu interfaz de búsqueda incluye una ventana de chat conversacional distinta y una barra de búsqueda estándar independiente (como un cuadro de búsqueda en todo el sitio), ingresar una nueva búsqueda en la barra de búsqueda estándar podría indicar de forma implícita la intención de iniciar una búsqueda nueva no relacionada, lo que podría provocar que se restablezca el conversationId para esa acción de búsqueda específica. Sin embargo, dentro de la ventana de conversación dedicada, siempre se debe mantener el conversationId para garantizar la continuidad.

En última instancia, la decisión de cuándo reutilizar o restablecer el conversationId es una elección de diseño para optimizar la experiencia conversacional de tus clientes.

Método y extremo HTTP (igual que la búsqueda inicial)

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

Solicitud a la API conversacional:

Consulta de seguimiento

{
  "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\")"
  }
}
  

Respuesta de la API de conversación:

Respuesta de seguimiento

{
  "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"
}
  

Ejemplos de un usuario final que sigue recibiendo preguntas:

• Pregunta del usuario: Ayúdame a planificar una fiesta
• Respuesta del sistema: ¿Qué tipo de fiesta estás planeando?
• Respuesta del usuario: Una fiesta de cumpleaños

Qué deben hacer los minoristas con la respuesta

La forma de renderizar los campos es similar a la respuesta inicial, pero ten en cuenta los cambios que reflejan la conversación continua:

• refined_search: Este campo contiene las búsquedas actualizadas que incorporan la entrada más reciente del usuario final. Debes actualizar la consola del cliente para que coincida con la búsqueda actual (por ejemplo, mostrar que la búsqueda visible para el usuario cambió de "decoraciones" a "decoraciones para fiesta de cumpleaños" o "artículos para fiesta de cumpleaños"). Las búsquedas refinadas se pueden usar para llamadas a la API de Search principal (SearchService.Search) o también se pueden mostrar al usuario final como sugerencias.
• conversational_text_response: Muestra la nueva respuesta de texto generada por IA que es pertinente para el turno más reciente.
• followup_question: Si la conversación debe continuar para una mayor definición, se proporcionará un nuevo followup_question.

Eventos que se envían a Vertex AI Search for Commerce

El etiquetado de eventos es importante para atribuir con precisión las búsquedas a las interacciones conversacionales y para usar las capacidades de Analytics en Vertex AI Search for Commerce.

El proceso de etiquetado de eventos consta de dos pasos:

1. Recupera conversation_id: Cuando realizas una llamada a la API de conversationalSearch, se devuelve ConversationalSearchResponse.conversation_id.
2. Etiqueta los eventos del usuario: En los casos en que la respuesta conversacional genere una búsqueda, por ejemplo, cuando se muestra una sugerencia de refined_search, o si tu sistema ejecuta automáticamente una búsqueda basada en la búsqueda refinada, debes etiquetar ese evento del usuario de búsqueda posterior (UserEvent) con el mismo conversation_id que se recibió en el ConversationalSearchResponse.

Si etiquetas UserEvent.conversation_id correctamente, tus estadísticas podrán atribuir con precisión las búsquedas a las interacciones conversacionales anteriores, lo que proporcionará estadísticas valiosas sobre el comportamiento del usuario final y las rutas de conversión.

Consideraciones y prácticas recomendadas adicionales

Cuando implementes la interfaz de tu agente de comercio conversacional, debes tener en cuenta las siguientes consideraciones y prácticas recomendadas adicionales:

• Coherencia del ID de visitante: Ayuda a garantizar que se envíe un visitor_id único de forma coherente con cada solicitud para un usuario final determinado. Esto es fundamental para la personalización precisa y el entrenamiento de modelos. Lo ideal es que este identificador siga siendo coherente para un usuario final en todas las sesiones y los estados de acceso o cierre de sesión.
• Administración de ramas: Si bien default_branch es común, asegúrate de usar el ID de rama correcto si tu catálogo de productos está estructurado con varias ramas.
• Interacción con la API de búsqueda: Para SIMPLE_PRODUCT_SEARCH y cualquier caso en el que se proporcione refined_search, recuerda hacer una llamada independiente a la API de búsqueda principal (SearchService.Search) con el query del campo refined_search o la búsqueda original para obtener las fichas de productos reales. La API de Conversational se enfoca principalmente en la experiencia conversacional y la comprensión de la intención del usuario, en lugar de mostrar directamente resultados de productos.
• Diseño de la interfaz de usuario: Diseña tu IU para presentar claramente las opciones conversational_text_response, followup_question y refined_search de manera intuitiva para guiar al usuario.

¿Qué sigue?

Para obtener más recursos de asistencia, consulta las Preguntas frecuentes sobre las funciones de conversación.