Controladores de estado

Los controladores de estado, también llamados simplemente controladores, se usan para controlar la conversación mediante la creación de respuestas a usuarios finales o la transición de la página actual. Para cada turno de conversación, los controladores se evalúan y pueden afectar la sesión. Los controladores tienen tres tipos generales de datos:

Término Definición
Requisitos del controlador Estos son los requisitos que se deben cumplir para que el controlador tenga efecto en la sesión. Se dice que un controlador se llama cuando se cumplen sus requisitos y afecta la sesión de alguna manera.
Entrega del controlador Si se llama a un controlador, se usa una entrega opcional a fin de crear respuestas para los usuarios finales. Estas respuestas se definen en datos del agente estático o se recuperan de forma dinámica desde tu servicio de webhook.
Objetivo de transición del controlador Si se llama a un controlador, se usa un objetivo de transición opcional para cambiar la página actual. La página siguiente solo puede ser una página de inicio de flujo o una página dentro del flujo activo actual.

Existen dos tipos de controladores de estado con requisitos de controlador diferentes:

Término Definición
Rutas Se llama a las rutas cuando una entrada de usuario final coincide con un intent o se cumple alguna condición en el estado de la sesión. Una ruta con un requisito de intent también se denomina una ruta de intents. Una ruta con solo un requisito de condición también se denomina una ruta de condición.
Controladores de eventos Los controladores de eventos se llaman cuando se invoca un evento. Algunos eventos integrados se activan cuando se recibe una entrada del usuario final inesperada o cuando se produce un error de webhook. También puedes definir eventos personalizados que invocas cuando algo sucede fuera de la conversación.

El procesamiento de un controlador de estado consta de tres pasos:

Término Definición
1. Alcance Un controlador debe estar dentro del alcance para tener algún efecto en la sesión. El alcance se determina en función de si un controlador se aplica a un flujo, a una página o a un parámetro de formulario, y de si el flujo asociado está activo, la página asociada está activa o el agente intenta completar el parámetro del formulario asociado.
2. Evaluation Cada controlador dentro del alcance se evalúa en orden. Si se cumplen los requisitos de un controlador, se aprueba la evaluación.
3. Llamar Si un controlador está dentro del alcance y pasa la evaluación, se llama. Se llama a cualquier entrega asociada y se aplica cualquier objetivo de transición asociado a la sesión.

Alcance

Para que se evalúe un controlador, debe estar dentro del alcance. El alcance del controlador es una herramienta importante y potente que te ayuda a controlar la conversación. Si controlas el alcance de un controlador, puedes controlar lo siguiente:

X Item
Cuando un intent puede coincidir
Cuando se debe verificar una condición
Cuando se puede controlar un evento determinado
Cuando se puede realizar una transición de página
Cuando se proporciona una respuesta de entrega estática
Cuando se llama a una entrega habilitada para webhook para respuestas dinámicas

El alcance se determina en función de si un controlador se aplica a un flujo, a una página o a un parámetro de formulario, y de si el flujo asociado está activo, la página asociada está activa o el agente intenta completar el parámetro del formulario asociado.

Las reglas de alcance detalladas son las siguientes:

  • Rutas de transición aplicadas al flujo activo:
    • Si la página actual es la página de inicio del flujo, están dentro del alcance.
    • Si la página actual no es la página de inicio del flujo, solo están dentro del alcance si tienen un requisito de intent.
  • Las rutas aplicadas a la página actual están dentro del alcance.
  • Los controladores de eventos aplicados al flujo activo están dentro del alcance.
  • Los controladores de eventos aplicados a la página actual están dentro del alcance.
  • Los controladores de eventos aplicados a un parámetro de formulario que el agente, en este momento, intenta completar están dentro del alcance.

Rutas

Las rutas tienen dos requisitos y se debe proporcionar uno o ambos. Si se proporcionan ambos requisitos, se deben cumplir ambos para llamar a la ruta:

Término Definición
Requisitos de Intent Un intent que debe coincidir con la entrada del usuario final para el turno de conversación actual. Cuando una ruta tiene un requisito de intent, se denomina ruta de intents.
Requisito de condición Una condición que se debe cumplir. Cuando una ruta tiene un requisito de condición, se denomina ruta de condición.

Puedes aplicar rutas a flujos (rutas a nivel de flujo) y a páginas (rutas a nivel de página). Por ejemplo, puedes usar rutas en las siguientes situaciones:

X Item
Cuando la entrada del usuario final coincide con un intent, la coincidencia debe activar una respuesta de entrega estática.
Cuando la entrada del usuario final coincide con un intent, la coincidencia debe activar una entrega habilitada para webhook para una respuesta dinámica.
Cuando la entrada del usuario final proporciona el parámetro de forma final requerido, una verificación de condición activa una transición de sesión a otra página.
Cuando la entrada del usuario final proporciona un parámetro de formulario específico, una verificación de condición activa una respuesta de entrega estática.
Es una verificación de condición configurada como true que fuerza una transición de página.

Propagación del intent

Por lo general, cuando se llama a una ruta debido a una coincidencia de un intent, el intent se consume. Un intent consumido no puede volver a coincidir, a menos que una entrada de usuario final nueva active una coincidencia de intent nueva. Sin embargo, es posible propagar una coincidencia de intent de un flujo a otro en la siguiente situación:

  • Una ruta en flow F1 tiene intent I1 como requisito y flow F2 como objetivo de transición.
  • Flow F2 tiene una ruta que también tiene intent I1 como requisito.

En este caso, cuando se llama a la ruta en flow F1, intent I1 coincide dos veces para una sola entrada del usuario final y se llama a ambas rutas.

La propagación de intents es útil para las siguientes tareas:

X Item
Cambia la página actual a una página específica en otro flujo (la ruta del flujo del destino de transición tiene una página de destino de transición específica).
Crea un mensaje de entrada para la página de inicio de un flujo (la ruta del flujo del objetivo de transición tiene una entrega).

Grupos de rutas

Cuando compilas un agente, puedes encontrar que muchas páginas tienen un conjunto común de rutas. Para hacer que las rutas sean reutilizables, puedes definir grupos de rutas. Estos grupos son un recurso para todo el flujo.

Por ejemplo, es posible que desees que tu flujo maneje la entrada del usuario final, como “Quiero agregar un complemento a mi pizza” y “Quiero cambiar el tamaño de mi bebida”. Estas entradas deben manejarse cuando alguna de las páginas del flujo esté activa. Puedes definir dos rutas con intents a fin de manejar estas entradas para todas las páginas relevantes, pero esto es mucho trabajo duplicado. En su lugar, puedes definir el grupo de rutas una vez y agregar una referencia al grupo en todas las páginas relevantes.

Rutas a nivel de flujo

Las rutas a nivel de flujo son rutas que se aplican a un flujo. Estos tipos de controladores tienen los siguientes casos de uso:

X Item
Son controladores con un requisito de condición o de intent dentro del alcance de la página de inicio del flujo.
Son controladores con un requisito de intent dentro del alcance de todas las páginas dentro del flujo.

Rutas a nivel de página

Las rutas a nivel de página son rutas que se aplican a una página. Estos tipos de controladores tienen los siguientes casos de uso:

X Item
Son controladores con un requisito de condición o de intent dentro del alcance cuando las páginas específicas están activas.

Controladores de eventos

Los controladores de eventos tienen un requisito para ser llamados:

Término Definición
Requisito de evento Es un evento que se debe invocar. Los eventos se identifican por su nombre. Algunos eventos integrados se invocan cuando se recibe una entrada inesperada del usuario final o cuando se produce un error de webhook. También puedes definir eventos personalizados que invocas cuando algo suceda fuera de la conversación.

Puedes aplicar controladores de eventos a los flujos (controladores de eventos a nivel de flujo), a las páginas (controladores de eventos a nivel de la página) y a los parámetros (controladores de eventos a nivel de parámetros). Por ejemplo, puedes usar controladores de eventos en las siguientes situaciones:

X Item
Cuando la entrada del usuario final no coincide con ningún intent, un controlador de eventos sin coincidencias proporciona una respuesta de entrega estática específica.
Un cronómetro vence en tu sistema y deseas proporcionar información de recordatorio al usuario final con una respuesta de entrega estática específica.

Controladores de eventos a nivel de flujo

Los controladores de eventos a nivel de flujo son controladores de eventos que se aplican a un flujo. Estos tipos de controladores tienen los siguientes casos de uso:

X Item
Son controladores con un requisito de evento dentro del alcance de la página de inicio del flujo.
Son controladores con un requisito de evento dentro del alcance de todas las páginas dentro del flujo.
Control de entradas de usuario final inesperadas que se comparten por todas las páginas de un flujo
Control de errores de webhook que comparten por todas las páginas de un flujo.
Control los eventos personalizados que invoca tu sistema y que comparten todas las páginas de un flujo.

Cada flujo tiene controladores de eventos para los eventos integrados no-match y no-input. Estos controladores de eventos se crean automáticamente cuando creas un flujo y no se pueden borrar.

Controladores de eventos a nivel de página

Los controladores de eventos a nivel de página son controladores de eventos que se aplican a una página. Estos tipos de controladores tienen los siguientes casos de uso:

X Item
Son controladores con un requisito de evento dentro del alcance cuando hay páginas específicas activas.
Control de entradas de usuarios finales inesperadas, específicas de una página
Control de errores de webhook, específicos de una página.
Control de eventos personalizados que invoca tu sistema, específicos de una página.

Controladores de eventos a nivel de parámetros

Los controladores de eventos a nivel de parámetros son controladores que se aplican a un parámetro de formulario. También se los conoce como controladores de solicitudes nuevas. Estos controladores de eventos no permiten eventos personalizados, ya que están diseñados, en particular, para manejar entradas de usuario final no válidas cuando se completan formularios.

Estos tipos de controladores tienen los siguientes casos de uso:

X Item
El usuario final no proporcionó una entrada válida cuando se le solicitó completar un parámetro de formulario.

Eventos integrados

Los siguientes eventos están integrados. Algunos eventos están restringidos a ciertos niveles.

Nombre del evento
Nivel del flujo Nivel de página Nivel de parámetros Cuando se invoca
sys.no-match-default La entrada del usuario final no coincide con ningún intent de los controladores que están dentro del alcance, ni cumple con ningún parámetro de formulario.
sys.no-match-[1-6] Si proporcionas controladores para cualquiera de estos eventos ordenados de manera forma, se invocan en lugar de sys.no-match-default y en orden: sys.no-match-1, sys.no-match-2, …
sys.no-input-default No se recibió la entrada del usuario final.
sys.no-input-[1-6] Si proporcionas controladores para cualquiera de estos eventos ordenados de manera forma, se invocan en lugar de sys.no-input-default y en orden: sys.no-input-1, sys.no-input-2, …
sys.invalid-parameter Se invoca cuando un webhook invalida el parámetro.
webhook.error La llamada de webhook mostró un error.
webhook.error.timeout Se agotó el tiempo de espera de la llamada de webhook.

Eventos personalizados

Puedes crear eventos personalizados y controladores de eventos. Los eventos se identifican de forma sencilla por nombre. No uses nombres de eventos que comiencen con sys. o webhook. para evitar conflictos con eventos integrados.

A fin de invocar un evento con la API, consulta el campo queryInput.event del método detectIntent para el tipo Session.

Selecciona un protocolo y una versión para la referencia de sesión:

Protocolo V3beta1
REST Recurso de sesión
RPC Interfaz de sesión
Java SessionsClient
Node.js SessionsClient
Python SessionsClient

Orden de evaluación

Los controladores se evalúan en un orden específico. Se aplican las siguientes reglas generales:

  1. Solo se evalúan los controladores dentro del alcance.
  2. Solo se puede llamar a los controladores cuyos requisitos se cumplen.
  3. Si se llama a un controlador sin un objetivo de transición, la evaluación de la lista de controladores continúa. Debido a esta regla, varias entregas pueden agregar varios mensajes a la cola de respuestas.
  4. Si se llama a un controlador con un objetivo de transición, finaliza la evaluación de la lista de controladores.
  5. Si se llama a un controlador con una entrega y esta da como resultado un error de webhook, haz lo siguiente:
    • Si un controlador de eventos está dentro del alcance del evento, controla el evento y la evaluación de la lista de controladores.
    • Si ningún controlador de eventos está dentro del alcance del evento, el webhook falla en silencio.
  6. Cuando se cumple un requisito de intent o de condición, no se consume el intent o la condición, por lo que se pueden llamar a varias rutas con el mismo intent o la misma condición.
  7. Cuando se cumple un requisito de evento, se consume el evento, por lo que solo se puede llamar al primer controlador de eventos que se encontró para el evento.

La evaluación consta de tres fases:

  1. Las rutas que tienen un requisito de intent se evalúan en este orden:
    1. Nivel de página: Son rutas individuales aplicadas a la página actual, en el orden proporcionado.
    2. Grupos a nivel de página: Son grupos de rutas aplicados a la página actual, en el orden proporcionado.
    3. Nivel de flujo: Son rutas aplicadas al flujo activo, en el orden proporcionado.
  2. Las rutas que solo tienen un requisito de condición se evalúan en este orden:
    1. Nivel de página: Son rutas individuales aplicadas a la página actual, en el orden proporcionado.
  3. Los controladores de eventos se evalúan en este orden:
    1. Nivel de parámetro: Los controladores de eventos aplicados al parámetro de formulario de la página actual que el agente intenta completar (controladores de solicitud nuevas) en el orden proporcionado.
    2. Nivel de página: controladores de eventos aplicados a la página actual, en el orden proporcionado.
    3. Nivel de flujo: Los controladores de eventos aplicados al flujo activo, en el orden proporcionado.

Objetivos simbólicos de transición

Cuando ingresas un objetivo de transición para un controlador, puedes ingresar flujos o páginas específicos, pero también puedes ingresar objetivos simbólicos de transición:

Objetivo simbólico de transición
Descripción
START_PAGE Transición a la página de inicio del flujo activo con nombre similar.
END_FLOW Finaliza el flujo activo actual y vuelve a la página que generó la transición al flujo actual.
END_SESSION Borra la sesión actual y pasa a la página especial llamada END_SESSION. La siguiente entrada de usuario reiniciará la sesión en la página de inicio del Flujo de inicio predeterminado.
PREVIOUS_PAGE Transición a la página anterior.
CURRENT_PAGE Vuelve la transición a la página actual. Esto puede ser útil si deseas que el agente repita algo.