Guías generativas

Nota: Esta función tiene acceso limitado. Comunícate con tu equipo de cuentas de Google Cloud para solicitar acceso a esta función y acceder a la documentación de referencia de la API.

Las guías generativas proporcionan una nueva forma de crear agentes de Dialogflow CX con modelos grandes de lenguaje (LLM). En lugar de definir flujos, páginas, intents y transiciones, debes proporcionar instrucciones de lenguaje natural y datos estructurados en forma de guías. Esto puede reducir significativamente el tiempo de creación y mantenimiento del agente, y habilitar tipos nuevos de experiencias de conversación para tu empresa.

Si aún necesitas el control explícito que proporcionan los flujos en determinadas situaciones de conversación, puedes combinar la potencia de las guías y los flujos en un solo agente híbrido.

Nota: El text-bison de Vertex AI es el modelo que usan las guías generativas en la actualidad.

Limitaciones

Se aplica la siguiente limitación:

• Solo se admite el idioma inglés.
• Solo se admiten las regiones us-central1 y global.
• Los agentes de la guía no admiten el envío de un SMS complementario de llamada desde la ruta del intent de bienvenida predeterminado en el flujo de inicio predeterminado, pero puedes habilitar la opción de SMS complementario de llamada en los flujos estándar.

Descripción general de la guía

Las guías son los componentes básicos de sus agentes. Por lo general, un agente tiene muchas guías, en las que cada una se define para manejar tareas específicas. Los datos de la guía se proporcionan al LLM, por lo que tiene la información que necesita para responder preguntas y ejecutar tareas. Cada guía puede proporcionar información, enviar consultas a servicios externos o diferir el manejo de conversaciones a un flujo tradicional o a otra guía para manejar subtareas.

Crea agentes de guía

Cuando creas un agente de Dialogflow, puedes elegir que el agente inicie una conversación con una guía (agente de guía) o con un flujo (agente tradicional).

Para crear un agente de la guía, haz lo siguiente:

1. Sigue los pasos para crear un agente y selecciona Build your own.
2. Selecciona Generative como el tipo de agente.
3. Haz clic en Guardar.

Observa que hay tres selectores de recursos nuevos en el panel de navegación izquierdo. Estos selectores te permiten elegir entre las siguientes opciones:

• Recursos de flujo
• Recursos generativos
• Recursos compartidos

Cuando creas un agente de guía, se crea automáticamente una guía predeterminada.

Datos de la guía

En esta sección, se describen los datos que definen una guía.

Nombre de la guía

El Nombre de la guía es el nombre visible de esta. Las guías pueden referirse a otras con este nombre.

Objetivo de la guía

Un objetivo de una guía es una descripción de alto nivel de lo que esta debe lograr.

Por ejemplo:

Help customers to book flights and hotels.

Pasos de la guía

Los pasos de la guía definen el proceso que se debe seguir para lograr su objetivo.

Cada paso contiene una instrucción de lenguaje natural que puede contener cualquiera de los siguientes elementos:

• Instrucción básica que el LLM puede comprender.
• Una instrucción para enrutar al usuario a otra guía. Se hace referencia a las guías con el formato ${PLAYBOOK: playbook_name}.
• Instrucción para usar una herramienta específica. Se hace referencia a las herramientas con el formato ${TOOL: tool_name}.
• Una instrucción para enrutar al usuario a un flujo de Dialogflow. Se hace referencia a los flujos con el formato ${FLOW: flow_name}.

La descripción de cada paso comienza con “-”, y puedes definir subpasos con sangría.

Por ejemplo:

- greet the customer and ask them how you can help.
    - If the customer wants to book flights, route them to ${PLAYBOOK: flight_booking}.
    - If the customer wants to book hotels, route them to  ${PLAYBOOK: hotel_booking}.
    - If the customer wants to know trending attractions, use the ${TOOL: attraction_tool} to show them the list.
- help the customer to pay for their booking by routing them to ${FLOW: make_payment}.

Nota: Cuando edites pasos, es posible que veas una advertencia que indica que una referencia de un recurso no tiene los ejemplos correspondientes. Puedes guardar y usar la guía con esta advertencia presente, pero es poco probable que funcione de manera confiable hasta que se agreguen ejemplos que usen el recurso.

Parámetros de la guía

Las guías pueden aceptar y emitir información de contexto usando parámetros definidos de forma explícita. Los parámetros se definen por guía en la pestaña Parámetros una vez que la hayas creado.

Los parámetros de la guía tienen un tipo, un nombre y una descripción. Después de definir los parámetros, úsalos en los ejemplos de la guía para mostrarle cómo leer, escribir y usar los valores de parámetros de manera confiable. Consulta los ejemplos de guía de entrada y salida y cómo pasar parámetros para obtener orientación.

Parámetros de entrada de la guía

Los parámetros de entrada permiten que las guías usen valores pasados desde flujos y otras guías. Por ejemplo, una guía podría recibir el nombre preferido de un usuario como parámetro y usarlo para agradecerle personalmente, o bien podría recibir un identificador de pedido como parámetro y usarlo para recuperar detalles del pedido con una herramienta.

Los parámetros de entrada de la guía se definen en función de la guía, y estas no tienen visibilidad de otros tipos de parámetros de Dialogflow CX de forma predeterminada. Cuando un flujo pasa a una guía, los parámetros de la página y de la sesión se propagan a la guía si esta tiene un parámetro de entrada con el mismo nombre. Para comunicar información de un flujo a una guía durante una transición, define los parámetros de entrada de la guía con el mismo nombre que un parámetro de sesión o página presente antes de la transición.

Nota: Es posible que la guía predeterminada no acepte parámetros de entrada. La guía predeterminada funciona como un punto de entrada para las conversaciones del usuario, por lo que no tiene forma de recibir parámetros de entrada.

Crea ejemplos para controlar cómo el valor del parámetro de entrada debe afectar las acciones de la guía. Por ejemplo, si un parámetro de entrada debe afectar la forma en que el agente se refiere al usuario, crea ejemplos que definan un valor para el parámetro y, luego, usa el mismo valor en las acciones de declaración en el ejemplo. Consulta Cómo pasar parámetros para obtener más detalles.

Parámetros de resultados de la guía

Los parámetros de salida permiten que las guías emitan información para que la usen otros flujos o guías. Por ejemplo, una guía podría recopilar un número de pedido de un usuario y emitirlo a través de un parámetro de salida, o bien una guía podría usar una herramienta para reservar un vuelo y emitir el número de confirmación a través de un parámetro de salida.

Crea ejemplos para controlar cómo la guía debe decidir el valor de cada parámetro de resultado. Por ejemplo, si un parámetro de salida que representa un número de confirmación debe derivar su valor del resultado del uso de una herramienta, crea ejemplos en los que el resultado del uso de la herramienta coincida con el valor del parámetro de resultado de la guía.

Cómo pasar parámetros

Las guías, a diferencia de los flujos, no admiten la inserción de valores de parámetros con una sintaxis en particular. En cambio, las guías se basan en instrucciones y ejemplos de instrucciones breves para determinar cómo se deben usar los valores de los parámetros y cómo se deben decidir los valores cuando se especifican los valores de parámetros.

Considera un agente diseñado para la venta de entradas para eventos con las siguientes guías:

1. Una guía llamada Ticket ordering que realiza pedidos mediante una herramienta llamada Ticket sales API.
   1. Esta guía acepta un parámetro de entrada con el tipo number y el nombre event_id.
   2. La herramienta Ticket sales API espera una solicitud que incluya un event_id.
2. Una guía llamada Event selection que ayuda a los usuarios a seleccionar un evento y, luego, los enruta a Ticket ordering con el parámetro event_id para comprar entradas.

En este ejemplo, para garantizar que event_id se pase de manera confiable de Event selection a Ticket ordering y de Ticket ordering a Ticket sales API, se necesitan varios ejemplos.

La guía Ticket ordering debe incluir varios ejemplos que:

• Haz que el parámetro de entrada event_id se especifique con un valor realista, diferente en cada ejemplo.
• Incluye una acción de uso de la herramienta con un cuerpo de solicitud que incluya el mismo valor realista event_id que se especifica en el parámetro de entrada.

La guía Event selection debe incluir varios ejemplos que:

• Incluye una declaración de usuario en la que este seleccione un evento con un event_id realista, diferente en cada ejemplo.
• Incluye una invocación de la guía de Ticket ordering que establezca el parámetro event_id en el mismo event_id realista según lo que decida la selección del usuario.

Además de agregar ejemplos, intenta agregar instrucciones específicas a los pasos de la guía, el objetivo de la guía o los detalles de la herramienta que expliquen cómo se deben usar los parámetros. Por ejemplo, la guía Ticket ordering incluye el siguiente paso:

- Use parameter event_id to send a buy_tickets request with ${TOOL: Ticket sales API}

Con los ejemplos y las instrucciones descritos, la guía Event selection decide correctamente un event_id en función de la selección del usuario y lo pasa como un parámetro de entrada llamado event_id al Ticket ordering playbook. Luego, Ticket ordering pasa el mismo event_id en el cuerpo de una solicitud a Ticket sales API. Las guías dependen de ejemplos con valores de parámetros distintos para ayudarlas a inferir cómo se deben usar los parámetros.

Ejemplos de guías

Cada guía debe tener uno o más ejemplos. Estos son ejemplos de conversaciones entre un usuario final y el agente, incluidos el diálogo y las acciones que realiza el agente. Estos son ejemplos de instrucciones con ejemplos limitados para el LLM.

La consola proporciona una interfaz para que ingreses acciones. Por ejemplo:

Ejemplo de resumen de entrada y resumen de salida

Además de los parámetros de entrada y salida, las guías admiten la recepción de un resumen de entrada y la emisión de un resumen de salida para intercambiar información con otras guías. Los resúmenes son útiles para pasar información contextual abstracta entre guías, mientras que los parámetros son más útiles para pasar campos estructurados y bien definidos entre guías. Los parámetros son la única forma de intercambiar datos entre flujos y guías.

Agrega resúmenes de entrada relevantes a los ejemplos para condicionar la guía y ajustar sus acciones en función de los resúmenes de entrada durante el tiempo de ejecución. Agrega resúmenes de resultados que incluyan detalles relevantes y precisos sobre la conversación de ejemplo para mostrarle a la guía qué detalles es importante resumir.

Nota: Es posible que los ejemplos de la guía predeterminada no definan parámetros de entrada ni un resumen de entrada. La guía predeterminada sirve como un punto de entrada para las conversaciones de los usuarios, por lo que no tiene forma de recibir parámetros de entrada.

Ejemplos de parámetros de entrada y salida

Además de un resumen de entrada y un resumen de salida, si una guía define parámetros de entrada o salida, los ejemplos de la guía deben todos definir esos parámetros de entrada o salida para ayudar al modelo de lenguaje a inferir cómo usar los valores de los parámetros de manera confiable.

En cada ejemplo de la guía, se deben especificar y usar valores para cada parámetro definido en la guía, como se muestra en esta guía con dos parámetros de entrada y uno de salida:

Ejemplo de estado del resultado de la guía

Para cada ejemplo que crees, selecciona el estado de guía que mejor represente el estado final de la conversación de ejemplo:

• OK: Se alcanzó el objetivo de la guía.
• CANCELLED: La guía se detuvo sin alcanzar su objetivo debido a circunstancias de la conversación. Por ejemplo, este estado puede ser apropiado si la conversación incluye a un usuario que cambia de opinión sobre con qué necesita ayuda.
• FAILED: La guía se detuvo sin alcanzar su objetivo debido a un error o una circunstancia no controlable. Por ejemplo, este estado puede ser apropiado si no se pudo alcanzar el objetivo debido a problemas de red durante la invocación de una herramienta.
• ESCALATED: La guía se detuvo sin alcanzar su objetivo porque el usuario solicitó la derivación a un agente humano.

Estrategia de recuperación

La estrategia de recuperación controla si cada ejemplo se incluye o no en la instrucción de la Guía.

• DEFAULT: Se puede omitir el ejemplo si el mensaje se acerca al límite de tokens.
• STATIC: Siempre se incluye el ejemplo.
• NEVER: El ejemplo nunca se incluye en la instrucción. El ejemplo no tendrá ningún efecto en el rendimiento de la guía.

Nota: La estrategia de recuperación “Nunca” puede ser útil para excluir de forma temporal un ejemplo para realizar pruebas a fin de comprender sus efectos en el rendimiento de la guía.

Crea una guía

Sigue estos pasos para crear una guía:

1. Selecciona los recursos generativos en la barra de navegación izquierda.
2. Haz clic en Playbooks.
3. Haz clic en Crear nueva.
4. Proporciona los datos como se describió anteriormente.

Guía predeterminada

Cuando creas un agente generativo, se crea automáticamente una guía predeterminada.

La guía predeterminada es el punto de partida para las conversaciones, por lo que tiene algunas diferencias importantes respecto de otras:

• La guía predeterminada no recibe un resumen de los turnos de conversación anteriores.
• La guía predeterminada no puede definir ni recibir parámetros de entrada.

Versiones de la guía

Puedes guardar las versiones de las guías, que son instantáneas inmutables.

Para guardar una versión de la guía, haz lo siguiente:

1. Carga la guía en la consola.
2. Haz clic en Historial de versiones.
3. Haz clic en Crear versión.
4. Proporciona un nombre de versión y haz clic en Guardar.

Para ver el historial de versiones, sigue estos pasos:

1. Carga la guía en la consola.
2. Haz clic en Historial de versiones.
3. Haz clic en Ver historial de versiones.
4. El panel del historial de versiones se abre en el lado derecho. Puedes hacer clic en cada versión para ver su contenido.

Herramientas

Los pasos de la guía pueden hacer referencia a las herramientas que deben usarse para lograr el paso. Para cada herramienta que usan las guías, debes proporcionar los detalles de la herramienta mediante un esquema de OpenAPI.

Actualmente, se admiten las llamadas a la API de HTTP o las consultas al almacén de datos.

Puedes proporcionar un ID de sesión como una ruta o un parámetro de búsqueda. Por ejemplo:

parameters:
  - name: petId
    in: path
    description: ID of pet that needs to be updated
    required: true
    schema:
      $ref: '@dialogflow/sessionId'
  - name: petName
    in: query
    description: ID of pet that needs to be updated
    required: true
    schema:
      $ref: '@dialogflow/sessionId'

Las siguientes limitaciones se aplican a las llamadas a la API de HTTP:

• Excepto por el ID de sesión, no se admiten los parámetros de consulta.
• El cuerpo de la solicitud y la respuesta debe estar vacío o ser JSON.
• Las funciones de esquema avanzadas, como oneOf, no son compatibles.

En el siguiente ejemplo, se muestra cómo hacer referencia a un almacén de datos:

"dataStoreConnections": [
    {
       "dataStoreType": "DATA_STORE_TYPE",
       "dataStore": "projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID"
    }
]

El valor DATA_STORE_TYPE puede ser uno de los siguientes:

• PUBLIC_WEB: Es un almacén de datos que tiene contenido web público.
• UNSTRUCTURED: Es un almacén de datos que contiene datos privados no estructurados.
• STRUCTURED: Es un almacén de datos que contiene datos estructurados (por ejemplo, preguntas frecuentes).

En el siguiente ejemplo, se muestra cómo hacer referencia a una herramienta de la API de HTTP:

openapi: 3.0.2
info:
  title: Search Attraction Tool
  description: >-
    This API search for attractions for travel purposes
  version: 1.0
servers:
  - url: https://search-attraction.app
paths:
  /search:
    post:
      summary: Search for attractions given a query
      operationId: search
      requestBody:
        description: Query
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
      responses:
        '200':
          description: Successfully got results (may be empty)
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: string
components:
  schemas:
    Query:
      required:
        - text
      type: object
      properties:
        text:
          type: string

prácticas recomendadas

Las siguientes prácticas recomendadas pueden ayudarte a compilar agentes sólidos.

Al menos un ejemplo para cada guía

Debes tener al menos un ejemplo para cada guía. Sin ejemplos suficientes, es probable que una guía genere un comportamiento impredecible. Si tu agente no responde o no se comporta de la manera esperada, es probable que la causa sea ejemplos faltantes o mal definidos. Intenta mejorar tus ejemplos o agregar otros nuevos.

Precisión de instrucciones y ejemplos

Si bien es útil escribir pasos instructivos claros y descriptivos, la calidad y cantidad de los ejemplos es lo que determina la exactitud del comportamiento del agente. En otras palabras, dedica más tiempo a escribir ejemplos detallados que a escribir instrucciones perfectamente precisas.

Campo operationsId del esquema de herramientas

Cuando defines esquemas para tus herramientas, el valor operationId es importante. Las instrucciones de la guía harán referencia a este valor. A continuación, se incluyen recomendaciones de nombres para este campo:

• Solo letras, números y guiones bajos.
• Debe ser único entre todas las operationId descritas en el esquema.
• Debe ser un nombre significativo que refleje la funcionalidad proporcionada.

Validación del esquema de la herramienta

Debes validar el esquema de tu herramienta. Puedes usar el Editor de Swagger para comprobar la sintaxis de esquema de tu openAPI 3.0.

Cómo generar un esquema con Bard

Bard puede generar un esquema por ti. Por ejemplo, prueba “puedes crear un ejemplo de esquema de openAPI 3.0 para el Calendario de Google”.

Guías enfocadas

Evita crear guías muy grandes y complejas. Cada libro de jugadas debe realizar una tarea específica y clara. Si tienes una guía compleja, considera dividirla en subguías más pequeñas.

Casos de prueba

Se mejoró la función existente de caso de prueba para admitir guías.

Se agregó el campo obligatorio Resultado esperado del caso de prueba, que proporciona una lista de acciones en forma de ejemplos de guía. El caso de prueba verifica que las acciones se realizaron según lo previsto.

Cuando veas una guía o una versión de guía, puedes hacer clic en la pestaña Test Cases sobre los datos de la guía para ver los resultados de los casos de prueba y ejecutar uno a pedido.

También puedes comparar los resultados de los casos de prueba de diferentes versiones de una guía. Selecciona un caso de prueba y, luego, haz clic en Comparar.

Para ver todos los casos de prueba del agente, haz clic en Casos de prueba en el panel de navegación izquierdo.

Historial de conversaciones

La función existente de historial de conversaciones se mejoró para admitir las guías.

Se agregó información para la ejecución de la herramienta, la invocación de guía y la invocación de flujo desde un agente de guía.