Panoramica delle variabili

Note

Questo articolo descrive le caratteristiche utilizzate negli agenti o nei flussi di agenti alimentati dall'imbracatura standard.

Le variabili esistono a quattro livelli, o ambiti:

  • Variabili di argomento che è possibile usare solo negli argomenti in cui vengono create. Questo è l'ambito predefinito per le variabili create.
  • Variabili globali che puoi utilizzare in tutti gli argomenti. Puoi modificare l'ambito di una variabile di argomento per renderla una variabile globale.
  • Variabili di sistema che Copilot Studio crea automaticamente per un agente. Forniscono informazioni più contestuali sulla conversazione o sull'utente. Sono disponibili in tutti gli argomenti.
  • Variabili di ambiente che crei in Power Platform. Sono di sola lettura in Copilot Studio. Archiviano le chiavi e i valori dei parametri, che serviranno poi come input per vari altri oggetti dell'applicazione, tra cui Copilot Studio. Separando i parametri dagli oggetti che consumano, puoi cambiare i valori all'interno dello stesso ambiente o quando migri soluzioni in altri ambienti. L'alternativa consiste nel lasciare i valori dei parametri codificati in modo statico nei componenti che li utilizzano.

Tipi di variabile

Ogni variabile ha un tipo di base. Il tipo determina quali valori la variabile può contenere e gli operatori che puoi utilizzare quando crei un'espressione logica con ess.

Tipo Description
Stringa Una sequenza di caratteri utilizzata per rappresentare il testo
Booleano Un valore logico che può essere solo true o false
Number Qualsiasi numero reale
Tabella Un elenco di valori, ma tutti i valori devono essere dello stesso tipo
Registra Una raccolta di coppie nome-valore in cui i valori possono essere di qualsiasi tipo
DateTime Una data, un'ora, un giorno della settimana o un mese relativi a un punto nel tempo
Scelta Un elenco di valori stringa con sinonimi associati
Vuoto Un segnaposto per "nessun valore" o "valore sconosciuto"; scopri di più in Blank nella documentazione Power Fx

Il tipo di variabile viene impostato la prima volta che le assegni un valore. Dopodiché, il tipo è fisso e non è possibile assegnare valori di nessun altro tipo. Ad esempio, se assegni il valore iniziale 1 a una variabile, impostane il tipo su Numero. Se quindi tenti di assegnare un valore Stringa come "apples", viene visualizzato un errore.

Quando testi un agente, è possibile che venga visualizzata temporaneamente una variabile con il tipo sconosciuto. Una variabile sconosciuta non ha ancora un valore.

L'ordine delle variabili è determinato dall'alto verso il basso dell'area di progettazione. L'agente prende in considerazione i nodi nella parte superiore dell'area di creazione prima di quelli nella parte inferiore.

Quando crei i branch usando nodi Condition, Copilot Studio ordina i branch da sinistra a destra. L'agente considera i nodi nel ramo più a sinistra prima dei nodi nel ramo più a destra.

Entities

Copilot Studio usa le entità per identificare tipi specifici di informazioni dalle risposte di un utente. Le informazioni identificate vengono salvate in una variabile del tipo appropriato per le informazioni. Nella tabella seguente è elencato il tipo di base della variabile associato alle entità predefinite.

Entità Tipo di base della variabile
Opzioni scelta multipla Scelta
Risposta completa dell'utente Stringa
Età Number
Booleano Booleano
Città Stringa
Colore Stringa
Continent Stringa
Paese o area geografica Stringa
Data e ora DateTime
Email Stringa
Event Stringa
Intero Intero
Language Stringa
Moneta Number
Number Number
Ordinale Number
Azienda Stringa
Percentuale Number
Nome della persona Stringa
Numero di telefono Stringa
Punto d'interesse Stringa
Velocità Number
State Stringa
Indirizzo stradale Stringa
Temperatura Number
URL Stringa
Weight Number
CAP Stringa
Entità personalizzata Scelta

Variabili di ambiente

Le variabili di ambiente sono un concetto di Power Platform. Le variabili di ambiente abilitano lo scenario ALM (Application Lifecycle Management) di base per lo spostamento di un'applicazione tra ambienti Power Platform. In questo scenario, l'applicazione rimane esattamente la stessa, tranne che per alcuni riferimenti esterni chiave che differiscono tra l'ambiente di origine e quello di destinazione.

Usa le variabili ambientali allo stesso modo delle variabili tematiche, globali e di sistema. Una differenza notevole è che le variabili di ambiente sono di sola lettura in Copilot Studio. Gli autori degli agenti non possono modificare le variabili di ambiente in Copilot Studio. Tuttavia, gli amministratori possono modificare il valore delle variabili di ambiente in Power Apps. In Copilot Studio, puoi utilizzare il pannello Variabili per visualizzare le informazioni su una variabile di ambiente. Il Pannello proprietà variabile include anche un collegamento a Power Apps, l'esperienza di creazione per le variabili di ambiente.

La versione pubblicata di un agente che utilizza variabili di ambiente include i valori che imposti per queste variabili quando pubblichi l'agente. Ogni volta che un amministratore aggiorna le variabili dell'ambiente, devi ripubblicare eventuali agenti che utilizzano queste variabili affinché le modifiche abbiano effetto a runtime. Tuttavia, c'è un'eccezione: non è necessario ripubblicare gli agenti quando cambia il valore di una variabile di ambiente di tipo secret. A differenza di altre variabili d'ambiente, le variabili segrete vengono recuperate in fase di esecuzione.

I tipi di variabili di ambiente in Copilot Studio si associano ai tipi di dati Power Apps come indicato di seguito:

Tipo in Copilot Studio Tipo in Power Apps
Numero decimale Number
JSON Rileva il tipo dal valore. Se non è JSON => Non specificato (errore di convalida)
Text Stringa
Sì/No Booleano
L'origine dei dati Stringa
Secret Stringa

Note

Vedi errori nelle variabili di ambiente nella chat di test e durante la pubblicazione. Tuttavia, questi errori non compaiono nella lista degli argomenti perché le variabili di ambiente non sono variabili di argomento.

Variabili di sistema

Ogni agente include variabili di sistema integrate che forniscono informazioni extra su una conversazione.

Schermata delle variabili di sistema in un argomento.

Copilot Studio non mostra tutte le variabili di sistema. Per accedere alle variabili di sistema nascoste, usa la formula formula Power Fx.

Per utilizzare le variabili di sistema in una formula Power Fx, aggiungi System. prima del nome della variabile. Ad esempio, per includere la variabile di sistema User.DisplayName in una formula, fai riferimento ad essa come System.User.DisplayName.

Name Tipo Definition
AllegatiAttività table I file allegati forniti dall'utente.
Activity.Channel choice L'ID canale della conversazione corrente.
Activity.ChannelData any Un oggetto che contiene contenuto specifico del canale.
Activity.ChannelId string L'ID canale della conversazione corrente, in formato stringa.
Attività.Da.Id string L'ID univoco specifico del canale del mittente.
Activity.From.Name string Il nome facilmente riconoscibile specifico del canale del mittente.
Activity.Name string Nome dell'evento.
Activity.Recipient.Id string Proprietà Tipo dell'attività entrante.
Activity.Recipient.Name string Rappresenta il nome visualizzato per l'agente all'interno del canale. Nel contesto del canale telefonico, il valore di questa variabile è il numero di telefono a cui è associato l'agente.
Activity.Text string L'ultimo messaggio inviato dall'utente.
Activity.Type choice Tipo di impegno.
Activity.TypeId string Tipo di impegno, come stringa.
Activity.Value any Valore illimitato.
Bot.EnvironmentId string ID ambiente dell'agente.
Bot.ID string L'ID dell'agente.
Bot.Name string Il nome del tuo agente.
Bot.SchemaName string Il nome dello schema dell'agente.
Bot.TenantId string ID tenant dell'agente.
ClientPluginActions choice Raccolta di azioni di plug-in client dinamici da considerare per l'orchestrazione generativa.
Conversation.Id string L'ID univoco della conversazione corrente.
Conversation.InTestMode Booleano Flag booleana che indica se la conversazione si sta svolgendo nell'ambiente di test.
Conversation.LocalTimeZone string Nome del fuso orario che l'utente dovrà utilizzare nel formato del database fuso orario IANA.
Conversation.LocalTimeZoneOffset datetime Differenza temporale rispetto a UTC per il fuso orario locale corrente.
Error.Code string Codice di errore per l'errore corrente
Il messaggio di errore per l'errore corrente.
Messaggio di Errore string Il messaggio di errore per l'errore corrente.
Nota: questa variabile è supportata solo se il trigger è On Error.
FallbackCount Numero Questa variabile conta le volte in cui un argomento non è stato abbinato all'input dell'utente.
Nota: questa variabile è supportata solo se il trigger è On Unknown Intent.
InactivityTimer.Continue Booleano Flag booleano che indica se il timer deve essere continuato.
Nota: questa variabile è supportata solo se il trigger è Inactivity.
InactivityTimer.Count Numero Numero di volte in cui il timer OnInactivity è stato attivato a causa di inattività dell'utente dopo il tempo configurato.
Nota: questa variabile è supportata solo se il trigger è Inactivity. Per altre informazioni, vedere Trigger di inattività.
LastMessage.Id string L'ID del messaggio precedente inviato dall'utente.
LastMessage.Text string Il messaggio precedente inviato dall'utente.
Recognizer.ExtractedEntities choice Rappresenta le entità estratte dal messaggio di attivazione.
Nota: questa variabile è supportata solo se il trigger è On Select Intent.
Recognizer.IntentOptions choice Rappresenta le opzioni di finalità quando il sistema di riconoscimento restituisce risultati ambigui.
Nota: questa variabile è supportata solo se il trigger è On Select Intent.
Riconoscitore.IntentoSelezionato choice Rappresenta l'intenzione selezionata dal sistema di riconoscimento.
Nota: questa variabile è supportata solo se il trigger è On Select Intent.
Recognizer.TriggeringMessage.Id string L'ID del messaggio dell'utente che ha attivato l'argomento corrente.
Recognizer.TriggeringMessage.Text string Il messaggio dell'utente che ha attivato l'argomento corrente.
Recognizer.MotivoCorrispondenzaMultiplaArgomenti string Utilizzato per determinare il motivo per cui sono stati abbinati più argomenti.
Nota: questa variabile è supportata solo se il trigger è On Select Intent.
SignInReason choice Utilizzato per determinare quale opzione di accesso è necessaria quando si attiva l'argomento.
Nota: questa variabile è supportata solo se il trigger è On Sign In.
Lingua.Utente choice Questa variabile viene utilizzata per impostare la lingua locale dell'utente per ogni conversazione.

Variabili per gli agenti con comandi vocali

Le seguenti variabili sono disponibili solo per gli agenti con comandi vocali. Scopri di più in Usa le variabili vocali.

Name Tipo Definition
Attività.InputDTMFKeys string Il valore grezzo del tasto DTMF proveniente dalla telefonia.
Activity.SpeechRecognition.Confidence Numero Il punteggio di confidenza per l'ipotesi di riconoscimento vocale automatico dell'intero risultato, da 0 a 1.
Activity.SpeechRecognition.TestoMinimamenteFormattato string Testo leggermente formattato dell'ipotesi del riconoscimento vocale automatico risultato. Ad esempio, "Cinquecento dollari". Le parole sono scritte per esteso, ma sono incluse le maiuscole e la punteggiatura di base.
Activity.UserInputType choice Tipo dell’ultimo input dell'utente agente. Il valore può essere test, comando vocale o DTMF.
Conversation.OnlyAllowDTMF Booleano Flag booleano che indica se l'IVR deve essere impostato sulla modalità esclusivamente DTMF durante l'esecuzione.
Conversation.SipUuiHeaderValue string Stringa dell'intestazione UUI utilizzata per passare il contesto all'IVR all'avvio della chiamata.

Variabili per l'autenticazione integrata (predefinita)

Le seguenti variabili sono disponibili per gli agenti configurati per l'autenticazione con Microsoft. Questa configurazione utilizza l'autenticazione Microsoft Entra ID ed è l'impostazione predefinita per i nuovi agenti. Scopri di più in Variabili di autenticazione.

Name Tipo Definition
NomeVisualizzato.Utente string Il nome visualizzato dell'utente che sta attualmente parlando con l'agente.
Utente.Email string L'indirizzo e-mail dell'utente che sta parlando con il agente.
User.FirstName string Il nome di battesimo dell'utente che sta parlando con l'agente.
User.Id string L'ID univoco dell'utente che sta attualmente parlando con l'agente.
User.IsLoggedIn Booleano Flag booleano che indica se l'utente che attualmente sta parlando con il agente è autenticato o meno.
User.LastName string Il cognome dell'utente che sta parlando con l'agente.
User.PrincipalName string Il nome principale utente della persona che sta attualmente parlando con l'agente.

Variabili per l'autenticazione manuale con OAuth 2 generico

Le seguenti variabili sono disponibili per gli agenti configurati per utilizzare il provider di servizi Generic OAuth 2.

Name Tipo Definition
User.AccessToken string Il token di accesso per l'utente che si autentica con l'agente.
NomeVisualizzato.Utente string Il nome visualizzato dell'utente che sta attualmente parlando con l'agente.
User.Id string L'ID univoco dell'utente che sta attualmente parlando con l'agente.
User.IsLoggedIn Booleano Flag booleano che indica se l'utente che attualmente sta parlando con il agente è autenticato o meno.

Variabili per l'autenticazione manuale con Microsoft Entra ID

Le seguenti variabili sono disponibili per gli agenti configurati per utilizzare i provider di servizi Microsoft Entra ID (in precedenza Azure Active Directory).

Name Tipo Definition
User.AccessToken string Il token di accesso per l'utente che si autentica con l'agente.
NomeVisualizzato.Utente string Il nome visualizzato dell'utente che sta attualmente parlando con l'agente.
Utente.Email string L'indirizzo e-mail dell'utente che sta parlando con il agente.
User.FirstName string Il nome di battesimo dell'utente che sta parlando con l'agente.
User.Id string L'ID univoco dell'utente che sta attualmente parlando con l'agente.
User.IsLoggedIn Booleano Flag booleano che indica se l'utente che attualmente sta parlando con il agente è autenticato o meno.
User.LastName string Il cognome dell'utente che sta parlando con l'agente.
User.PrincipalName string Il cognome dell'utente che sta parlando con l'agente.
  • Last updated on