Diseña los temas como miniagentes para evitar mensajes duplicados

Note

Este artículo describe características y comportamientos de los temas con un desencadenante conversacional en el arnés estándar. Descubre cómo acceder a las funciones estándar en Acceder a los agentes estándar y a los flujos de agentes.

Este artículo se centra en las mejores prácticas de diseño para evitar mensajes duplicados. Los mensajes duplicados provienen de huecos de contexto, así que el diseño comienza por entender cómo fluye el contexto. Consulta el diagrama en Distribución de contexto en el arnés estándar para entender cómo la capa de orquestación comparte contexto con cada componente.

En el entorno estándar, el planificador invoca los temas del mismo modo que invoca a las herramientas y a los agentes. Lee la descripción de cada tema para decidir cuándo utilizarlo, genera las entradas del tema a partir de su contexto activo y del usuario, y lee las salidas del tema cuando termina. Un tema con una descripción clara, entradas bien definidas y salidas bien definidas se comporta como un mini-agente en el plan: la capa de orquestación recopila lo que el tema necesita, el tema ejecuta su lógica, devuelve lo que ha producido, y la capa de orquestación formatea y comunica la respuesta al usuario.

Para el usuario, un miniagente resulta conversacional. El usuario puede hablar de forma natural mientras el tema recoge las entradas que necesita, hacer preguntas de seguimiento y obtener respuestas enriquecedoras del agente.

Tip

En el arnés estándar, mantener la lógica determinista dentro del tema y dejar la comunicación del usuario a la capa de orquestación. Recoge los valores que el tema necesita como entradas antes de ejecutarse y devuelve lo que ha producido como salidas después de ejecutarse.

Nombra y describe el tema para que la capa de orquestación pueda enrutar hacia él

La capa de orquestación utiliza el nombre y la descripción del tema para enrutar las solicitudes al tema. Escribe ambos elementos para la capa de orquestación. Dale al tema un nombre claro y específico que describa lo que hace.

Escribe la descripción en dos partes. Primero, explica cuándo usar el tema. Segundo, explica brevemente qué hacer en función de los resultados del tema, incluyendo cómo la capa de orquestación debe enrutar las solicitudes y gestionar los resultados después de que el tema se ejecute. No describas las pantallas internas o los pasos del tema.

Por ejemplo, utiliza la siguiente descripción para un tema que responde a consultas sobre el saldo de la cuenta y devuelve una salida answered:

This topic handles account balance requests. 
If its answered output is true, the user has already received their response and it should not be answered again.

Recoge entradas antes de que el tema se publique

Proporciona al tema un valor de entrada para cada valor que necesite. La capa de orquestación puede recopilar esos valores de su contexto activo y del usuario de forma conversacional antes de que el tema se ejecute. Se entrega una entrada a una variable que la lógica del tema utiliza después.

Utiliza el nombre de la entrada, la descripción, la entidad y los ajustes de validación para ayudar a que la capa de orquestación llene una entrada con precisión:

  • El nombre de entrada indica a la capa de orquestación qué se está recopilando, y se usa para formar la pregunta de si la capa de orquestación tiene que pedirle al usuario ese valor. Nómbralo por el valor, no por el mecanismo. Por ejemplo, nombra una entrada The user's request about... en lugar de OData filter, para que la capa de orquestación no pida al usuario que escriba una consulta.

  • La descripción de entrada es un prompt para la capa de orquestación, no una etiqueta para el usuario. Úsalo para indicar a la capa de orquestación cómo interpretar, restringir o transformar el valor antes de que el tema lo reciba. La capa de orquestación puede rellenar una entrada de la conversación, de una salida anterior o de datos de perfil de usuario. Puede elegir entre un conjunto de valores, aplicar ciertas restricciones y escribir consultas basadas en la información del esquema.

    Las descripciones de entrada incluso pueden indicar a la capa de orquestación que construya un valor en un formato específico. Por ejemplo, un tema que filtra una lista puede recibir una entrada cuya descripción indica a la capa de orquestación cómo construir el filtro a partir de la petición del usuario, incluyendo los campos disponibles, la sintaxis de la consulta y algunos ejemplos.

  • Las entidades establecen el tipo y rango permitidos para una entrada, por lo que solo los valores válidos llegan a la lógica del tema.

  • La validación avanzada y la lógica condicional, incluyendo Power Fx, actúan como comprobaciones deterministas. Pueden impedir que se llene una entrada, o impedir que el tema actúe, cuando no se cumple una condición.

Las comprobaciones deterministas de entrada son tan fiables como el código, por lo que se respetan las reglas de negocio y las restricciones de cumplimiento incluso cuando se genera el resto del plan.

Mantén la lógica y las salvaguardas en el tema

Mantén el trabajo determinista del tópico dentro del propio tópico: los pasos que ejecuta, los cálculos que realiza y las reglas que aplica. El creador ejerce control y aplica una lógica de negocio crucial que funciona siempre de la misma manera, como una herramienta.

Devuelve los resultados como salidas, no como mensajes al usuario

Cuando el tema termine, devuelve lo que ha producido como salidas para que la capa de orquestación pueda usarlo y decidir cómo responder. Prefiero este enfoque a que el tema envíe mensajes directos al usuario. Un tópico que envía mensajes al usuario mientras la capa de orquestación también responde es una fuente habitual de mensajes duplicados: la capa de orquestación no sabe que el tópico ya ha respondido.

Importante

Un tema que no devuelve salidas es una señal de alerta. Si un tema respondió al usuario, recogió un valor o mostró una carta pero no devuelve nada, la capa de orquestación no puede ver lo que ha pasado y puede responder a la misma petición de nuevo. Este comportamiento es la causa más común de los mensajes duplicados procedentes de temas.

Se recomiendan encarecidamente los siguientes resultados probados como patrones fiables para el contexto y la comunicación. Aplican tanto si el tema responde directamente al usuario como si devuelve toda la información a la capa de orquestación para responder.

Output Description Cómo usar
answered Cierto si el usuario ya ha recibido una respuesta satisfactoria a su solicitud dentro de este tema. Establécelo en `true` en el tema una vez que haya respondido o mostrado el resultado. Consulta la instrucción de primer nivel que sigue, que asegura que la capa de orquestación trate esa parte de la petición como respondida y no la repita.
choiceReceived Cierto si el usuario ya ha hecho su elección en este tema. Establécelo en true una vez que el usuario realice una selección, por ejemplo, al seleccionar un botón de tarjeta. La capa de orquestación no vuelve a formular la pregunta.
balanceValue El valor que el tema recuperó y ya proporcionó al usuario. Establécelo en los datos importantes que ha recuperado el tema y asigna un nombre a la salida de esos datos. La capa de orquestación lo reutiliza desde el contexto en vez de recuperarlo.
messageSummary Un breve resumen de lo que ya se mostró al usuario, para mantener en contexto. Configúralo cuando un mensaje lleve información que el plan necesita más adelante. La capa de orquestación se mantiene consciente de lo que se le ha dicho al usuario y no lo repite ni lo contradice.

Las salidas por sí solas son suficientes para modelos antiguos. Los modelos más recientes también necesitan una instrucción de nivel superior que indique a la capa de orquestación que revise las salidas antes de responder.

Esta instrucción de nivel superior es un ejemplo probado y funcional. Edítalo y personalízalo según sea necesario.

Siempre que se llame a cualquier tema o agente, comprueba siempre el valor booleano de salida 'answered' antes de decidir qué responder. Los temas y agentes tienen su propio canal de comunicación con el usuario. Si 'respondido' es cierto, siempre asume que la petición ha sido respondida adecuadamente usando al menos una de las variables de salida y comprueba cuáles basándose en la descripción de salida. No des un reconocimiento incómodo del contenido respondido. Proporciona solo los resultados pendientes y continúa la conversación de forma natural con el siguiente paso.

El término canal no se refiere a un canal de integración. Es un dispositivo de indicaciones que indica a la capa de orquestación que el usuario podría haber visto ya la respuesta a través de otro componente. Dependiendo del modelo del agente, puede ser más efectivo colocar una instrucción similar en las instrucciones del propio agente. Aprende más en Diseñar una instrucción robusta de nivel superior para evitar mensajes repetidos.

Si el tema debe mostrar algo que la capa de orquestación no puede reproducir, como una Tarjeta Adaptativa, deja que el tema lo muestre y devuelva una salida en estado respondido.

Tip

Infórmate más sobre mensajes duplicados y salidas en estado respondido en Mejores Prácticas de Diseño para evitar mensajes duplicados. Aprende cómo el contexto se mueve entre la capa de orquestación y un tema en la distribución de contexto en el arnés estándar.

Recoge respuestas cuando un tema aún necesita intervención del usuario

Algunos temas deben hacer una pregunta o mostrar una tarjeta, por ejemplo, para recopilar una elección mediante botones. Este enfoque de diseño es válido. Ten en cuenta que una pregunta abierta o una tarjeta debe resolverse cuando el usuario cambia de rumbo antes de responder.

Antes de añadir un nodo de pregunta, considera si el valor puede recogerse como entrada en su lugar. Al mantener un nodo de pregunta, maneja el caso en que el usuario pida otra cosa mientras la pregunta sigue abierta. Más información en Una pregunta abierta o devoluciones de tarjeta después de que se haya gestionado una solicitud diferente.

Ejemplo: Evitar que se vuelva a pedir una selección de Carta Adaptativa

Un tema pide al usuario que elija una categoría con una Tarjeta Adaptativa:

¿En qué categoría es tu problema?

[Facturación] [Técnico] [Cuenta]

La capa de orquestación recibe el texto de la pregunta a través del historial de conversaciones, pero no el hecho de que la carta se mostró o que el usuario seleccionó un botón. Después de que el usuario selecciona un botón, la capa de orquestación puede volver a hacer la misma pregunta en texto plano.

Diseña el tema para que notifique su acción y así evitar este problema:

Output Tipo A qué valor configurarlo
answered Verdadero/Falso Verdadero cuando el tema ya ha mostrado la respuesta o la indicación al usuario.
choiceReceived Verdadero/Falso Cierto cuando el usuario ya ha hecho una elección.
selectedCategory Text Cada vez que se recibe una elección, esta salida contiene la categoría que eligió el usuario.

Añade una instrucción a la descripción del tema para que la capa de orquestación sepa qué significa una ejecución exitosa. Apóyate en la instrucción de nivel superior de Devuelve los resultados como salidas, no como mensajes al usuario, para que un modelo posterior compruebe esas salidas antes de volver a preguntar.

Mejores prácticas para los temas del arnés estándar

  • Dale al tema un nombre claro y específico y una descripción que indique cuándo usarlo (y, opcionalmente, qué hacer después de que se ejecute).
  • Añade una entrada para cada valor que necesite el tema y escribe la descripción de entrada como un prompt para la capa de orquestación.
  • Asigna nombres a las entradas en función del valor que contienen, ya que el nombre constituye la pregunta en caso de que la capa de orquestación tenga que hacérsela al usuario.
  • Mantén la lógica determinista y las barreras de seguridad, como entidades, validación y Power Fx, dentro del tema.
  • Evita enviar mensajes directos al usuario dentro del tema. Usa un nodo de mensaje, nodo de preguntas o tarjeta adaptativa solo cuando sea necesario.
  • Devuelve los resultados como salidas, incluyendo una salida en estado respondido.
  • Last updated on