Vertex AI Search para retail cambia su nombre a Vertex AI Search para el sector del comercio. Estamos actualizando el contenido para reflejar la nueva marca.

Esta página se ha traducido con Cloud Translation API.

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 deja claras las diferencias entre el agente de comercio conversacional y el filtrado de productos conversacional.

Configuración

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

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 de agente de comercio conversacional. 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:

Para obtener la experiencia conversacional, debe usarse la API Conversational.
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 de 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: 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 (por ejemplo, filter, canonicalFilter, sortBy y boostSpec. Es fundamental que estos parámetros reflejen la configuración utilizada en las llamadas principales a la API Search 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, se inhabilitará de forma predeterminada.
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 de agentes de comercio conversacional. Este es el modo preferido para esta guía de implementación de la búsqueda de agentes de comercio conversacional.

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, lo que incluye la búsqueda de agentes de comercio conversacional y el filtrado conversacional de productos.

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. Consulta la guía adicional sobre cómo integrar ambos productos conversacionales.

Endpoint 2: solicitud a la API Core Search

Hay dos enfoques principales para mostrar los resultados de búsqueda en tu interfaz de usuario:

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 de la conversación

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, consulta el paso 2c Consulta los tipos de consultas y las acciones de los comerciantes.

Método HTTP y endpoint

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

Solicitud de la API de búsqueda de productos 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 obtener información detallada sobre las acciones que se pueden llevar a cabo en función de estos tipos, consulta [Tipos de consultas y acciones de los comerciantes](#step-2c).
conversation_id: puedes almacenar este ID único en el almacenamiento de sesión de tu 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 será una sola consulta. En el caso de otras consultas que busquen respuestas de LLMs, será una o varias. 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 proporcionar información en la interfaz de usuario, como mostrar un indicador de carga hasta que se muestre SUCCEEDED. Puedes consultar más detalles sobre este paso en la sección 2b. Información sobre la API Streaming

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 se encuentra en el primer fragmento, tu 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.

Para 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 de la conversación y su state cambia 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(s) clasificación(es) 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 de comercio conversacional usa categorías de consultas de búsqueda para determinar si se genera una respuesta basada en LLM 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 la ubicación de las tiendas, los horarios de apertura, la disponibilidad de los productos, etc. (por ejemplo, ¿Tenemos leche en stock?). `RETAIL_SUPPORT`: consultas relacionadas con compras, métodos de pago, etc. (como ¿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 (por ejemplo, muéstrame las especificaciones de [nombre del producto], ¿cuál es el contenido de proteínas de la leche al 2 %?). `PRODUCT_COMPARISON`: comparaciones de productos, como compara [nombre del producto] y [nombre del producto], 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 proporciona 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 proporciona 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 de usuario 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 de usuario 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 de usuario 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 de usuario 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, 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 podría 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): puedes 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 de usuario 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 de usuario conversacional: muchos comercios eligen redirigir al usuario a una página de resultados de búsqueda estándar cuando se detecta un 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: Mantener la interfaz de usuario 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:

Obtener conversation_id: cuando haces una llamada a la API conversationalSearch, se devuelve el ConversationalSearchResponse.conversation_id.
Etiqueta de 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 proporcionará los detalles del producto solicitado. Tu sistema debe mostrar esta información claramente al usuario.
La respuesta también incluirá refined_search (una o varias consultas de búsqueda sugeridas, ordenadas y clasificadas) que deben usarse para obtener resultados de búsqueda mediante la API de búsqueda principal.

PRODUCT_COMPARISON:

Acción: la 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 varias consultas de búsqueda sugeridas, ordenadas y clasificadas) que deben usarse para obtener resultados de búsqueda con la API Search principal.

BEST_PRODUCT:

Acción: el conversational_text_response proporciona recomendaciones o información sobre los "mejores" productos en función de 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 deben usarse para obtener resultados de búsqueda con la API Search principal.

INTENT_REFINEMENT:

Acción: la respuesta incluirá 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:

conversational_text_response
refined_search sugerencias: están ordenadas y clasificadas, por lo que es importante mostrarlas en el mismo orden que en la respuesta.
Followup_question

La respuesta incluirá refined_search (una o varias consultas de búsqueda sugeridas, ordenadas y clasificadas) que deben usarse para obtener resultados de búsqueda con la API Search 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 la categoría 5 (INTENT_REFINEMENT).

Recomendación

Pantalla: muestra las N (entre 1 y 3, según las pruebas que hagas para determinar el número ideal para tu interfaz de usuario) refinedSearch principales consultas 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 Search:

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:

Obtener conversation_id: cuando haces una llamada a la API conversationalSearch, se devuelve el ConversationalSearchResponse.conversation_id.
Etiquetar 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 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.

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

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

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 nueva: 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 de usuario incluye un botón explícito para iniciar un nuevo chat o restablecer la 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 incluirá un nuevo conversationId que se usará 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 pasa 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 Conversational: el objeto searchParams del ConversationalSearchRequest debe rellenarse de forma idéntica al SearchRequest que se usa para la búsqueda de productos principales.

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.

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 restablecerás el conversationId, aunque el usuario final escriba una consulta nueva que parezca no estar relacionada. El sistema usará el historial de conversación (vinculado a conversationId) para ofrecer respuestas relevantes en el contexto.
Situación 2: Ventana de conversación y ventana de consulta independientes: si tu interfaz de búsqueda incluye una ventana de chat de conversación independiente y una barra de consulta de búsqueda estándar independiente (como un cuadro de búsqueda en todo el sitio), introducir una nueva consulta en la barra de búsqueda estándar 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 para 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 de 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 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 proporcionará una nueva 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:

Obtener conversation_id: cuando haces una llamada a la API conversationalSearch, se devuelve el ConversationalSearchResponse.conversation_id.
Etiquetar 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.

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 la interfaz de usuario para que presente 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.

Guía para desarrolladores de agentes de comercio conversacional Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Configuración

Enviar una consulta desde el usuario final

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

Endpoint 1: solicitud a la API Conversational

Endpoint 2: solicitud a la API Core Search

Interpretar la respuesta

Respuesta de Vertex AI Search para el sector del comercio

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

Información sobre la API de streaming

Tipos de consultas y acciones de los comerciantes

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

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

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

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

Categoría 5. Refinamiento de intents

Mostrar consultas sugeridas de productos

Recomendación

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

Continuar la conversación

Gestión de sesiones

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

Qué deben hacer los comercios con la respuesta

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

Consideraciones y prácticas recomendadas adicionales

Siguientes pasos

Guía para desarrolladores de agentes de comercio conversacional