Acciones y parámetros

En esta página, se describe la configuración de acciones y parámetros para intents, y cómo se usan cuando los intents coinciden en el entorno de ejecución.

Dónde encontrar estos datos

Cuando compilas un agente, es más común usar la consola de Dialogflow ES (consulta la documentación, abre consola). En las instrucciones que se detallan a continuación, nos enfocaremos en el uso de la consola. Para acceder a los datos de las acciones y los parámetros, haz lo siguiente:

1. Ve a la consola de Dialogflow ES.
2. Selecciona un agente.
3. En el menú de la barra lateral izquierda, selecciona Intents.
4. Selecciona un intent.
5. Desplázate hasta la sección Action and parameters (Acción y parámetros).

Si compilas un agente con la API en lugar de la consola, consulta la referencia de los intents. Los nombres de los campos de la API son similares a los de la consola. En las instrucciones que se detallan continuación, se resaltan las diferencias importantes entre la consola y la API.

Acciones

El campo de acción es un campo de conveniencia sencillo que ayuda a ejecutar la lógica en tu servicio.

Cuando compilas un agente, puedes configurar este campo con cualquier texto que te resulte útil.

Cuando un intent coincide en el tiempo de ejecución, Dialogflow proporciona el valor de acción a tu solicitud de webhook de entregas o la respuesta de interacción de la API. Se puede utilizar para activar lógica específica en tu servicio.

Parámetros

Cuando un intent coincide en el entorno de ejecución, Dialogflow proporciona los valores extraídos de la expresión del usuario final como parámetros. Cada parámetro tiene un tipo, llamado tipo de entidad, que dicta cómo se extraen los datos. A diferencia de la entrada sin procesar del usuario final, los parámetros son datos estructurados que se pueden usar fácilmente para realizar alguna lógica o generar respuestas.

Cuando compilas un agente, puedes controlar cómo se extraen los datos mediante la anotación de las partes de tus frases de entrenamiento y la configuración de los parámetros asociados.

En la siguiente lista, se muestran los campos de una configuración de parámetros. Se incluyen ejemplos de la frase de entrenamiento "reservar una habitación el martes", en la que se anota "martes".

• Obligatorio (Required): Marca esta casilla si se requiere el parámetro para completar el intent. Consulta la sección Rellena ranuras con parámetros obligatorios, que se encuentra a continuación.
• Nombre del parámetro: nombre que identifica el parámetro. Ejemplo: date.
• Entidad: tipo de entidad asociado con el parámetro. Ejemplo: @sys.date.
• Valor: en la mayoría de los casos, esto se configura en una referencia de parámetro como $parameter-name, que se usa como marcador de posición para el valor extraído en el entorno de ejecución. Sin embargo, este campo también se puede usar para seleccionar valores alternativos. Consulta la sección Valores y referencias del parámetro, que se encuentra a continuación. Ejemplo: $date.
• Es lista: marca esta casilla si los valores se deben mostrar como una lista. Consulta la sección Lista de parámetros, que se encuentra a continuación.
• Mensajes (Prompts): Preguntas que el agente formulará al usuario final si no se proporcionó este parámetro. Este campo solo se usa si el campo Obligatorio está marcado. Consulta la sección Rellena ranuras con parámetros obligatorios, que se encuentra a continuación.
• Valor predeterminado: Valor por defecto del parámetro cuando el usuario final no proporciona un valor. Para cambiar el valor predeterminado con la consola, debes colocar el cursor sobre la fila de parámetros y hacer clic en el menú de la derecha.

Cuando un intent coincide en el entorno de ejecución, Dialogflow proporciona datos de parámetros a tu solicitud de webhook de entrega o a la respuesta de interacción de la API. Estos se proporcionan como una asignación entre nombres y valores de parámetros.

Cuando se compila un agente, las respuestas pueden incluir valores de parámetros. Consulta Valores y referencias del parámetro, que se encuentra a continuación.

Lista de parámetros

Cuando compilas un agente con la consola, si marcas la opción Es lista (Is List), el parámetro se configura como una lista. Las listas pueden contener varios elementos. Por ejemplo, un agente de pedido de producción puede esperar las siguientes expresiones del usuario final:

• “Quiero manzanas”.
• "Quiero manzanas y naranjas".
• “Quiero manzanas, naranjas y bananas”.

Cuando anotas frases de entrenamiento con parámetros de lista, las frases pueden contener uno o más ejemplos de parámetros, y cada uno se anota por separado:

Una vez que anotas al menos dos palabras o frases con el mismo parámetro en una sola frase de entrenamiento, la opción Es una lista se habilita automáticamente. Si inhabilitas esta opción, pero mantienes la misma anotación, Is List se volverá a marcar automáticamente una vez que abras la página con esta anotación.

En los agentes multilingües, la opción Is List no es específica de un idioma.

Valores y referencias del parámetro

Las referencias del parámetro son variables que contienen valores del parámetro extraído en el entorno de ejecución. Cuando compilas un agente, puedes usar referencias del parámetro en las respuestas del intent, en los mensajes del parámetro y en el campo Valor del parámetro.

Por ejemplo, puedes usar $parameter-name en la respuesta de un intent. Cuando Dialogflow responde al usuario, reemplazará esa referencia del parámetro con el valor del parámetro extraído en el entorno de ejecución. Esto es útil para resumir la información proporcionada por el usuario final. Por ejemplo, la respuesta de tu intent podría ser: “De acuerdo, reservé una habitación para ti el $date”.

Referencia básica del parámetro

Para hacer referencia al valor de un parámetro que extrajo la entidad asociada, usa el siguiente formato:

$parameter-name

Por ejemplo, si el nombre del parámetro es date, puedes referirte a él como $date.

Referencia del parámetro para un valor original

Cuando el texto coincide con una entidad en particular, a menudo se convierte en texto, que es más conveniente para el procesamiento. Por ejemplo, la palabra “manzanas” en una expresión de usuario final se puede extraer como “manzana” para una entidad de fruta. Para hacer referencia al valor del parámetro exactamente como lo escribió o pronunció el usuario final, usa el siguiente formato:

$parameter-name.original

Por ejemplo, si el nombre del parámetro es date, puedes referirte al valor original como $date.original.

Referencia del parámetro para fechas ambiguas

Cuando un parámetro se asocia con la entidad del sistema @sys.date, y el usuario final proporciona una fecha parcial (sin especificar el mes, el día y el año), Dialogflow coincidirá con la fecha más cercana en el futuro. Sin embargo, también puedes recuperar variaciones de esta fecha.

Puedes recuperar la coincidencia parcial explícita, en la que Dialogflow sustituye la parte desconocida por U mediante el siguiente formato:

$parameter-name.partial

Puedes recuperar la fecha más cercana en el pasado con el siguiente formato:

$parameter-name.recent

Por ejemplo, si la fecha de hoy es 11 de agosto de 2021, el nombre de tu parámetro es date y el usuario dice “13 de agosto”:

Referencia del parámetro	Valor resuelto
$date	2021-08-13
$date.partial	UUUU-08-13
$date.recent	2020-08-13

Referencia de parámetro para una entidad compuesta

Las entidades compuestas son entidades que contienen otras subentidades. Para hacer referencia al valor de la subentidad de un parámetro, usa el siguiente formato:

$parameter-name.sub-entity-name

Por ejemplo, si el nombre del parámetro es move y el nombre de la subentidad es direction, puedes referirte al valor de la subentidad como $move.direction.

Referencia de parámetro para un contexto activo

Los contextos pueden servir como almacenamiento temporal para los valores del parámetro. Para hacer referencia al valor de un parámetro obtenido a partir de un contexto activo, usa el siguiente formato:

#context-name.parameter-name

Por ejemplo, si el nombre del parámetro es room y reservation es un contexto activo, puedes referirte al valor del parámetro como #reservation.room.

Referencia de parámetro para un parámetro de evento

Para hacer referencia a un parámetro de evento, usa el siguiente formato:

#event-name.parameter-name

Por ejemplo, si el nombre del parámetro es duration y el nombre del evento es alarm, puedes referirte al parámetro del evento como #alarm.duration.

Campo Valor (Value) del parámetro

Las referencias del parámetro en el campo Valor (Value) del parámetro tienen una importancia especial. El contenido de este campo determina el valor resuelto para $parameter-name en las respuestas de los intent y los mensajes del parámetro. Dialogflow procesa los datos del parámetro en el siguiente orden:

1. Extrae el valor del parámetro de la expresión del usuario final mediante la entidad asociada.
2. Resuelve el contenido del campo Valor (Value) del parámetro.
3. Configura $parameter-name en el contenido resuelto del campo Valor (Value) del parámetro. Si el campo Valor (Value) no se configura como $parameter-name, se restablecerá el valor de $parameter-name a un valor distinto.
4. Resuelve el contenido de las respuestas de los intents y los mensajes del parámetro.

A continuación, se presentan algunos ejemplos a fin de ilustrar los efectos de este orden en la expresión del usuario final “Quiero comprar una camisa pequeña”.

Ubicación de la referencia de parámetro	Contenido configurado	Contenido resuelto
Campo Value (Valor) del parámetro	$size	S
Respuesta al intent	Elegiste el tamaño: $size	Elegiste el tamaño: S

Ubicación de la referencia de parámetro	Contenido configurado	Contenido resuelto
Campo Value (Valor) del parámetro	$size.original	pequeño
Respuesta al intent	Elegiste el tamaño: $size	Elegiste el tamaño: pequeño

Ubicación de la referencia de parámetro	Contenido configurado	Contenido resuelto
Campo Value (Valor) del parámetro	$size	S
Respuesta al intent	Elegiste el tamaño: $size.original	Elegiste el tamaño: pequeño

Rellena ranuras con parámetros obligatorios

Cuando compilas un agente, puedes marcar los parámetros como obligatorios. Un intent no está completo hasta que el usuario final haya suministrado datos para cada uno de estos parámetros obligatorios.

Cuando un intent coincide en el tiempo de ejecución, el agente de Dialogflow continúa recopilando información del usuario final hasta que el usuario haya proporcionado datos para cada uno de los parámetros obligatorios. Este proceso se llama relleno de ranuras.

Dialogflow no envía una solicitud de webhook de entregas hasta que haya recopilado todos los datos obligatorios del usuario final, a menos que esté habilitado el webhook para el relleno de ranuras.

Dialogflow envía una respuesta de interacción de la API para cada paso del relleno de ranuras. Para cada una de estas respuestas de relleno de ranuras, el intent y la acción serán los mismos, y se proporcionarán los parámetros recopilados hasta el momento.

Cuando compilas un agente, proporcionas mensajes que el agente usará para obtener datos de parámetros del usuario final. También puedes proporcionar variaciones de los mensajes para que el agente no haga siempre la misma pregunta.

Por ejemplo, considera que tu agente de tienda de ropa tiene un intent con parámetros obligatorios para los siguientes elementos:

• tipo de ropa
• cantidad
• talla
• color

Completar un intent podría ser algo parecido a lo siguiente:

Usuario: me gustaría comprar una camiseta.
Agente: ¿cuántas quieres?
Usuario: 3
Agente: ¿qué color te gustaría?
Usuario: negro
Agente: ¿de qué tamaño?
Usuario: mediano
Agente: entendido, son tres camisetas negras de tamaño mediano

Si el usuario final proporciona datos para más de un parámetro en una sola expresión, Dialogflow recopila los datos proporcionados y continúa solicitando los datos faltantes. Por ejemplo, el usuario final puede decir: “Me gustaría comprar tres camisetas negras”. Dialogflow le preguntará al usuario acerca de la talla.

Ordena los parámetros

Cuando compilas un agente, puedes ordenar los parámetros, lo que determina el orden en el que el agente solicitará al usuario final los datos que faltan.

Si compilas un agente desde la consola, al desplazarte sobre un parámetro se mostrará un ícono de reordenamiento a la derecha. Puedes arrastrar este ícono para cambiar la posición del parámetro en la lista.

Referencias del parámetro en mensajes

Cuando compilas un agente, puedes usar referencias del parámetro en los mensajes, pero solo para los parámetros requeridos antes del mensaje. Por ejemplo, si el parámetro color es anterior al parámetro quantity, puedes usar el siguiente mensaje para el parámetro quantity: How many $color t-shirts would you like to buy?

Cancela el relleno de ranuras

Cuando el usuario final dice una frase de salida como “Cancelar”, “Detener”, “Suficiente”, etc., el agente responde “De acuerdo, cancelado” y borra los contextos de relleno de ranuras.

Si usas la API, el campo DetectIntentResponse.queryResult.cancelsSlotFilling se establece en true cuando se cancela el relleno de las ranuras. Para obtener más información, consulta la documentación de detectIntent del tipo Sessions.