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.
Limitaciones
Se aplica la siguiente limitación:
- Solo se admite el idioma inglés.
- Solo se admiten las regiones
us-central1
yglobal
. - 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:
- Sigue los pasos para crear un agente y selecciona Build your own.
- Selecciona Generative como el tipo de agente.
- 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}.
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.
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:
- Una guía llamada
Ticket ordering
que realiza pedidos mediante una herramienta llamadaTicket sales API
.- Esta guía acepta un parámetro de entrada con el tipo
number
y el nombreevent_id
. - La herramienta
Ticket sales API
espera una solicitud que incluya unevent_id
.
- Esta guía acepta un parámetro de entrada con el tipo
- Una guía llamada
Event selection
que ayuda a los usuarios a seleccionar un evento y, luego, los enruta aTicket ordering
con el parámetroevent_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ámetroevent_id
en el mismoevent_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.
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.
Crea una guía
Sigue estos pasos para crear una guía:
- Selecciona los recursos generativos en la barra de navegación izquierda.
- Haz clic en Playbooks.
- Haz clic en Crear nueva.
- 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:
- Carga la guía en la consola.
- Haz clic en Historial de versiones.
- Haz clic en Crear versión.
- Proporciona un nombre de versión y haz clic en Guardar.
Para ver el historial de versiones, sigue estos pasos:
- Carga la guía en la consola.
- Haz clic en Historial de versiones.
- Haz clic en Ver historial de versiones.
- 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.