Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
As variáveis existem em quatro níveis, ou escopos:
- Variáveis de tópico você só pode usar nos tópicos onde você as cria. Este escopo é o padrão para as variáveis que você cria.
- Variáveis globais você pode usar em todos os tópicos. Você pode alterar o escopo de qualquer variável de tópico para torná-la uma variável global.
- Variáveis do sistema que o Copilot Studio cria automaticamente para um agente. Eles fornecem informações mais contextuais sobre a conversa ou o usuário. Elas estão disponíveis em todos os tópicos.
- Variáveis de ambiente que você cria no Power Platform. Elas são somente leitura no Copilot Studio. Elas armazenam as chaves e os valores dos parâmetros, que poderão então servir como entrada para vários outros objetos do aplicativo, incluindo o Copilot Studio. Separar os parâmetros dos objetos de consumo permite alterar os valores dentro do mesmo ambiente ou ao migrar soluções para outros ambientes. A alternativa é deixar valores de parâmetros codificados nos componentes que os usam.
Tipos de variáveis
Cada variável tem um tipo base. O tipo base determina quais valores a variável podem armazenar e quais operadores que você pode usar ao criar uma expressão lógica com ela.
| Tipo | Descrição |
|---|---|
| Cadeia de caracteres | Uma sequência de caracteres usada para representar texto |
| Booliano | Um valor lógico que só pode ser true ou false |
| Número | Qualquer número real |
| Tabela | Uma lista de valores, mas todos os valores devem ser do mesmo tipo |
| Registro | Uma coleção de pares nome-valor em que os valores podem ser de qualquer tipo |
| DateTime | Uma data, hora, dia da semana ou mês em relação a um ponto no tempo |
| Opção | Uma lista de valores de cadeia de caracteres com sinônimos associados |
| Em branco | Um espaço reservado para "sem valor" ou "valor desconhecido"; para obter mais informações, consulte Em branco na documentação do Power Fx |
Você define o tipo de uma variável na primeira vez que atribui um valor a ela. Depois disso, o tipo é fixo e você não pode atribuir valores de nenhum outro tipo. Por exemplo, se você atribuir o valor inicial 1 a uma variável, defina seu tipo como Número. Se você tentar atribuir um valor de Cadeia de caracteres como "apples", receberá um erro.
Quando você testa um agente, uma variável pode aparecer temporariamente com o tipo desconhecido. Uma variável desconhecida ainda não tem um valor.
A ordem das variáveis é determinada de cima para baixo do tela de criação. Os nós na parte superior da tela de criação são considerados antes dos nós na parte inferior.
Quando você cria ramificações com nós Condição, as ramificações são ordenadas da esquerda para a direita. Os nós na ramificação mais à esquerda são considerados antes dos nós na ramificação mais à direita.
Entidades
O Copilot Studio usa entidades para identificar tipos específicos de informação das respostas de um usuário. As informações identificadas são salvas em uma variável do tipo apropriado para as informações. A tabela a seguir lista o tipo base de variável associado a entidades predefinidas.
| Entidade | Tipo base de variável |
|---|---|
| Opções de múltipla escolha | Opção |
| Resposta completa do usuário | Cadeia de caracteres |
| Idade | Número |
| Booliano | Booliano |
| Cidade | Cadeia de caracteres |
| Cor | Cadeia de caracteres |
| Continente | Cadeia de caracteres |
| País ou região | Cadeia de caracteres |
| Data e hora | DateTime |
| Cadeia de caracteres | |
| Evento | Cadeia de caracteres |
| Inteiro | Inteiro |
| Linguagem | Cadeia de caracteres |
| Quantia | Número |
| Número | Número |
| Ordinal | Número |
| Organização | Cadeia de caracteres |
| Porcentagem | Número |
| Nome da pessoa | Cadeia de caracteres |
| Número do telefone | Cadeia de caracteres |
| Ponto de interesse | Cadeia de caracteres |
| Velocidade | Número |
| Estado | Cadeia de caracteres |
| Endereço | Cadeia de caracteres |
| Temperatura | Número |
| URL | Cadeia de caracteres |
| Peso | Número |
| CEP | Cadeia de caracteres |
| Entidade personalizada | Opção |
Variáveis de ambiente
Variáveis de ambiente são um conceito do Power Platform. As variáveis de ambiente permitem o cenário básico de gerenciamento do ciclo de vida do aplicativo (ALM) de mover um aplicativo entre ambientes da Power Platform. Nesse cenário, o aplicativo permanece exatamente o mesmo, exceto por algumas referências externas importantes que são diferentes entre o ambiente de origem e o ambiente de destino.
Use as variáveis do ambiente da mesma forma que as variáveis de tópico, globais e do sistema. Uma diferença notável é que as variáveis de ambiente são somente leitura no Copilot Studio. Os criadores do agente não podem modificar variáveis de ambiente no Copilot Studio. No entanto, os administradores podem alterar o valor das variáveis de ambiente no Power Apps. Em Copilot Studio, você pode usar o painel Variáveis para ver informações sobre uma variável de ambiente. O painel de propriedades de variáveis também tem um link para o Power Apps, a experiência de criação para variáveis de ambiente.
A versão publicada de um agente que usa variáveis de ambiente tem os valores definidos para essas variáveis quando você publica o agente. Sempre que um administrador atualizar variáveis de ambiente, você deverá republicar quaisquer agentes que usem essas variáveis para que as alterações sejam efetivas no runtime. No entanto, há uma exceção: você não precisa republicar seus agentes quando o valor de uma variável de ambiente do tipo segredo é alterado. Ao contrário de outras variáveis de ambiente, as variáveis secretas são recuperadas no runtime.
Os tipos de variável de ambiente no Copilot Studio são mapeados para tipos de dados do Power Apps da seguinte maneira:
| Tipo no Copilot Studio | Tipo no Power Apps |
|---|---|
| Número decimal | Número |
| JSON | Detecte o tipo a partir do valor. Caso não seja JSON=> Não especificado (erro de validação) |
| Texto | Cadeia de caracteres |
| Sim/Não | Booliano |
| Fonte de dados | Cadeia de caracteres |
| Segredo | Cadeia de caracteres |
Observação
Erros de variável de ambiente são visíveis no chat de teste e durante a publicação. No entanto, esses erros não são mostrados na lista Tópico porque não são variáveis de tópico.
Variáveis do sistema
Cada agente vem com variáveis de sistema internas que fornecem informações extras sobre uma conversa.
Observação
Para obter mais informações sobre variáveis agente habilitadas para voz, consulte Usar variáveis de voz.
O Copilot Studio não mostra todas as variáveis do sistema. Para acessar variáveis ocultas do sistema, use uma Fórmula do Power Fx.
Para usar variáveis do sistema em uma fórmula do Power Fx, adicione System. antes do nome da variável. Por exemplo, para incluir a variável do sistema User.DisplayName em uma fórmula, consulte-a como System.User.DisplayName.
| Nome | Digitar | Definição |
|---|---|---|
| Activity.Attachments | tabela | Os anexos de arquivo que o usuário fornece. |
| Activity.Channel | opção | O ID do canal da conversa atual. |
| Activity.ChannelData | qualquer | Um objeto que contém conteúdo específico do canal. |
| Activity.ChannelId | cadeia | O ID do canal da conversa atual, como uma cadeia de caracteres. |
| Activity.From.Id | cadeia | ID exclusivo específico do canal para o remetente. |
| Activity.From.Name | cadeia | Nome amigável do usuário específico do canal do remetente. |
| Activity.Name | cadeia | O nome do evento. |
| Activity.Recipient.Id | cadeia | A propriedade Tipo de atividade de entrada. |
| Activity.Recipient.Name | cadeia | Representa o nome para exibição do agente no canal. No contexto do canal de telefonia, o valor dessa variável é o número de telefone ao qual o agente está anexado. |
| Activity.Text | cadeia | A mensagem mais recente enviada pelo usuário. |
| Activity.Type | opção | Tipo de atividade. |
| Activity.TypeId | cadeia | Tipo de atividade, como uma cadeia de caracteres. |
| Activity.Value | qualquer | Valor em aberto. |
| Bot.EnvironmentId | cadeia | A ID do ambiente do agente. |
| Bot.Id | cadeia | A ID do agente. |
| Bot.Name | cadeia | O nome do seu agente. |
| Bot.SchemaName | cadeia | O nome do esquema do agente. |
| Bot.TenantId | cadeia | A ID de locatário do agente. |
| ClientPluginActions | opção | Coleção de Ações de Plug-in de Cliente Dinâmico a serem consideradas para orquestração generativa. |
| Conversation.Id | cadeia | O ID exclusivo da conversa atual. |
| Conversation.InTestMode | Booliano | Sinalizador booliano que representa se a conversa está acontecendo na tela de teste. |
| Conversation.LocalTimeZone | cadeia | Nome do fuso horário a ser usado pelo usuário no formato de banco de dados de Fuso Horário IANA. |
| Conversation.LocalTimeZoneOffset | datetime | O deslocamento de hora de UTC para o fuso horário local atual. |
| Error.Code | cadeia | O código de erro para o erro atual. A mensagem de erro definida para o erro atual. |
| Error.Message | cadeia | A mensagem de erro definida para o erro atual. Observação: essa variável só é compatível se o gatilho for On Error. |
| FallbackCount | número | Essa variável conta as vezes em que um tópico não pôde ser correspondida à entrada do usuário. Observação: essa variável só é compatível se o gatilho for On Unknown Intent. |
| InactivityTimer.Continue | Booliano | Sinalizador booliano que representa se o temporizador precisa continuar. Observação: essa variável só é compatível se o gatilho for Inactivity. |
| InactivityTimer.Count | número | Número de vezes que o temporizador OnInactivity foi acionado devido à inatividade do usuário após o tempo configurado. Observação: essa variável só é compatível se o gatilho for Inactivity. |
| LastMessage.Id | cadeia | ID da mensagem anterior enviada pelo usuário. |
| LastMessage.Text | cadeia | A mensagem anterior enviada pelo usuário. |
| Recognizer.ExtractedEntities | opção | Representa as entidades extraídas da mensagem de disparo. Observação: essa variável só é compatível se o gatilho for On Select Intent. |
| Recognizer.IntentOptions | opção | Representa as opções de intenção quando o reconhecedor retorna resultados ambíguos. Observação: essa variável só é compatível se o gatilho for On Select Intent. |
| Recognizer.SelectedIntent | opção | Representa a intenção selecionada do reconhecedor. Observação: essa variável só é compatível se o gatilho for On Select Intent. |
| Recognizer.TriggeringMessage.Id | cadeia | A ID da mensagem do usuário que acionou o tópico atual. |
| Recognizer.TriggeringMessage.Text | cadeia | A mensagem do usuário que acionou o tópico atual. |
| Recognizer.MultipleTopicsMatchedReason | cadeia | Usado para determinar por que vários tópicos foram correspondidos. Observação: essa variável só é compatível se o gatilho for On Select Intent. |
| SignInReason | opção | Usado para determinar qual opção de entrada é necessária ao acionar o tópico. Observação: essa variável só é compatível se o gatilho for On Sign In. |
| User.Language | opção | Essa variável é usada para definir a localidade de idioma do usuário por conversa. |
Variáveis para autenticação integrada (padrão)
As variáveis a seguir estão disponíveis para agentes configurados para se autenticarem com a Microsoft. Essa configuração usa a autenticação do Microsoft Entra ID e é o padrão para novos agentes.
Para obter mais informações, consulte Variáveis de autenticação.
| Nome | Digitar | Definição |
|---|---|---|
| User.DisplayName | cadeia | O nome de exibição do usuário que está falando com o agente. |
| User.Email | cadeia | O endereço de e-mail do usuário que está falando com o agente. |
| User.FirstName | cadeia | O primeiro nome do usuário que está falando com o agente. |
| User.Id | cadeia | O ID exclusivo do usuário que está falando com o agente. |
| User.IsLoggedIn | Booliano | Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não. |
| User.LastName | cadeia | O nome da família do usuário que está falando com o agente. |
| User.PrincipalName | cadeia | O nome UPN do usuário que está falando atualmente com o agente. |
Variáveis para autenticação manual com OAuth 2 Genérico
As variáveis a seguir estão disponíveis para agentes configurados para usar o provedor de serviços para OAuth 2 Genérico.
| Nome | Digitar | Definição |
|---|---|---|
| User.AccessToken | cadeia | O token de acesso para o usuário autenticar com o agente. |
| User.DisplayName | cadeia | O nome de exibição do usuário que está falando com o agente. |
| User.Id | cadeia | O ID exclusivo do usuário que está falando com o agente. |
| User.IsLoggedIn | Booliano | Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não. |
Variáveis para autenticação manual com o Microsoft Entra ID
As variáveis a seguir estão disponíveis para agentes configurados para usar os provedores de serviço do Microsoft Entra ID (anteriormente Azure Active Directory).
| Nome | Digitar | Definição |
|---|---|---|
| User.AccessToken | cadeia | O token de acesso para o usuário autenticar com o agente. |
| User.DisplayName | cadeia | O nome de exibição do usuário que está falando com o agente. |
| User.Email | cadeia | O endereço de e-mail do usuário que está falando com o agente. |
| User.FirstName | cadeia | O primeiro nome do usuário que está falando com o agente. |
| User.Id | cadeia | O ID exclusivo do usuário que está falando com o agente. |
| User.IsLoggedIn | Booliano | Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não. |
| User.LastName | cadeia | O nome da família do usuário que está falando com o agente. |
| User.PrincipalName | cadeia | O nome da entidade de segurança do usuário que está falando com o agente. |
Variáveis para agentes habilitados para voz
As variáveis a seguir estão disponíveis apenas em agentes habilitados para voz.
Observação
Para obter mais informações sobre variáveis agente habilitadas para voz, consulte Usar variáveis de voz.
| Nome | Digitar | Definição |
|---|---|---|
| Activity.InputDTMFKeys | cadeia | O valor bruto da chave DTMF da telefonia. |
| Activity.SpeechRecognition.Confidence | número | A pontuação de confiança para o resultado inteiro da hipótese de Recuperação de Site do Azure, 0 a 1. |
| Activity.SpeechRecognition.MinimallyFormattedText | cadeia | Texto ligeiramente formatado do resultado da hipótese de Recuperação de Site do Azure. Por exemplo, "Quinhentos dólares". As palavras são soletradas, mas maiúsculas básicas e pontuação são incluídas. |
| Activity.UserInputType | opção | O tipo da entrada mais recente do usuário do agente. O valor pode ser teste, fala ou DTMF. |
| Conversation.OnlyAllowDTMF | Booliano | Sinalizador booliano que representa se o IVR deve ser definido para o modo somente DTMF no tempo de execução. |
| Conversation.SipUuiHeaderValue | cadeia | A cadeia de caracteres de cabeçalho UUI usada para passar o contexto para o IVR no início da chamada. |