Reutilización de variables en los temas

  • Artículo

Importante

Las capacidades y características de Power Virtual Agents son ahora parte de Microsoft Copilot Studio tras importantes inversiones en IA generativa e integraciones mejoradas en Microsoft Copilot.

Algunos artículos y capturas de pantalla pueden hacer referencia a Power Virtual Agents mientras actualizamos la documentación y el contenido de capacitación.

Variables almacena las respuestas de sus clientes a las preguntas de su copiloto. Por ejemplo, puede guardar el nombre de un cliente en una variable llamada UserName. El copiloto puede dirigirse al cliente por su nombre a lo largo de la conversación.

De forma predeterminada, el valor de una variable solo se puede usar en el tema donde se crea la variable. Sin embargo, es posible reutilizar el mismo valor en todos los temas. Por ejemplo, en un tema de Bienvenida, el bot solicita el nombre y el correo electrónico del cliente. En el tema Reserva de citas, desea que el copiloto recuerde lo que introdujo el cliente y no vuelva a preguntar.

Una forma de reutilizar una variable es pasar la variable entre temas. La otra forma es hacer que la variable tenga un alcance global, y eso es lo que cubre este artículo. Variables globales se llaman así porque están disponibles en todos los temas en todo el copiloto.

Las variables de Copilot se aplican durante una sola sesión de usuario. Debe especificar qué variables hay que tratar como variables de Copilot para distinguirlas de las variables de nivel de tema.

Creación de una variable global

Puede crear una variable global cambiando el alcance de una variable de tema.

  1. Crear una variable nueva o usar el panel de variables para abrir una variable existente.

  2. En el panel Propiedades de las variables, seleccione Global (cualquier tema puede acceder).

    Se agregará al nombre de la variable una cadena de prefijo Global. para diferenciarla de las variables de nivel de tema. Por ejemplo, ahora la variable UserName se muestra como Global.UserName.

    Captura de pantalla que muestra el panel Propiedades de variable, con la configuración Organización resaltada.

  3. Guarde el tema.

    El nombre de una variable global debe ser único en todos los temas. En caso de conflicto, deberá cambiar el nombre de la variable antes de guardar el tema.

Uso de variables globales

Cuando esté redactando un mensaje de copiloto en un nodo de Mensaje o en un nodo de Pregunta, seleccione el icon {x} para ver las variables disponibles para el tema. Las variables globales aprecedn en la pestaña Personalizado junto con cualquier variable tema. Las variables se enumeran en orden alfabético.

Captura de pantalla que muestra la selección de una variable global.

Buscar todos los temas mediante una variable global

Puede encontrar dónde se definió por primera vez y qué otros temas la están utilizando. Esto puede ser útil si está trabajando en un copiloto nuevo, o si tiene múltiples variables y una ramificación de temas compleja.

  1. Seleccione una variable global en el lienzo de creación o abra el panel Variables y seleccione una variable global.

  2. En el panel Propiedades de variables, en la sección Referencia, seleccione cualquiera de los temas donde se usa la variable para ir directo a ese tema y nodo.

    Captura de pantalla que muestra la lista de temas utilizados por una variable en el panel Propiedades de variable.

Ciclo de vida de las variables globales

De forma predeterminada, el valor de una variable global persiste hasta que finaliza la sesión. El nodo Borrar valores de variables restablece los valores de las variables globales y se utiliza en el sistema Restablecer conversación tema. Ese tema puede activarse mediante la redirección o cuando el usuario escribe una frase desencadenante como "Comenzar de nuevo". En ese caso, todas las variables globales se restablecen.

Establecer el valor de una variable global desde orígenes externos

Si desea asegurarse de que el copiloto inicie una conversación con algún contexto, puede inicializar una variable global con una fuente externa. Digamos que su sitio requiere que los usuarios inicien sesión. Dado que su copiloto ya conoce el nombre de un usuario, puede saludar a los clientes por su nombre antes de que comiencen a escribir su primera pregunta.

  1. Seleccione un avariable global.

  2. En el panel Propiedades de variable, seleccione Las fuentes externas pueden establecer valores.

Establecer variables globales en un copiloto integrado

Si está incrustando su copiloto en una página web simple, puede agregar variables y sus definiciones a la URL del copiloto. O, si desea tener un poco más de control, puede usar un bloque de código <script> para llamar y usar variables programáticamente.

El nombre de la variable en la cadena de consulta de la URL debe coincidir con el nombre de la variable global, sin el prefijo Global.. Por ejemplo, una variable global Global.UserName se denominaría UserName en la consulta.

Los ejemplos siguientes hacen una declaración sencilla para las variables. En un escenario de producción, puede pasar como parámetro de consulta o definición de variable otra variable que ya ha almacenado el nombre del usuario (por ejemplo, si tiene el nombre de usuario de un script de inicio de sesión).

Anexe las variables y sus definiciones a la URL del copiloto como parámetros de cadena de consulta (con el formato botURL?variableName1=variableDefinition1&variableName2=variableDefinition2).

Por ejemplo:

En el nombre de parámetro no se distinguen mayúsculas de minúsculas. Esto significa que username=Renata también funcionará en este ejemplo.

Agregar la variable a un lienzo personalizado

También puede agregar la variable a un lienzo personalizado.

  1. En la sección <script> de la página en la que está el copiloto, defina las variables de la siguiente manera, sustituyendo variableName1 por el nombre de la variable sin el prefijo Global. y variableDefinition1 por la definición. Separe múltiples variables con comas (,).

       const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
     if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
       dispatch({
          type: "WEB_CHAT/SEND_EVENT",
          payload: {
            name: "pvaSetContext",
            value: {
               "variableName1": "variableDefinition1",
               "variableName2": "variableDefinition2"
            }
          },
        });
      }
        return next(action);
    });

  2. En la sección <script>, llame a store al insertar el copiloto, como en el siguiente ejemplo en el que se llama a store justo encima de donde se llama a styleOptions (debe reemplazar BOT_ID por su identificación):

    const BOT_ID = "12345-5678";
const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;

fetch(theURL)
    .then(response => response.json())
    .then(conversationInfo => {
        window.WebChat.renderWebChat(
            {
                directLine: window.WebChat.createDirectLine({
                    token: conversationInfo.token,
                }),
                store,
                styleOptions
            },
            document.getElementById('webchat')
        );
    })
    .catch(err => console.error("An error occurred: " + err));