Información general de las variables
Las variables pueden existir en cuatro niveles, o ámbitos:
- Tema: las variables solo se pueden usar en los temas en los que se crean. Este es el ámbito predeterminado para las variables que crea.
- Las variables globales pueden utilizarse en todos los temas. Puede cambiar el alcance de una variable de tema para convertirla en una variable global.
- Las variables del sistema se crean automáticamente con su agente. Proporcionan más información contextual sobre la conversación o el usuario. Están disponibles en todos los temas.
- Las variables de entorno se crean en Power Platform y son de solo lectura en Copilot Studio. Almacenan las claves y los valores de los parámetros, que luego sirven de entrada a otros objetos de la aplicación, incluido Copilot Studio. Separar los parámetros de los objetos consumidores le permite cambiar los valores dentro del mismo entorno o cuando migra soluciones a otros entornos. La alternativa es dejar valores de parámetros codificados de forma rígida en los componentes que los utilizan.
Tipos de variables
Una variable está asociada a un tipo base. El tipo determina qué valores puede contener la variable y los operadores que puede usar al crear una expresión lógica con ella.
| Type | Description |
|---|---|
| String | Una secuencia de caracteres utilizados para representar texto |
| Booleana | Un valor lógico que sólo puede ser true o false |
| Number | Cualquier número real |
| Table | Una lista de valores, pero todos los valores deben ser del mismo tipo |
| Grabar | Una colección de pares de nombre y valor donde los valores pueden ser de cualquier tipo |
| Fecha y hora | Una fecha, hora, día de la semana o mes relativo a un punto en el tiempo |
| Opción | Una lista de valores de cadena con sinónimos asociados |
| En blanco | Un marcador de posición para "sin valor" o "valor desconocido"; para obtener más información, consulte Espacio en blanco en Power Fx |
El tipo de una variable se establece la primera vez que se le asigna un valor. Después, el tipo de esa variable es fijo y no se le pueden asignar valores de ningún otro tipo. Por ejemplo, a una variable dado el valor inicial de 1 se le asigna el tipo Número. Si se intenta asignarlo a un valor de Cadena de "apples" , se produce un error.
Cuando está probando un agente, una variable puede aparecer temporalmente como el tipo desconocido. A una variable desconocida aún no se le ha asignado un valor.
El orden de las variables se determina de arriba a abajo del lienzo de creación. Los nodos de la parte superior del lienzo de creación se consideran antes que los nodos de la parte inferior.
Cuando crea ramas con nodos de condición, las ramas se ordenan de izquierda a derecha. Los nodos de la rama situada más a la izquierda se consideran antes que los nodos de la rama situada más a la derecha.
Entidades
Copilot Studio usa entidades para identificar un tipo específico de información de las respuestas de un usuario. La información identificada se guarda en una variable del tipo apropiado para la información. En la tabla siguiente se muestra el tipo base de variable asociado a las entidades precompiladas.
| Entity | Tipo base de variable |
|---|---|
| Opciones de elección múltiple | Opción |
| Respuesta completa del usuario | String |
| Edad | Number |
| Booleana | Booleana |
| City | String |
| Color | String |
| Continente | String |
| País o región | String |
| Fecha y hora | Fecha y hora |
| String | |
| Evento | String |
| Número entero | Número entero |
| Lenguaje | String |
| Money | Number |
| Number | Number |
| Ordinal | Number |
| Organization | String |
| Porcentaje | Number |
| Nombre de la persona | String |
| N.º de teléfono | String |
| Punto de interés | String |
| Velocidad | Number |
| Valor | String |
| Dirección postal | String |
| Temperatura | Number |
| Dirección URL | String |
| Grosor | Number |
| Código postal | String |
| Entidad personalizada | Opción |
Variables de entorno
Las variables de entorno son un concepto de Power Platform. Las variables de entorno habilitan el escenario básico de administración del ciclo de vida de la aplicación (ALM) de mover una aplicación entre entornos de Power Platform. En este escenario, la aplicación se mantiene exactamente igual salvo por unas pocas referencias externas clave que son diferentes entre el entorno de origen y el de destino.
Utilice variables de entorno de la misma forma que las variables de Tema, Global y Sistema. Una diferencia notable es que las variables de entorno son de solo lectura en Copilot Studio. Los autores de agentes no pueden modificar variables de entorno en Copilot Studio. Sin embargo, los administradores pueden cambiar el valor de las variables de entorno en Power Apps. En Copilot Studio, puede utilizar el panel Variables para ver información sobre una variable de entorno. El panel Variables también tiene un vínculo a la experiencia de creación nativa.
La versión publicada de un agente que utiliza variables de entorno tiene los valores que se establecieron para estas variables cuando se publicó el agente. Cada vez que un administrador actualiza variables de entorno, debe volver a publicar los agentes que utilizan estas variables para que los cambios sean efectivos en tiempo de ejecución. Sin embargo, hay una excepción: no es necesario volver a publicar los agentes cuando cambia el valor de una variable de entorno de tipo secreto. A diferencia de otras variables de entorno, las variables secretas se recuperan en tiempo de ejecución.
Los tipos de variables de entorno en Copilot Studio se asignan a los tipos de datos de Power Apps del siguiente modo:
| Tipo en Copilot Studio | Tipo en Power Apps |
|---|---|
| Número decimal | Number |
| JSON | Detectar el tipo a partir del valor. Si no es JSON=> No especificado (error de validación) |
| Text | String |
| Sí/No | Booleana |
| Origen de datos | String |
| Secret | String |
Nota
Los errores de las variables de entorno son visibles en el chat de Prueba y al publicar. Sin embargo, estos errores no se muestran en la lista Tema porque no son variables de tema.
Variables del sistema
Cada agente viene con variables de sistema integradas que proporcionan información adicional sobre una conversación.
Nota
Para obtener más información sobre las variables agente habilitadas para voz, consulte Uso de variables de voz.
No todas las variables del sistema se muestran en la lista. Debe acceder a estas variables ocultas del sistema con una fórmula de Power Fx.
Para utilizar variables del sistema en una fórmula de Power Fx, debe agregar System. antes del nombre de variable. Por ejemplo, para incluir la variable del sistema User.DisplayName en una fórmula, haga referencia a ella como System.User.DisplayName.
| Nombre. | Type | Definición |
|---|---|---|
| Activity.Attachments | tabla | Los archivos adjuntos proporcionados por el usuario |
| Canal de actividades | opción | El ID de canal de la conversación actual |
| Activity.ChannelData | cualquiera | Un objeto que contiene contenido específico del canal |
| Activity.ChannelId | string | El ID de canal de la conversación actual, como cadena |
| Activity.From.Id | string | El ID único específico del canal para el remitente |
| Activity.From.Name | string | El nombre descriptivo del remitente específico del canal |
| Activity.Name | string | El nombre del evento |
| Activity.Recipient.Id | string | Tipo de propiedad de la actividad entrante. |
| Activity.Recipient.Name | string | Representa el nombre para mostrar del agente dentro del canal. En el contexto del canal de telefonía, el valor de esta variable será el número de teléfono al que está asociado el agente. |
| Activity.Text | string | El mensaje más reciente enviado por el usuario |
| Activity.Type | opción | Tipo de actividad |
| Activity.TypeId | string | Tipo de actividad, como una cadena |
| Activity.Value | cualquiera | Valor con extremo abierto |
| Bot.EnvironmentId | string | El Id. del entorno del agente |
| Bot.Id | string | Id. del agente |
| Bot.Name | string | El nombre del agente |
| Bot.SchemaName | string | El nombre del esquema del agente |
| Bot.TenantId | string | El id. de inquilino del agente |
| ClientPluginActions | opción | Colección de acciones de complemento de cliente dinámico que se deben tener en cuenta para la orquestación generativa |
| Conversation.Id | string | El id. exclusivo de la conversación actual |
| Conversation.InTestMode | Booleana | Indicador booleano que representa si la conversación está sucediendo en el lienzo de prueba |
| Conversation.LocalTimeZone | string | Nombre de la zona horaria que utilizará el usuario en el formato de la base de datos de zonas horarias de IANA |
| Conversation.LocalTimeZoneOffset | datetime | La diferencia horaria con respecto a UTC para la zona horaria local actual |
| Error.Code | string | El código del error actual. El mensaje de error del error actual. |
| Error.Message | string | El mensaje de error del error actual. Nota: Esta variable solo se admite si el desencadenador es On Error. |
| FallbackCount | número | Esta variable cuenta las veces que un tema no pudo coincidir con la entrada del usuario. Nota: Esta variable solo se admite si el desencadenador es On Unknown Intent. |
| InactivityTimer.Continue | Booleana | Bandera booleana que representa si el temporizador debe continuar. Nota: Esta variable solo se admite si el desencadenador es Inactivity. |
| InactivityTimer.Count | número | Número de veces que el temporizador OnInactivity se ha activado debido a la inactividad del usuario después del tiempo configurado. Nota: Esta variable solo se admite si el desencadenador es Inactivity. |
| LastMessage.Id | string | El id. del mensaje anterior enviado por el usuario |
| LastMessage.Text | string | El mensaje anterior enviado por el usuario |
| Recognizer.ExtractedEntities | opción | Representa las entidades extraídas del mensaje desencadenante. Nota: Esta variable solo se admite si el desencadenador es On Select Intent. |
| Recognizer.IntentOptions | opción | Representa las opciones de intención cuando el reconocedor devuelve resultados ambiguos. Nota: Esta variable solo se admite si el desencadenador es On Select Intent. |
| Recognizer.SelectedIntent | opción | Representa la intención seleccionada del reconocedor. Nota: Esta variable solo se admite si el desencadenador es On Select Intent. |
| Recognizer.TriggeringMessage.Id | string | El id. del mensaje de usuario que activó el tema actual |
| Recognizer.TriggeringMessage.Text | string | El mensaje de usuario que activó el tema actual |
| Recognizer.MultipleTopicsMatchedReason | string | Se utiliza para determinar por qué coincidieron varios temas. Nota: Esta variable solo se admite si el desencadenador es On Select Intent. |
| SignInReason | opción | Se utiliza para determinar qué opción de inicio de sesión se necesita cuando se activa tema. Nota: Esta variable solo se admite si el desencadenador es On Sign In. |
| User.Language | opción | Esta variable se utiliza para establecer la configuración regional del idioma del usuario por conversación. |
Variables para autenticación integrada (predeterminado)
Las siguientes variables están disponibles para agentes configurados para autenticarse con Microsoft. Esta configuración utiliza autenticación de Microsoft Entra ID y es la predeterminada para los nuevos agentes.
Para obtener más información, consulte Variables de autenticación.
| Nombre. | Type | Definición |
|---|---|---|
| User.DisplayName | string | El nombre para mostrar del usuario que está hablando actualmente con el agente. |
| User.Email | string | La dirección de correo electrónico del usuario que está hablando actualmente con el agente. |
| User.FirstName | string | El nombre de pila del usuario que está hablando actualmente con el agente. |
| User.Id | string | Id. único del usuario que está hablando actualmente con el agente. |
| User.IsLoggedIn | Booleana | Indicador booleano que representa si el usuario que está hablando actualmente con el agente está autenticado o no. |
| User.LastName | string | El nombre de familia del usuario que está hablando actualmente con el agente. |
| User.PrincipalName | string | El nombre principal de usuario del usuario que está hablando actualmente con el agente. |
Variables para autenticación manual con Genérico OAuth 2
Las siguientes variables están disponibles cuando ha configurado su agente para utilizar el proveedor de servicios Genérico OAuth 2.
| Nombre. | Type | Definición |
|---|---|---|
| User.AccessToken | string | El token de acceso del usuario que se autentica con el agente. |
| User.DisplayName | string | El nombre para mostrar del usuario que está hablando actualmente con el agente. |
| User.Id | string | Id. único del usuario que está hablando actualmente con el agente. |
| User.IsLoggedIn | Booleana | Indicador booleano que representa si el usuario que está hablando actualmente con el agente está autenticado o no. |
Variables para la autenticación manual con Microsoft Entra ID
Las siguientes variables están disponibles para agentes configurados para usar los proveedores de servicio de Microsoft Entra ID (anteriormente Azure Active Directory).
| Nombre. | Type | Definición |
|---|---|---|
| User.AccessToken | string | El token de acceso del usuario que se autentica con el agente. |
| User.DisplayName | string | El nombre para mostrar del usuario que está hablando actualmente con el agente. |
| User.Email | string | La dirección de correo electrónico del usuario que está hablando actualmente con el agente. |
| User.FirstName | string | El nombre de pila del usuario que está hablando actualmente con el agente. |
| User.Id | string | Id. único del usuario que está hablando actualmente con el agente. |
| User.IsLoggedIn | Booleana | Indicador booleano que representa si el usuario que está hablando actualmente con el agente está autenticado o no. |
| User.LastName | string | El nombre de familia del usuario que está hablando actualmente con el agente. |
| User.PrincipalName | string | El nombre principal del usuario que está hablando actualmente con el agente. |
Variables para agentes habilitados por voz
Las siguientes variables solo están disponibles en agentes habilitados para voz.
Nota
Para obtener más información sobre las variables agente habilitadas para voz, consulte Uso de variables de voz.
| Nombre. | Type | Definición |
|---|---|---|
| Activity.InputDTMFKeys | string | El valor de la clave DTMF sin procesar que se recibió desde la telefonía. |
| Activity.SpeechRecognition.Confidence | número | La puntuación de confianza para el resultado completo de la hipótesis del Azure Site Recovery, de 0 a 1. |
| Activity.SpeechRecognition.MinimallyFormattedText | string | Texto ligeramente formateado del resultado de la hipótesis de Azure Site Recovery. Por ejemplo, "quinientos dólares". Las palabras están escritas, pero se incluyen las mayúsculas y la puntuación básicas. |
| Activity.UserInputType | opción | El tipo de la entrada más reciente del usuario. El valor puede ser prueba, voz o DTMF. |
| Conversation.OnlyAllowDTMF | Booleana | Bandera booleana que representa si el IVR debe configurarse en modo solo DTMF en tiempo de ejecución. |
| Conversation.SipUuiHeaderValue | string | La cadena de encabezado UUI utilizada para pasar contexto a IVR al iniciar la llamada. |