Panoramica delle variabili

Note

Le funzionalità in questo articolo sono alimentate dallo standard harness, che utilizza le opzioni di fatturazione descritte in Licensing per gli agenti alimentati dallo standard harness. Impara come accedere alle funzionalità standard negli agenti standard Access e nei flussi degli agenti.

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 è lasciare i valori dei parametri hardcoded all'interno dei componenti che li usano.

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 Descrizione
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 al fondo della tela di autoria. L'agente considera i nodi in cima alla canvas di authoring prima di quelli in basso.

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
Numero intero Numero intero
Lingua Stringa
Moneta Number
Number Number
Ordinale Number
Organizzazione 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
peso 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)
Testo Stringa
Sì/No Booleano
L'origine dei dati Stringa
Segreto 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.

Screenshot 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 Definizione
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 stringa L'ID canale della conversazione corrente, in formato stringa.
Attività.Da.Id stringa L'ID univoco specifico del canale del mittente.
Activity.From.Name stringa Il nome facilmente riconoscibile specifico del canale del mittente.
Activity.Name stringa Nome dell'evento.
Activity.Recipient.Id stringa Proprietà Tipo dell'attività entrante.
Activity.Recipient.Name stringa 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 stringa L'ultimo messaggio inviato dall'utente.
Activity.Type choice Tipo di impegno.
Activity.TypeId stringa Tipo di impegno, come stringa.
Activity.Value any Valore illimitato.
Bot.EnvironmentId stringa ID ambiente dell'agente.
Bot.ID stringa L'ID dell'agente.
Bot.Name stringa Il nome del tuo agente.
Bot.SchemaName stringa Il nome dello schema dell'agente.
Bot.TenantId stringa ID tenant dell'agente.
ClientPluginActions choice Raccolta di azioni di plug-in client dinamici da considerare per l'orchestrazione generativa.
Conversation.Id stringa 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 stringa 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 stringa Codice di errore per l'errore corrente
Il messaggio di errore per l'errore corrente.
Messaggio di Errore stringa 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 stringa L'ID del messaggio precedente inviato dall'utente.
LastMessage.Text stringa 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 stringa L'ID del messaggio dell'utente che ha attivato l'argomento corrente.
Recognizer.TriggeringMessage.Text stringa Il messaggio dell'utente che ha attivato l'argomento corrente.
Recognizer.MotivoCorrispondenzaMultiplaArgomenti stringa 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 Definizione
Attività.InputDTMFKeys stringa Il valore grezzo del tasto DTMF proveniente dalla telefonia.
Activity.SpeechRecognition.Confidence Numero Il punteggio di fiducia per l'ipotesi del riconoscimento vocale automatico è risultato completo, 0 a 1.
Activity.SpeechRecognition.TestoMinimamenteFormattato stringa 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 stringa 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 Definizione
NomeVisualizzato.Utente stringa Il nome visualizzato dell'utente che sta attualmente parlando con l'agente.
Utente.Email stringa L'indirizzo e-mail dell'utente che sta parlando con il agente.
User.FirstName stringa Il nome di battesimo dell'utente che sta parlando con l'agente.
User.Id stringa 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 stringa Il cognome dell'utente che sta parlando con l'agente.
User.PrincipalName stringa 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 Definizione
User.AccessToken stringa Il token di accesso per l'utente che si autentica con l'agente.
NomeVisualizzato.Utente stringa Il nome visualizzato dell'utente che sta attualmente parlando con l'agente.
User.Id stringa 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 Definizione
User.AccessToken stringa Il token di accesso per l'utente che si autentica con l'agente.
NomeVisualizzato.Utente stringa Il nome visualizzato dell'utente che sta attualmente parlando con l'agente.
Utente.Email stringa L'indirizzo e-mail dell'utente che sta parlando con il agente.
User.FirstName stringa Il nome di battesimo dell'utente che sta parlando con l'agente.
User.Id stringa 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 stringa Il cognome dell'utente che sta parlando con l'agente.
User.PrincipalName stringa Il cognome dell'utente che sta parlando con l'agente.
  • Last updated on