Visão geral das variáveis

Note

Os recursos deste artigo são viabilizados pelo standard harness, que usa as opções de cobrança descritas em Licenciamento para agentes viabilizados pelo standard harness. Aprenda como acessar recursos padrão em agentes e fluxos de agentes padrão do Access.

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. 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. Ao separar os parâmetros dos objetos consumidores, você pode 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 Description
String Uma sequência de caracteres usada para representar texto
booleano Um valor lógico que só pode ser true ou false
Number Qualquer número real
Table 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
Data e hora 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 marcador para "sem valor" ou "valor desconhecido"; saiba mais em Blank 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 de variáveis é determinada de cima para baixo na tela de criação. O agente considera nós na parte superior da tela de criação antes dos nós na parte inferior.

Quando você cria ramificações usando nós Condição, o Copilot Studio ordena as ramificações da esquerda para a direita. O agente considera os nós do ramo mais à esquerda antes dos nós do ramo mais à direita.

Entities

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 String
Idade Number
booleano booleano
City String
Cor String
Continent String
País ou região String
Data e hora Data e hora
Email String
Event String
Número inteiro Número inteiro
Linguagem String
Dinheiro Number
Number Number
Ordinal Number
Organização String
Porcentagem Number
Nome da pessoa String
Número de telefone String
Ponto de interesse String
Velocidade Number
State String
Endereço String
Temperatura Number
URL String
Peso Number
CEP String
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, a aplicação permanece exatamente a mesma, exceto por algumas referências externas importantes que diferem entre o ambiente de origem e o ambiente de destino.

Use variáveis de ambiente da mesma forma que variáveis de tópico, globais e de sistema. A principal diferença é que, no Copilot Studio, as variáveis de ambiente são somente leitura. 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 inclui os valores que você define para essas variáveis ao publicar o agente. Sempre que um administrador atualiza variáveis de ambiente, você deve republicar quaisquer agentes que usem essas variáveis para que as mudanças entrem em vigor em tempo de execução. 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 Number
JSON Detecte o tipo a partir do valor. Caso não seja JSON=> Não especificado (erro de validação)
Texto String
Sim/Não booleano
Fonte de dados String
Segredo String

Note

Você vê erros nas variáveis de ambiente no chat de teste e ao publicar. No entanto, esses erros não aparecem na lista de Tópicos porque variáveis de ambiente não são variáveis de tópico.

Variáveis do sistema

Cada agente inclui variáveis de sistema integradas que fornecem informações extras sobre uma conversa.

Captura de tela das variáveis do sistema em um tópico.

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 Tipo Definition
Atividade.Anexos 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 específico do canal do usuário 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 de 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.
Atividade.Texto cadeia A mensagem mais recente enviada pelo usuário.
Tipo de Atividade opção Tipo de atividade.
Activity.TypeId cadeia Tipo de atividade, como uma cadeia de caracteres.
Activity.Value qualquer Valor indeterminado.
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 booleano 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 para o erro atual.
Erro.Mensagem cadeia A mensagem de erro 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 booleano 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. Saiba mais em Gatilho de inatividade.
LastMessage.Id cadeia ID da mensagem anterior enviada pelo usuário.
ÚltimaMensagem.Texto cadeia A mensagem anterior enviada pelo usuário.
Recognizer.ExtractedEntities opção Representa as entidades extraídas da mensagem disparadora.
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.
Motivo de Login 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.
Usuário.Idioma opção Essa variável é usada para definir a localidade de idioma do usuário por conversa.

Variáveis para agentes habilitados para voz

As variáveis a seguir estão disponíveis apenas em agentes habilitados para voz. Saiba mais em Use voice variables.

Nome Tipo Definition
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 completo da hipótese de reconhecimento automático de fala, de 0 a 1.
Activity.SpeechRecognition.MinimallyFormattedText cadeia Texto ligeiramente formatado do resultado da hipótese do reconhecimento automático de voz. Por exemplo, "Quinhentos dólares." As palavras são escritas por extenso, mas a capitalização básica e a 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 booleano 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.

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. Saiba mais em Variáveis de Autenticação.

Nome Tipo Definition
Usuário.NomeDeExibição cadeia O nome de exibição do usuário que está falando com o agente.
Usuário.Email cadeia O endereço de e-mail do usuário que está falando com o agente.
Usuário.PrimeiroNome cadeia O primeiro nome do usuário que está falando com o agente.
Id do Usuário cadeia O ID exclusivo do usuário que está falando com o agente.
Usuário.EstáLogado booleano Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não.
Sobrenome do Usuário 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 Genérico OAuth 2.

Nome Tipo Definition
User.AccessToken cadeia O token de acesso para o usuário se autenticar com o agente.
Usuário.NomeDeExibição cadeia O nome de exibição do usuário que está falando com o agente.
Id do Usuário cadeia O ID exclusivo do usuário que está falando com o agente.
Usuário.EstáLogado booleano 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 Tipo Definition
User.AccessToken cadeia O token de acesso para o usuário se autenticar com o agente.
Usuário.NomeDeExibição cadeia O nome de exibição do usuário que está falando com o agente.
Usuário.Email cadeia O endereço de e-mail do usuário que está falando com o agente.
Usuário.PrimeiroNome cadeia O primeiro nome do usuário que está falando com o agente.
Id do Usuário cadeia O ID exclusivo do usuário que está falando com o agente.
Usuário.EstáLogado booleano Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não.
Sobrenome do Usuário cadeia O nome da família do usuário que está falando com o agente.
User.PrincipalName cadeia O nome principal do usuário que está falando com o agente.
  • Last updated on