Guía para desarrolladores de agentes de comercio conversacional

En esta guía se explica cómo integrar la API Conversational para ofrecer a tus clientes experiencias de chat dinámicas basadas en IA. Si conoces los distintos tipos de consultas y aprovechas las respuestas de la API, puedes ofrecer búsquedas de productos relevantes, responder a las preguntas de tus clientes y guiar a tus usuarios finales en su recorrido de compra.

El conversationalFilteringMode de la API Conversational muestra claramente las diferencias entre el agente conversacional de comercio y el filtrado conversacional de productos.

Configuración

La API Conversational admite la función de agente conversacional de comercio:

• gRPC conversationalSearchService
• REST: conversationalSearch

La API Conversacional permite ofrecer 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 streaming, lo que permite detectar la intención de la consulta con antelación. Para las interacciones posteriores en la conversación, es necesario adjuntar un conversation_id.

Para devolver resultados de búsqueda, la API Retail antigua debe llamarse en paralelo a la API Conversational.

Enviar una consulta desde el usuario final

En esta sección se describe cómo iniciar una experiencia con un agente conversacional de comercio. Por ejemplo, un usuario puede introducir Ayúdame a organizar una fiesta en el campo de búsqueda.

Enviar una solicitud a Vertex AI Search para el sector del comercio

Hay dos endpoints de API diferentes:

1. Para obtener la experiencia conversacional, debe usarse la API Conversational.
2. La API Search principal debe usarse para obtener resultados de búsqueda.

Endpoint 1: solicitud a la API Conversational

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

Método HTTP y endpoint

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

Solicitud a la API Conversation:

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: nombre del recurso de la colocación (por ejemplo, projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Se trata de un parámetro de ruta obligatorio.
• query: la consulta de búsqueda sin procesar del usuario. Este campo es obligatorio.
• branch: 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: identificador único para monitorizar a los visitantes. Este campo es obligatorio.
• conversationId: ID único para monitorizar las sesiones de conversación. En la solicitud inicial de una conversación nueva, este campo debe estar vacío. En las solicitudes posteriores de la misma conversación, debe asignarse el valor conversation_id recibido en la ConversationalSearchResponse anterior.
• searchParams: (opcional) Parámetros de búsqueda principales estándar, como filter, canonicalFilter, sortBy y boostSpec. Es fundamental que estos parámetros reflejen la configuración utilizada en las llamadas a la API de búsqueda principal para garantizar la coherencia entre las respuestas del LLM y los resultados de búsqueda de productos que se muestren.
• userInfo: (opcional) información del usuario para mejorar la personalización. Puede incluir userId, user_agent y direct_user_request (booleano).
• conversationalFilteringSpec: (Opcional) Especifica el modo de filtrado conversacional. Si no se define, el valor predeterminado es DISABLED.

  mode: integra la API Conversational usando uno de estos tres modos para controlar el filtrado de productos conversacional:

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

Solicitud de ejemplo a la 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
        }
      

Respuesta de ejemplo 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 funciones conversacionales, como la búsqueda de agentes conversacionales de comercio y el filtrado conversacional de productos.

Consulta la guía adicional sobre cómo integrar ambos productos conversacionales.

Solicitud de ejemplo a la 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
        }
      

Respuesta de ejemplo 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 esta opción, el cliente solo implementará el filtrado de productos conversacional. Si se selecciona este modo, el usuario solo podrá filtrar los productos de forma conversacional, sin generar una respuesta de LLM, una clasificación de consulta ni consultas de búsqueda sugeridas.

Consulta la guía para desarrolladores de filtros de productos conversacionales para obtener más información.

Endpoint 2: solicitud a la API Core Search

Hay dos enfoques principales para mostrar los resultados de búsqueda en tu interfaz web.

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

Si el diseño de la experiencia de usuario indica que los resultados de búsqueda deben mostrarse siempre, independientemente de la respuesta de la conversación (por ejemplo, en un área de resultados de búsqueda específica junto al chat), envía la consulta original del usuario a la API principal Product Search con tu llamada a la API Conversational. De esta forma, las fichas de producto están disponibles de inmediato.

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

Si el diseño de la experiencia de usuario es más dinámico y solo quieres mostrar resultados de búsqueda en función de la respuesta de la API Conversational, por ejemplo, solo para las consultas de SIMPLE_PRODUCT_SEARCH o cuando se proporcionen sugerencias de refined_search, espera a que la API Conversational responda antes de enviar cualquier consulta a la API principal Product Search. Si hay una respuesta, usa la consulta refined_search proporcionada para obtener los resultados del producto.

Independientemente de la opción de interfaz de usuario que elijas, cuando necesites obtener resultados de productos reales, puedes llamar a la API Retail. Para obtener más información, consulte Tipos de consultas y acciones de los comerciantes.

Método HTTP y endpoint

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

Solicitud a la API de búsqueda del producto principal:

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): nombre del recurso de la configuración de servicio de búsqueda para minoristas o del emplazamiento antiguo. Ejemplo: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
• query: obligatorio. La consulta de búsqueda. Puede ser la entrada sin procesar del usuario, como Ayúdame a organizar una fiesta, o una refinedSearch.query más optimizada (como suministros y decoración para fiestas) obtenida de la respuesta de la API Conversational Commerce.
• visitorId: obligatorio. Identificador único para hacer un seguimiento de los visitantes. Debe ser coherente con el visitorId enviado a la API Conversational Commerce del mismo usuario final.
• branch (obligatorio): nombre del recurso de la rama, como projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
• pageSize (Opcional): número máximo de productos que se pueden devolver.
• filter (Opcional): se usa para filtrar los resultados de búsqueda. Aquí es donde aplicarías los filtros que reflejen lo que envías en `searchParams` a la API Conversational Commerce para mantener la coherencia.
• orderBy (Opcional): especifica el orden en el que se devuelven los productos (por ejemplo, por relevancia o por precio).
• userInfo (Opcional): información del usuario para la personalización. Debe ser coherente con la llamada a la API Conversational Commerce.
• searchMode (Opcional): define el comportamiento de la búsqueda. PRODUCT_SEARCH es habitual en las consultas generales sobre productos.

Interpretar la respuesta

Este ejemplo de código muestra una respuesta de la API Conversational Commerce.

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

Respuesta de Vertex AI Search para el sector del comercio

En este ejemplo de código se muestra una respuesta de la API 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 comercios con la respuesta (general)

Renderiza estos campos de la respuesta:

• user_query_types: este campo proporciona la(s) clasificación(es) de la intención del usuario. Para ver las acciones detalladas que se pueden llevar a cabo en función de estos tipos, consulta el artículo Tipos de consultas y acciones de los comerciantes.
• conversation_id: puede almacenar este ID único en el almacenamiento de sesión de su navegador o en un almacenamiento similar del lado 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 mismo comprador. Tu modelo conserva el contexto de un conversation_id determinado. Si envías un nuevo conversation_id, se iniciará una nueva sesión. Le recomendamos que defina la duración de la sesión, por ejemplo, 30 minutos de inactividad.
• refined_search: es una lista de consultas de búsqueda refinadas propuestas que se usan para obtener los resultados de búsqueda relevantes. En el caso de SIMPLE_PRODUCT_SEARCH, siempre se trata de una sola consulta. En el caso de otras consultas que buscan respuestas de LLMs, se trata de una o más. Las consultas refined_search se pueden usar para hacer llamadas a la API Search principal (SearchService.Search) o se pueden mostrar a los usuarios como sugerencias.
• conversational_text_response: muestra este texto al usuario como la respuesta principal generada por IA a su consulta.
• followup_question: opcional. Se muestra el followup_question.
• state: este campo indica el estado de la generación de la respuesta ("STREAMING" o "SUCCEEDED"). Puedes usarlo para obtener comentarios sobre la experiencia de usuario, como mostrar un indicador de carga hasta que se muestre "SUCCEEDED". En la siguiente sección se ofrecen más detalles al respecto.

Información sobre la API de streaming

La API Conversational Commerce funciona como una API de streaming. Esto significa que el 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 consultas 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 las mejoras de búsqueda permiten que tu modelo tome decisiones rápidas sobre cómo gestionar la consulta del usuario y su experiencia en cuanto a la latencia de las respuestas de LLM:

• En el caso de los tipos de consulta que no esperan una respuesta de texto conversacional, como SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS y STORE_RELEVANT:
• Como query_types están en el primer fragmento, el sistema sabe inmediatamente que no va a recibir ninguna respuesta de un LLM. Puedes continuar con la gestión predefinida de estos tipos, como mostrar un mensaje estático o redirigir al usuario al servicio de asistencia, sin esperar a que se produzca más contenido conversacional.
• En el caso de SIMPLE_PRODUCT_SEARCH, tu sistema puede hacer una llamada directa a la API Search principal inmediatamente con la consulta refined_search recibida en el primer fragmento. De esta forma, los resultados de búsqueda se muestran con un retraso mínimo, lo que cumple los acuerdos de nivel de servicio típicos de la experiencia de búsqueda.
• En el caso de los tipos de consulta que sí esperan una respuesta de texto conversacional, como INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON y BEST_PRODUCT:
• Recibes las consultas query_types y refined_search en el primer fragmento. Puedes iniciar inmediatamente una llamada paralela a la API Search principal con estas consultas refined_search para empezar a cargar los resultados de los productos.
• Los siguientes fragmentos se transmiten en streaming y contienen diferentes secciones de la respuesta de texto conversacional. Durante este tiempo, el state sigue siendo "STREAMING".
• Por último, el último fragmento incluye la respuesta de texto completa y sus state cambios a "COMPLETED".
• Este enfoque de streaming permite ofrecer una experiencia fluida a los usuarios finales, ya que los resultados de búsqueda pueden empezar a cargarse mientras se genera el resumen de la IA. Puedes mostrar un indicador de carga de la respuesta conversacional o presentarla después de que se haya completado la transmisión.

Tipos de consultas y acciones de los comerciantes

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

El agente conversacional de comercio usa categorías de consultas de búsqueda para determinar si se genera una respuesta basada en LLMs y cómo gestionan las APIs Conversacional y de Búsqueda las consultas de los usuarios finales en estos casos:

Categorías	Consultar clasificaciones
1. Consultas irrelevantes que no requieren una respuesta de un LLM	QUERY_TYPE_UNSPECIFIED: tipo de consulta no especificado. RETAIL_IRRELEVANT: consultas irrelevantes para el dominio de comercio, como una consulta adversarial (por ejemplo, cómo hacer una bomba), una consulta conversacional (por ejemplo, ¿cómo estás?) o una consulta de jailbreak (por ejemplo, escribe un poema). BLOCKLISTED: consultas bloqueadas explícitamente por los clientes de comercio (por ejemplo, ¿Cuáles son los efectos secundarios del ibuprofeno?).
2. Consultas de asistencia e información	ORDER_SUPPORT: consulta complementaria o de asistencia (como Seguimiento de mi pedido, Estado del pedido 12345). DEALS_AND_COUPONS: consultas relacionadas con ofertas, promociones, ofertas de productos y descuentos (por ejemplo, ¿Hay alguna oferta para el Día de Acción de Gracias?). STORE_RELEVANT: consultas relacionadas con las ubicaciones de las tiendas, incluidos los horarios de apertura y la disponibilidad de productos (por ejemplo, ¿Tenemos leche en stock?). RETAIL_SUPPORT: consultas relacionadas con las compras, incluidos los métodos de pago (¿Qué métodos de pago aceptáis?).
3. Búsquedas por palabras clave que no requieren un LLM Solicitud de 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 Conversational: Respuesta inicial { "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"], "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9", "refinedSearch": [ { "query": "monster energy drinks" } ] } Solicitud a la API Search: Consulta de seguimiento { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "monster energy drinks", "visitorId": "test" }	SIMPLE_PRODUCT_SEARCH: búsquedas básicas de productos, como vestido rojo o enséñame bebidas Monster.
4. Consultas de búsqueda de respuestas de LLM Solicitud de 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 Conversational: 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 Search: 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 de un producto, como muéstrame las especificaciones de [nombre del producto] o ¿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] o compara leche al 1% con leche al 2 %. BEST_PRODUCT: consultas con el patrón que más se ajusta, como ¿Cuál es la galleta más saludable? ¿Qué marca de leche es la mejor?
5. Refinamiento de intents Solicitud de 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 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" }	INTENT_REFINEMENT: el tipo no está claro y puede que sea necesario mantener una conversación de seguimiento o concretar la solicitud para aclarar el tipo, como Ayúdame a organizar una fiesta. Suele ser la intención más popular en las conversaciones.

Categoría 1. Consultas irrelevantes que no requieren una respuesta de un LLM

• QUERY_TYPE_UNSPECIFIED:
• No se ha proporcionado ningún conversational_text_response.
• Acción: gestionarlo como un caso predeterminado o de error. Puedes pedirle al usuario que aclare su duda o indicarle dónde puede recibir ayuda general.
• RETAIL_IRRELEVANT:
• No se ha proporcionado ningún conversational_text_response.
• Acción: Responde mostrando un mensaje adecuado, como No puedo responder a esa pregunta o Soy un asistente de compras. ¿En qué puedo ayudarte?, tal como se define en el diseño de tu aplicación.
• BLOCKLISTED:
• No se proporciona ningún conversational_text_response.
• Acción: gestiona la solicitud de acuerdo con tu política de lista de bloqueo. Normalmente, 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 estos casos, la API no proporciona un conversational_text_response directo de forma predeterminada, pero tienes opciones para dirigir a los enlaces o recursos adecuados.

• ORDER_SUPPORT:
• Acción predeterminada: no se proporciona ningún conversational_text_response. Tu interfaz web debe mostrar un mensaje estándar, enlaces relevantes o redirigir la consulta a tu propia API de asistencia o canal de atención al cliente.
• DEALS_AND_COUPONS:
• Acción predeterminada: no se proporciona ningún conversational_text_response. Tu interfaz web debe mostrar algún mensaje estándar, enlaces relevantes o redirigir la consulta a tu sistema de ofertas o promociones.
• STORE_RELEVANT:
• Acción predeterminada: no se proporciona ningún conversational_text_response. Tu interfaz web debe mostrar un mensaje estándar, enlaces relevantes o redirigir la consulta 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 interfaz web debe mostrar un mensaje estándar, enlaces relevantes o redirigir la consulta a tu propio sistema de preguntas frecuentes e información.

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

• SIMPLE_PRODUCT_SEARCH:
• No se genera ninguna respuesta de texto conversacional.
• Acción: la respuesta de la API siempre devuelve una sola consulta refined_search. Esta consulta refinada actúa como término de búsqueda sugerido. Haz una llamada directa a la API Search principal (SearchService.Search) y obtén resultados de productos relevantes con la consulta original o la consulta refined_search. La refined_search.query puede no proceder 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 ha refinado previamente vestido de fiesta a rojo, la consulta refinada puede ser vestido de fiesta rojo.
• En el caso de las interfaces conversacionales (como los chatbots), es muy recomendable usar el refined_search.query que proporciona la API. En un flujo conversacional, la API optimiza automáticamente las consultas en lenguaje natural, como "¿puedes ayudarme a encontrar plátanos?", para convertirlas en un término de búsqueda de producto preciso ("plátanos"), lo que da lugar a resultados de producto más relevantes.
• En las experiencias de búsqueda principales (como la página de resultados de búsqueda): puede usar el refined_search.query de la API o la consulta original proporcionada por el usuario final, ya que es más probable que la consulta original ya sea un término de búsqueda de producto preciso. Elige la opción que mejor se adapte a tu interfaz web y a tu estrategia de visualización de resultados de búsqueda.
• Opciones de experiencia de usuario: la conversación no tiene que terminar para las consultas SIMPLE_PRODUCT_SEARCH. El usuario puede continuar la conversación enviando el conversation_id en las solicitudes posteriores.
• Opción A: Finalizar la interfaz web conversacional: muchos comercios eligen dirigir al usuario a una página de resultados de búsqueda estándar cuando se detecta una SIMPLE_PRODUCT_SEARCH, lo que cierra la ventana de chat. En este caso, si el usuario final introduce una nueva consulta en el cuadro de búsqueda estándar sin el conversation_id anterior, se tratará como una conversación nueva e independiente, y se emitirá un nuevo conversation_id.
• Opción B: Continuar con la interfaz web conversacional: los comerciantes pueden mantener abierta la ventana de chat. De esta forma, el usuario puede volver al modo de conversación. La decisión de implementar la opción A o la B depende por completo de la experiencia de usuario que prefiera el anunciante.

Para atribuir con precisión las consultas de búsqueda a las interacciones conversacionales y usar todas las funciones analíticas de Vertex AI Search para el comercio, es fundamental etiquetar los eventos correctamente:

1. Recuperar conversation_id. Cuando haces una llamada a la API conversationalSearch, se devuelve el ConversationalSearchResponse.conversation_id.
2. Etiqueta los eventos de usuario. En los casos en los que la respuesta conversacional lleve a una consulta de búsqueda, como si tu sistema ejecuta automáticamente una búsqueda basada en la consulta refinada de SIMPLE_PRODUCT_SEARCH, debes etiquetar ese evento de usuario de búsqueda posterior (UserEvent) con el mismo conversation_id recibido en ConversationalSearchResponse.

Si etiqueta correctamente UserEvent.conversation_id, sus analíticas podrán atribuir con precisión las consultas de búsqueda a las interacciones de conversación anteriores, lo que le proporcionará estadísticas valiosas sobre el comportamiento de los usuarios y las rutas de conversión.

Categoría 4. Consultas de búsqueda de respuestas de LLM

En el caso de estos tipos de consultas, la API genera una conversational_text_response (respuesta de LLM) y también puede proporcionar una o varias consultas refined_search. La conversación no termina y el usuario final puede continuarla.

• PRODUCT_DETAILS:
• Acción: el conversational_text_response proporciona los detalles del producto solicitado. Tu sistema debe mostrar esta información claramente al usuario.
• La respuesta también incluye refined_search (una o varias consultas de búsqueda sugeridas, ordenadas y clasificadas) que se deben usar para obtener resultados de búsqueda mediante la API Search principal.
• PRODUCT_COMPARISON:
• Acción: conversational_text_response ofrece una comparación de los productos especificados. Tu sistema debe mostrar esta información claramente al usuario.
• La respuesta incluye refined_search (una o varias consultas de búsqueda sugeridas, ordenadas y clasificadas) que se deben usar para obtener resultados de búsqueda mediante la API de búsqueda principal.
• BEST_PRODUCT:
• Acción: el conversational_text_response proporciona recomendaciones o información sobre los productos que mejor se ajustan a la consulta. Tu sistema debería mostrar esta información.
• La respuesta incluye refined_search (una o varias consultas de búsqueda sugeridas, ordenadas y clasificadas) que se deben usar para obtener resultados de búsqueda mediante la API de búsqueda principal.

Categoría 5. Refinamiento de intents

• INTENT_REFINEMENT:
• Acción: la respuesta incluye conversational_text_response, un followup_question y refined_search (una o varias consultas de búsqueda sugeridas). El orden de visualización recomendado es el siguiente:
1. conversational_text_response
2. refined_search sugerencias: están ordenadas y clasificadas, por lo que es importante mostrarlas en el mismo orden que en la respuesta.
3. Followup_question
• La respuesta incluye refined_search (una o varias consultas de búsqueda sugeridas, ordenadas y clasificadas) que se deben usar para obtener resultados de búsqueda mediante la API de búsqueda principal.
• En las interacciones posteriores, envía la respuesta del usuario junto con el conversation_id.

Mostrar consultas sugeridas de productos

A continuación, te explicamos cómo configurar la Búsqueda de Google para que muestre preguntas y sugerencias de productos en el agente de comercio conversacional.

Cuando la API Conversacional devuelve consultas de refinedSearch, estas consultas representan excelentes oportunidades para guiar al usuario final hacia productos relevantes. Esto es especialmente útil en la categoría 4 (consultas para obtener respuestas de LLMs) y en la categoría 5 (INTENT_REFINEMENT).

Recomendación

• Mostrar: presenta las N (1-3, pendiente de pruebas sobre el número ideal para tu interfaz web) refinedSearch consultas principales al usuario.
• Mecanismo: estas consultas sugeridas deben ejecutarse a través de la API de búsqueda principal (SearchService.Search) en segundo plano o cuando el usuario interactúe.
• Presentación: muestra los resultados como carruseles interactivos o tarjetas en las que se puede hacer clic para que los usuarios puedan consultar categorías de producto relacionadas o artículos específicos. De esta forma, se ofrece valor inmediato y se acorta la distancia 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 deben enviar a Vertex AI Search para el sector del comercio

Es importante atribuir con precisión las consultas de búsqueda a las interacciones conversacionales y usar todas las funciones analíticas de Vertex AI Search para el comercio mediante el etiquetado de eventos adecuado:

1. Recuperar conversation_id. Cuando haces una llamada a la API conversationalSearch, se devuelve el ConversationalSearchResponse.conversation_id.
2. Etiqueta los eventos de usuario. En los casos en los que la respuesta conversacional lleve a una consulta de búsqueda, como cuando se muestra una sugerencia refined_search en la que el usuario final hace clic o cuando tu sistema ejecuta automáticamente una búsqueda basada en la consulta refinada, debes etiquetar ese evento de usuario de búsqueda posterior (UserEvent) con el mismo conversation_id recibido en el ConversationalSearchResponse.

Si etiqueta correctamente UserEvent.conversation_id, sus analíticas podrán atribuir con precisión las consultas de búsqueda a las interacciones conversacionales anteriores, lo que le proporcionará estadísticas valiosas sobre el comportamiento de los usuarios y las rutas de conversión.

Continuar la conversación

En esta sección se describe cómo mantiene la API Conversational las sesiones de agentes de comercio conversacional y cómo continúan en este último paso.

La API Conversational usa un conversation_id para gestionar las conversaciones en curso. Para asegurar la coherencia entre las respuestas de los LLMs y los resultados de búsqueda, las solicitudes posteriores de Conversational API deben incluir SearchParams que reflejen la configuración de las llamadas a la API de la Búsqueda principal.

Muestra la tabla

Gestión de sesiones	Descripción	Integración de la API Conversational
Crear conversaciones	Para iniciar una conversación, el cliente omite el conversation_id de la solicitud de la API.	Solicitud de ejemplo a la 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" Respuesta de ejemplo 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" }
Continuar la conversación	La API Conversational devuelve un conversation_id como parte de la respuesta de la API. Este ID se puede enviar en las solicitudes posteriores para continuar la misma conversación. De esta forma, te aseguras de que el agente de comercio conversacional responda a las consultas de los usuarios en función del historial de la conversación de esa sesión.	Solicitud de ejemplo a la 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" Respuesta de ejemplo 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" }
Asegurar la coherencia de los resultados de búsqueda	Para asegurarse de que las respuestas del LLM sean coherentes con los resultados de búsqueda que se muestran, el cliente debe usar SearchParams en la solicitud de la API Conversational. Estos parámetros de búsqueda deben tener la misma configuración que la API Search principal.	Solicitud de ejemplo a la 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" } } }

Gestión de sesiones

• Para iniciar una conversación, sigue estos pasos:
  • Descripción: para iniciar una conversación, el cliente omite el conversationId de la solicitud de la API.
  • Cuándo iniciar una conversación: un cliente querrá iniciar una conversación nueva (y, por lo tanto, obtener un conversationId nuevo de la respuesta de la API) en varios casos habituales de experiencia de usuario:
    • Nueva pestaña o sesión: cuando un cliente abre su sitio en una nueva pestaña del navegador o inicia una sesión completamente nueva.
    • Nueva consulta original: en algunos diseños de experiencia de usuario, si un cliente introduce una consulta nueva que no está relacionada, puedes reiniciar el flujo de conversación para asegurarte de que el contexto sea el más relevante.
    • Botón para reiniciar la conversación: si tu interfaz web proporciona un botón explícito Iniciar nuevo chat o Restablecer conversación, al hacer clic en él se iniciará una nueva sesión de conversación.
  • Integración de la API Conversational: la respuesta de la API incluye un nuevo conversationId que se usa en las solicitudes posteriores.
• Continuar la conversación:
  • Descripción: Conversational API devuelve un conversation_id como parte de la respuesta de la API. Este ID debe enviarse en las solicitudes de seguimiento para continuar la misma conversación. De esta forma, te aseguras de que el agente de comercio conversacional responda a las consultas de los usuarios basándose en el historial de la conversación de esa sesión, que incluye el query, el conversational_text_response y el followup_question.
  • Integración de la API Conversational: el cliente envía el conversation_id de la respuesta anterior en el ConversationalSearchRequest.
• Asegúrate de que los resultados de búsqueda sean coherentes:
  • Descripción: para asegurarse de que las respuestas del LLM sean coherentes con los resultados de búsqueda que se muestran al usuario, el cliente debe usar searchParams en la solicitud 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 Search API realizadas para obtener resultados de productos.
  • Integración de la API Conversacional: el objeto searchParams del ConversationalSearchRequest debe rellenarse de forma idéntica al SearchRequest que se usa para la búsqueda de productos principal.

Enviar una solicitud a Vertex AI Search para el sector del comercio

Puedes recuperar el conversation_id del almacenamiento de sesión. La solicitud debe incluir el nuevo query del cliente, que puede 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 consulta refinada. De lo contrario, debe incluir una consulta completamente nueva y no relacionada, así como el conversationId. Recuerda incluir siempre searchParams.

Nota: Si el conversationId se mantiene o se restablece para una nueva consulta del usuario final, dependerá de las opciones de experiencia de usuario específicas que elijas y de la experiencia de usuario seleccionada. La conversationId actúa como memoria del sistema en una sesión de conversación determinada.

• Situación 1: una sola barra de búsqueda y una conversación persistente. Si tu interfaz de búsqueda solo tiene una barra de búsqueda principal o una ventana de conversación persistente, no se restablecerá el conversationId, aunque el usuario final escriba una consulta nueva que parezca no estar relacionada. El sistema usa el historial de conversaciones (vinculado a conversationId) para ofrecer respuestas relevantes en función del contexto.
• Situación 2: Ventana de conversación y ventana de consulta independientes. Si tu interfaz de búsqueda incluye una ventana de chat conversacional independiente y una barra de consulta de búsqueda estándar (como un cuadro de búsqueda en todo el sitio), al introducir una nueva consulta en la barra de búsqueda estándar, se podría indicar implícitamente la intención de iniciar una búsqueda nueva e independiente, lo que podría provocar que se restableciera el conversationId de esa acción de búsqueda específica. Sin embargo, en la ventana de conversación específica, el conversationId siempre debe mantenerse para que no se interrumpa la conversación.

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

Método HTTP y endpoint (igual que la consulta inicial)

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

Solicitud a la API Conversation:

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 Conversational:

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 situaciones en las que un usuario final sigue recibiendo preguntas:

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

Qué deben hacer los comercios con la respuesta

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

• refined_search: este campo contiene las consultas actualizadas que incorporan la información más reciente del usuario final. Debe actualizar la consola del cliente para la consulta actual (por ejemplo, mostrando que la consulta visible para el usuario ha cambiado de "decoraciones" a "decoraciones para fiesta de cumpleaños" o "artículos para fiesta de cumpleaños"). Las consultas de búsqueda refinada se pueden usar en llamadas a la API Search principal (SearchService.Search) o se pueden mostrar al usuario final como sugerencias.
• conversational_text_response: muestra la nueva respuesta de texto generada por IA pertinente a la última interacción.
• followup_question: si la conversación debe continuar para seguir perfeccionando el resultado, se proporciona un nuevo followup_question.

Eventos que se deben enviar a Vertex AI Search para el sector del comercio

El etiquetado de eventos es importante para atribuir con precisión las consultas de búsqueda a las interacciones conversacionales y para usar las funciones analíticas de Vertex AI Search para el sector del comercio.

El proceso de etiquetado de eventos consta de dos pasos:

1. Recuperar conversation_id. Cuando haces una llamada a la API conversationalSearch, se devuelve el ConversationalSearchResponse.conversation_id.
2. Etiqueta los eventos de usuario. En los casos en los que la respuesta conversacional lleve a una consulta de búsqueda, como cuando se muestra una sugerencia refined_search, o si tu sistema ejecuta automáticamente una búsqueda basada en la consulta refinada, debes etiquetar ese evento de usuario de búsqueda posterior (UserEvent) con el mismo conversation_id recibido en el ConversationalSearchResponse.

Si etiqueta correctamente UserEvent.conversation_id, sus analíticas podrán atribuir con precisión las consultas de búsqueda a las interacciones conversacionales anteriores, lo que le proporcionará estadísticas valiosas sobre el comportamiento de los usuarios finales y las rutas de conversión.

Integrar el agente con el filtrado de productos conversacional

En esta guía se explica cómo integrar la API Conversacional y el filtrado de productos conversacional para ofrecer una experiencia de compra basada en IA. Cuando conversationalFilteringSpec.mode está configurado como ENABLED, tu sistema puede pasar directamente de interacciones conversacionales abiertas a filtros de productos guiados, lo que ofrece un recorrido del usuario muy refinado.

Entender la interacción

Cuando se habilitan tanto el agente de comercio conversacional como el filtro de productos conversacional, el sistema aprovecha las ventajas de cada uno. El agente conversacional de comercio gestiona consultas generales, proporciona respuestas generadas por IA y perfecciona las intenciones iniciales, mientras que el filtro de productos conversacional guía a los usuarios a través de selecciones de atributos de productos específicos mediante un modelo de interacción simplificado basado en chips o baldosas.

El punto de interacción y la posible transición entre estos dos modos se produce cuando la clasificación de la API Conversational Commerce lleva a una búsqueda orientada a productos, concretamente SIMPLE_PRODUCT_SEARCH. En este punto, la API puede proporcionar una consulta de búsqueda directa o, si la intención del usuario se puede refinar aún más, activa un flujo de filtrado guiado mediante el filtrado de productos conversacional.

Un principio clave de esta integración es que la API Conversational Commerce gestiona todas las entradas de texto libre, mientras que el filtrado de productos conversacional gestiona los clics en las respuestas sugeridas que aparecen como chips.

Enviar consulta del usuario

Ejemplo de petición del usuario: Ayúdame a organizar una fiesta

Para habilitar tanto el agente conversacional de comercio como el filtro conversacional de productos, asegúrese de que su ConversationalSearchRequest incluya esta configuración:

Solicitud a la 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
  }
}

Las configuraciones clave son las siguientes:

• Conversational_filtering_mode: ENABLED: si asignas el valor ENABLED a este campo en tu conversationalFilteringSpec, le indicas a la API que tu sistema puede gestionar el filtrado de productos conversacional, lo que permite que la API proporcione respuestas relevantes específicas para el filtrado.

Respuesta inicial: perfeccionamiento de la intención

El campo userQueryTypes sigue siendo fundamental para comprender la intención del usuario. En el caso de una consulta inicial amplia, como Ayúdame a organizar una fiesta, es probable que la API la clasifique como INTENT_REFINEMENT si no se identifica de inmediato una búsqueda de producto más específica.

Respuesta de Google

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

Acción

1. Muestra el conversationalTextResponse.
2. Presenta las refinedSearch sugerencias como chips en los que se pueda hacer clic para Decoraciones y Aperitivos. También puedes llamar a la API Commerce Search en paralelo usando las consultas refined_search para mostrar resultados de productos relevantes, como Decoraciones, Snacks en forma de carrusel, junto con la conversación.
3. Mostrar la followupQuestion: ¿Qué tipo de fiesta estás organizando?
4. Permite que los usuarios introduzcan texto libre para continuar la conversación.

Etiquetado de eventos y analíticas

Para asegurarse de que las analíticas y la atribución de la interacción inicial de la conversación sean precisas, haga lo siguiente:

• Recuperar conversation_id. Captura el conversation_id de ConversationalSearchResponse. Este ID es fundamental para vincular todas las acciones posteriores a esta sesión de conversación específica.
• Etiqueta los eventos de usuario. Si la respuesta conversacional lleva a una consulta de búsqueda, como si tu sistema ejecuta automáticamente una búsqueda basada en una consulta refined_search o si el usuario hace clic en una sugerencia refined_search, debes etiquetar ese evento de usuario de búsqueda posterior (UserEvent) con el mismo conversation_id.

Consulta de seguimiento

Cuando el usuario responde a la followupQuestion, la conversación se acota.

Ejemplo de entrada de usuario: Una fiesta de cumpleaños

Refinamiento de la intención | Fragmentos de código

Solicitud a la API Conversational Commerce: 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": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Respuesta de la API Conversational Commerce: consulta 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"
}

Acción

1. Al igual que en la respuesta inicial, actualiza la interfaz web con las nuevas sugerencias de conversationalTextResponse, refinedSearch y followupQuestion.
2. Continúa la conversación pidiendo más detalles.

Etiquetado de eventos y analíticas

Cuando el usuario continúa la conversación:

• Recuperar conversation_id. Asegúrate de que el conversation_id del ConversationalSearchResponse anterior se haya incluido en el ConversationalSearchRequest actual.
• Etiqueta los eventos de usuario. Si la respuesta conversacional lleva a una nueva consulta de búsqueda, por ejemplo, porque un usuario hace clic en una sugerencia de refined_search o porque tu sistema hace una llamada de búsqueda paralela, etiqueta ese evento de usuario de búsqueda posterior (UserEvent) con el mismo conversation_id. Esto ayuda a hacer un seguimiento del recorrido de la conversación de varios turnos.

Transición al filtrado de productos conversacional

A medida que la conversación se vuelve más específica, el sistema puede clasificar la intención como SIMPLE_PRODUCT_SEARCH y, si es adecuado, activar el filtrado de productos conversacional.

Entrada de usuario de ejemplo: Tema de princesa

Solicitud a la API Conversational Commerce: consulta de seguimiento

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

Posibles resultados de la búsqueda de productos principales

Cuando una consulta se clasifica como SIMPLE_PRODUCT_SEARCH, hay dos posibles respuestas de la API, en función de si se activa Filtrado de productos conversacionales. La diferencia principal radica en la presencia y el contenido del campo conversationalFilteringResult.

Resultado 1: se activa el filtrado

Esto ocurre cuando la consulta es lo suficientemente genérica como para poder acotarla más con atributos de producto. La respuesta incluye conversationalFilteringResult, que tu interfaz web debería priorizar.

Respuesta de la API Conversational Commerce: transición al filtrado de productos:

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

Acción

La consulta ahora se ha clasificado como SIMPLE_PRODUCT_SEARCH. En este caso, se activa el filtrado de productos conversacional. Sin embargo, es posible que no active el filtrado de productos conversacional.

• Priorizar la interfaz web de filtrado de productos conversacional: cuando se rellena conversationalFilteringResult, significa que has accedido al modo de filtrado de productos. Tu interfaz web debe destacar el followupQuestion, que aparece en la interfaz de usuario como ¿Qué tipo de decoración de princesa buscas?, y el suggestedAnswers, como botones en los que se puede hacer clic para Globos, Serpentinas y Manteles.
• Mostrar resultados de productos: llama inmediatamente a la API Retail Search con refined_search.query (decoraciones de cumpleaños de princesa) para mostrar los resultados de productos iniciales junto con las opciones de filtrado.
• Práctica recomendada para la experiencia de usuario: debe haber una única barra de entrada de texto libre persistente para toda la experiencia. Esta barra permanece activa en todo momento, incluso durante un flujo de filtrado de productos conversacional. Cuando el conversationalFilteringResult está activo y muestras las respuestas sugeridas como chips en los que se puede hacer clic, los usuarios tienen dos opciones claras:
• Continúa el proceso de filtrado haciendo clic en una respuesta sugerida.
• Inicia una nueva conversación escribiendo una nueva consulta en la barra de texto activa. Esta nueva entrada siempre activa una nueva llamada a la API Conversational Commerce, lo que finaliza el flujo de filtrado actual.

Nota: Esta decisión de diseño se ajusta al principio fundamental de que la API Conversational Commerce gestiona las entradas de texto libre, mientras que el filtrado de productos conversacional gestiona los clics en las respuestas sugeridas.

Resultado 2: No se activa ningún filtro

Si la consulta ya es lo suficientemente específica o no se puede filtrar más, la respuesta no incluye el campo conversationalFilteringResult. En ese caso, debes realizar una búsqueda estándar.

Acción

• Trata la interacción como el final del flujo de conversación y usa la consulta refined_search para llamar a la API Retail Search y mostrar una página de resultados de producto estándar.

Etiquetado de eventos y analíticas

Cuando la conversación pase al filtrado de productos:

• Recuperar conversation_id. Sigue usando el mismo conversation_id.
• Etiqueta los eventos de usuario. Si la transición lleva a una búsqueda inmediata, etiquétala UserEvent con conversation_id. Es importante que, cuando el usuario interactúe con el suggestedAnswers, por ejemplo, cuando un usuario final haga clic en Globos, esta acción también active un UserEvent, como un evento filter o un evento search nuevo, que esté etiquetado con el mismo conversation_id. De esta forma, se puede atribuir las acciones de filtrado dentro del flujo de conversación.

Continuar con el filtrado de productos conversacional

Cuando el usuario seleccione un suggestedAnswer, envía un nuevo ConversationalSearchRequest.

Ejemplo de entrada de usuario (hacer clic en una respuesta sugerida): Globos

Búsqueda de productos sencilla | Fragmentos de código

Solicitud a la API Conversational Commerce: seguir 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"
  }
}

Respuesta de la API Conversational Commerce: seguir filtrando

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

Acción

La API responde con una consulta SIMPLE_PRODUCT_SEARCH, pero sin el campo conversationalFilteringResult, lo que indica que el flujo de filtrado guiado ha finalizado.

• Usa la consulta final refinedSearch (globos de cumpleaños de princesa) para hacer una llamada directa a la API Retail Search.
• Muestra al usuario los resultados finales del producto. En este punto, la conversación puede terminar o el usuario puede introducir una nueva consulta para iniciar una nueva interacción.

Etiquetado de eventos y analíticas

En cada paso del proceso de filtrado de productos, haz lo siguiente:

• Recuperar conversation_id. Utilice siempre el mismo conversation_id en todas las solicitudes de la sesión de filtrado.
• Etiqueta los eventos de usuario. Cada interacción de un usuario con un suggestedAnswer, como un clic, debe activar un UserEvent relevante, como un evento filter o un evento search si se forma una nueva consulta. Esta UserEvent debe etiquetarse con conversation_id para hacer un seguimiento preciso del recorrido de filtrado y de su impacto en la conversión.

Recomendaciones de interfaz de usuario y decisiones de diseño

La interacción entre el agente conversacional de comercio y el filtrado de productos conversacional ofrece una gran flexibilidad. Estos son algunos aspectos clave de la experiencia de usuario que debes tener en cuenta para crear una experiencia fluida e intuitiva:

• Barra de entrada única: solo debe haber una barra de entrada de texto libre para toda la experiencia. No hay una barra de entrada independiente y específica para el filtrado de productos conversacional. De esta forma, se simplifica la interfaz de usuario y se mantiene la coherencia de la interacción.
• Transiciones fluidas: diseña tu interfaz web para que las transiciones entre respuestas conversacionales, consultas sugeridas y opciones de filtrado sean naturales e intuitivas.
• Indicaciones claras: usa señales visuales, como estilos de botones distintos para las respuestas sugeridas, en lugar de entradas generales, e instrucciones claras para guiar al usuario sobre cómo interactuar en cada fase.
• Equilibrio del control: el usuario siempre debe tener la sensación de controlar la dirección de la conversación.
• Filtrar frente a texto libre: la barra de entrada de texto libre permanece activa en todo momento. De esta forma, el usuario siempre tiene dos opciones: hacer clic en una respuesta sugerida para seguir acotando su búsqueda o escribir una nueva consulta en la barra de texto para iniciar una nueva ronda de conversación. Este diseño asegura que, incluso durante un flujo de filtrado, el usuario pueda cambiar a otro tema si sus necesidades cambian.
• Opción de restablecer: ofrece una opción clara para Iniciar una conversación nueva o Restablecer filtros para que los usuarios puedan reiniciar su proceso de búsqueda o filtrado.
• Persistencia visual: incluso al pasar al filtrado de productos, mantener el historial de la conversación en la ventana del chat, como mostrar las preguntas y respuestas anteriores, puede mejorar el contexto y la experiencia de usuario.

Consideraciones y prácticas recomendadas adicionales

Al implementar la interfaz de agente de comercio conversacional, debe tener en cuenta otras consideraciones y prácticas recomendadas:

• Coherencia del ID de visitante: ayuda a asegurar que se envíe de forma coherente un visitor_id único con cada solicitud de un usuario final determinado. Esto es fundamental para que la personalización y el entrenamiento del modelo sean precisos. Lo ideal es que este identificador sea coherente para un usuario final en todas las sesiones y estados de inicio y cierre de sesión.
• Gestión de sucursales: aunque default_branch es habitual, asegúrese de usar el ID de sucursal correcto si su catálogo de productos está estructurado con varias sucursales.
• Interacción con la API Search: en el caso de SIMPLE_PRODUCT_SEARCH y en cualquier caso en el que se proporcione refined_search, recuerda hacer una llamada independiente a la API Search principal (SearchService.Search) con el query del campo refined_search o la consulta original para obtener las fichas de producto reales. La API Conversacional se centra principalmente en la experiencia conversacional y en la comprensión de la intención del usuario, en lugar de devolver directamente resultados de productos.
• Diseño de la interfaz de usuario: diseña tu interfaz web para presentar claramente las opciones conversational_text_response, followup_question y refined_search de forma intuitiva para guiar al usuario.

Siguientes pasos

Para consultar más recursos de asistencia, consulta las preguntas frecuentes sobre las funciones conversacionales.