Übersicht über Variablen

Note

Die Funktionen in diesem Artikel basieren auf dem Standard-Harness, das die in Lizenzierung für Agenten mit Standard-Harness beschriebenen Abrechnungsoptionen verwendet. Erfahren Sie, wie Sie auf Standardfunktionen in Zugriff auf Standard-Agenten und Agentenflüsse zugreifen.

Variablen existieren auf vier Ebenen oder Bereichen:

• Themenvariablen, die Sie nur in den Themen verwenden können, in denen Sie sie erstellen. Dieser Bereich ist der Standardbereich für Variablen, die Sie erstellen.
• Globale Variablen, die Sie in allen Themen verwenden können. Sie können den Bereich einer Thema-Variable ändern, um sie zu einer globalen Variablen zu machen.
• Systemvariablen, die Copilot Studio automatisch für einen Agent erstellt. Sie bieten mehr kontextbezogene Informationen über die Unterhaltung oder den Benutzer. Sie sind in allen Themen verfügbar.
• Umgebungsvariablen, die Sie in Power Platform erstellen. Sie sind in Copilot Studio als Nur-Lesen markiert. Sie speichern die Parameterschlüssel und -werte, die dann als Eingabe für verschiedene andere Anwendungsobjekte dienen können, einschließlich Copilot Studio. Indem man die Parameter von den verbrauchenden Objekten trennt, kann man die Werte innerhalb derselben Umgebung oder beim Migrationsprozess von Lösungen in andere Umgebungen ändern. Die Alternative besteht darin, festcodierte Parameterwerte in den Komponenten zu belassen, die sie verwenden.

Variablentypen

Jede Variable hat einen Basistyp. Der Typ bestimmt, welche Werte die Variable annehmen kann und welche Operatoren Sie verwenden können, wenn Sie damit einen logischen Ausdruck bilden.

Typ	Description
String	Eine Folge von Zeichen zur Darstellung von Text
Boolean	Ein logischer Wert, der nur true oder false sein kann
Nummer	Eine beliebige reelle Zahl
Table	Eine Liste mit Werten, aber alle Werte müssen vom gleichen Typ sein
Aufzeichnung	Eine Sammlung von Name-Wert-Paaren, bei denen Werte beliebigen Typs sein können
Datum/Uhrzeit	Ein Datum, eine Uhrzeit, ein Wochentag oder ein Monat relativ zu einem Zeitpunkt
Auswahl	Eine Liste von Zeichenfolgenwerten mit zugehörigen Synonymen
Leer	Ein Platzhalter für "keinen Wert" oder "unbekannten Wert"; mehr erfahren Sie in Blank in der Power Fx-Dokumentation

Sie legen den Typ einer Variablen fest, wenn Sie ihr zum ersten Mal einen Wert zuweisen. Danach ist der Typ festgelegt, und Sie können keine Werte anderen Typs zuweisen. Wenn Sie beispielsweise den Anfangswert 1 einer Variablen zuweisen, legen Sie dessen Typ auf Zahl fest. Wenn Sie dann versuchen, einen Zeichenfolge-Wert wie "apples" zuzuweisen, wird eine Fehlermeldung angezeigt.

Wenn Sie einen Agent testen, wird möglicherweise vorübergehend eine Variable mit dem Typ Unbekannt angezeigt. Eine unbekannte Variable hat noch keinen Wert.

Die Reihenfolge der Variablen wird von oben nach unten auf der Autorenleinwand bestimmt. Der Agent berücksichtigt Knoten oben im Authoring-Canvas vor Knoten unten im Authoring-Canvas.

Wenn du Zweige mit Condition-Knoten erstellst, ordnet Copilot Studio die Zweige von links nach rechts. Der Agent betrachtet Knoten im linkesten Zweig vor Knoten im rechten Zweig.

Entitäten

Web-App

Copilot Studio verwendet Entitäten, um bestimmte Arten von Informationen aus den Antworten eines Benutzers zu identifizieren. Die identifizierten Informationen werden in einer Variablen des Typs gespeichert, der den Informationen entspricht. In der folgenden Tabelle ist der Basistyp der Variablen aufgeführt, die vordefinierten Entitäten zugeordnet sind.

Objekt	Variablen-Basistyp
Mehrfachauswahl-Optionen	Auswahl
Die gesamte Antwort des Benutzers	String
Alter	Nummer
Boolean	Boolean
Stadt	String
Farbe	String
Continent	String
Land oder Region	String
Datum und Uhrzeit	Datum/Uhrzeit
E-Mail	String
Event	String
Integer	Integer
Sprache	String
Geld	Nummer
Nummer	Nummer
Ordinalzahl	Nummer
Organisation	String
Prozentsatz	Nummer
Name der Person	String
Rufnummer	String
Interessanter Ort	String
Speed	Nummer
State	String
Straßenadresse	String
Temperatur	Nummer
URL	String
Gewicht	Nummer
Postleitzahl	String
Benutzerdefinierte Entität	Auswahl

Teamplan

Copilot Studio verwendet Entitäten, um bestimmte Arten von Informationen aus den Antworten eines Benutzers zu identifizieren. Die identifizierten Informationen werden in einer Variablen des Typs gespeichert, der den Informationen entspricht.

In der folgenden Tabelle ist der Variablen-Basistyp aufgeführt, der jeder vordefinierten Entität zugeordnet ist. Der Basistyp bestimmt die Operatoren, die Sie verwenden können, wenn Sie einen logischen Ausdruck mit der entsprechenden Variablen erstellen. Es bestimmt auch, ob Sie eine Variable in einen Flow oder eine Bot Framework Fertigkeit als Eingabeparameter einspeisen können.

Zum Beispiel wird ein boolescher Basistyp einem „gleich“-Operator zugeordnet, wobei die möglichen Werte „Wahr“ oder „Falsch“ sein können. Ein Zahlenbasistyp liefert numerische Operatoren wie "ist gleich mit", "ist größer als", "ist größer als oder gleich mit" und so weiter.

Objekt	Variablen-Basistyp
Multiple-Choice-Optionen	String
Die gesamte Antwort des Benutzers	String
Alter	Nummer
Boolean	Boolean
Stadt	String
Farbe	String
Continent	String
Land oder Region	String
Datum und Uhrzeit	String
Dauer	String
E-Mail	String
Event	String
Sprache	String
Geld	String
Nummer	String
Ordinalzahl	String
Organisation	String
Prozentsatz	Nummer
Name der Person	String
Rufnummer	String
Interessanter Ort	String
Speed	Nummer
State	String
Straßenadresse	String
Temperatur	Nummer
URL	String
Gewicht	Nummer
Postleitzahl	String
Benutzerdefinierte Entität	String

Umgebungsvariablen

Umgebungsvariablen sind ein Power Platform-Konzept. Umgebungsvariablen ermöglichen das grundlegende Szenario der Lebenszyklusverwaltung von Anwendungen (Application Lifecycle Management, ALM) zum Verschieben einer Anwendung zwischen Power Platform-Umgebungen. In diesem Szenario bleibt die Anwendung exakt gleich, abgesehen von einigen wenigen wichtigen externen Referenzen, die sich zwischen Quellumgebung und Zielumgebung unterscheiden.

Verwenden Sie Umweltvariablen auf die gleiche Weise wie Topic-, Global- und Systemvariablen. Ein bemerkenswerter Unterschied besteht darin, dass Umgebungsvariablen in Copilot Studio schreibgeschützt sind. Agent-Erstellende können Umgebungsvariablen in Copilot Studio nicht ändern. Administrierende können jedoch den Wert von Umgebungsvariablen in Power Apps ändern. In Copilot Studio können Sie den Bereich Variablen verwenden, um Informationen zu einer Umgebungsvariablen anzuzeigen. Der Bereich Variableneigenschaften verfügt außerdem über einen Link zu Power Apps, der Erstellungsumgebung für Umgebungsvariablen.

Die veröffentlichte Version eines Agenten, die Umweltvariablen verwendet, enthält die Werte, die du für diese Variablen beim Veröffentlichen des Agenten festgelegt hast. Wann immer ein Administrator Umweltvariablen aktualisiert, müssen Sie alle Agenten, die diese Variablen verwenden, neu veröffentlichen, damit die Änderungen zur Laufzeit in Kraft treten. Es gibt jedoch eine Ausnahme: Sie müssen Ihre Agenten nicht erneut veröffentlichen, wenn sich der Wert einer Umgebungsvariablen vom Typ Geheimnis ändert. Im Gegensatz zu anderen Umgebungsvariablen werden geheime Variablen bei der Laufzeit abgerufen.

Umgebungsvariablentypen in Copilot Studio entsprechen den Datentypen in Power Apps wie folgt:

Schreiben Sie in Copilot Studio	Eingeben in Power Apps
Dezimalzahl	Nummer
JSON	Ermitteln Sie den Typ anhand des Wertes. Wenn nicht JSON => Nicht spezifiziert (Validierungsfehler)
Text	String
Ja/Nein	Boolean
Datenquelle	String
Geheimnis	String

Note

Man sieht Fehler bei Umgebungsvariablen im Testchat und beim Veröffentlichen. Diese Fehler erscheinen jedoch nicht in der Topic-Liste , da Umgebungsvariablen keine Topic-Variablen sind.

Systemvariablen

Jeder Agent enthält integrierte Systemvariablen, die zusätzliche Informationen über ein Gespräch liefern.

Copilot Studio zeigt nicht alle Systemvariablen an. Um auf ausgeblendete Systemvariablen zuzugreifen, verwenden Sie eine Power Fx-Formel.

Um Systemvariablen in einer Power Fx-Formel zu verwenden, fügen Sie vor dem Variablennamen System. hinzu. Um beispielsweise die Systemvariable User.DisplayName in eine Formel einzubinden, verweisen Sie als System.User.DisplayName darauf.

Name	Typ	Definition
Aktivität.Anlagen	Tisch	Die Dateianhänge, die der Benutzer bereitstellt.
Activity.Channel	choice	Die Kanal-ID der aktuellen Unterhaltung.
Activity.ChannelData	any	Ein Objekt, das kanalspezifische Inhalte enthält.
Activity.ChannelId	string	Die Kanal-ID der aktuellen Konversation als Zeichenfolge.
Activity.From.Id	string	Die kanalspezifische eindeutige ID des Absenders.
Aktivität.Von.Name	string	Der kanalspezifische benutzerfreundliche Name des Absenders.
Aktivität.Name	string	Der Name des Ereignisses.
Aktivität.Empfänger.Id	string	Die Typ-Eigenschaft der eingehenden Aktivität.
Activity.Recipient.Name	string	Stellt den Anzeigenamen für den Agenten innerhalb des Kanals dar. Im Kontext des Telefoniekanals ist der Wert dieser Variablen die Telefonnummer, mit der der Agent verbunden ist.
Aktivität.Text	string	Die letzte vom Benutzer gesendete Nachricht.
Activity.Type	choice	Typ der Aktivität.
Activity.TypeId	string	Typ der Aktivität als Zeichenfolge.
Aktivität.Wert	any	Wert mit offenem Ende.
Bot.EnvironmentId	string	Die Umgebungs-ID des Agents.
Bot.Id	string	Die ID des Agenten.
Bot.Name	string	Der Name Ihres Agents.
Bot.SchemaName	string	Der Schemaname des Agenten.
Bot.TenantId	string	Die Mandanten-ID des Agents.
ClientPluginActions	choice	Sammlung dynamischer Client-Plug-In-Aktionen, die bei der generativen Orchestrierung zu berücksichtigen sind.
Conversation.Id	string	Die eindeutige ID des aktuellen Gesprächs.
Konversation.ImTestmodus	Boolean	Boolesches Kennzeichen, das angibt, ob die Unterhaltung im Test-Canvas stattfindet.
Unterhaltung.LokaleZeitzone	string	Name der vom Benutzenden zu verwendenden Zeitzone im IANA-Zeitzonendatenbankformat.
Conversation.LocalTimeZoneOffset	datetime	Der Zeitunterschied zur UTC für die aktuelle lokale Zeitzone.
Fehlercode	string	Der Fehlercode des aktuellen Fehlers. Die Fehlermeldung für den aktuellen Fehler.
Fehlermeldung	string	Die Fehlermeldung für den aktuellen Fehler. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Error lautet.
FallbackCount	number	Diese Variable zählt, wie oft ein Thema nicht der Benutzereingabe zugeordnet werden konnte. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Unknown Intent lautet.
InaktivitätsTimer.Fortsetzen	Boolean	Boolesches Kennzeichen, das angibt, ob der Timer fortgesetzt werden muss. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger Inactivity lautet.
InactivityTimer.Count	number	Gibt an, wie oft der OnInactivity-Timer aufgrund von Benutzerinaktivität nach der konfigurierten Zeit ausgelöst wurde. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger Inactivity lautet. Erfahren Sie mehr über den Inaktivitätsauslöser.
LastMessage.Id	string	Die ID der vorherigen vom Benutzer gesendeten Nachricht.
LastMessage.Text	string	Die vorherige vom Benutzer gesendete Nachricht.
Recognizer.ExtractedEntities	choice	Stellt die extrahierten Entitäten aus der auslösenden Nachricht dar. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Select Intent lautet.
Recognizer.IntentOptions	choice	Stellt die Absichtsoptionen dar, wenn die Erkennung mehrdeutige Ergebnisse zurückgibt. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Select Intent lautet.
Recognizer.SelectedIntent	choice	Stellt die vom Erkennungsmodul ausgewählte Absicht dar. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Select Intent lautet.
Recognizer.TriggeringMessage.ID	string	Die ID der Benutzernachricht, die das aktuelle Thema ausgelöst hat.
Recognizer.TriggeringMessage.Nachrichtentext	string	Die Benutzernachricht, die das aktuelle Thema ausgelöst hat.
Recognizer.MultipleTopicsMatchedReason	string	Wird verwendet, um zu ermitteln, warum mehrere Themen übereinstimmen. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Select Intent lautet.
Anmeldegrund	choice	Wird verwendet, um zu bestimmen, welche Anmeldeoption beim Auslösen des Themas erforderlich ist. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Sign In lautet.
Benutzersprache	choice	Mit dieser Variable wird das Gebietsschema der Benutzersprache für jede Unterhaltung festgelegt.

Variablen für sprachaktivierte Agenten

Die folgenden Variablen sind nur für sprachgesteuerte Agenten verfügbar. Erfahren Sie mehr unter Sprachvariablen verwenden.

Name	Typ	Definition
Activity.EingabeDTMFTasten	string	Der rohe DTMF-Schlüsselwert aus der Telefonie.
Aktivität.Spracherkennung.Vertrauensniveau	number	Der Konfidenzwert für das Gesamtergebnis der automatischen Spracherkennungshypothese, 0 zu 1.
Activity.SpeechRecognition.MinimallyFormattedText	string	Leicht formatierter Text des Hypothesenergebnisses der automatischen Spracherkennung. Zum Beispiel: „Fünfhundert Dollar“. Die Wörter werden ausgeschrieben, aber grundlegende Großschreibung und Zeichensetzung werden berücksichtigt.
Activity.UserInputType	choice	Die Art der letzten Eingabe des Agent-Benutzers. Der Wert kann entweder Test, Sprache oder DTMF sein.
Unterhaltung.NurDTMFERlauben	Boolean	Boolesches Kennzeichen, das angibt, ob das IVR zur Laufzeit auf den DTMF-Nur-Modus eingestellt werden soll.
Conversation.SipUuiHeaderValue	string	Die UUI-Headerzeichenfolge, die verwendet wird, um zu Beginn des Anrufs den Kontext an das IVR zu übermitteln.

Variablen für integrierte Authentifizierung (Standard)

Die folgenden Variablen sind für Agenten verfügbar, die für die Authentifizierung bei Microsoft konfiguriert sind. Diese Konfiguration verwendet die Microsoft Entra ID-Authentifizierung und ist die Standardeinstellung für neue Agents. Erfahren Sie mehr unter Authentifizierungsvariablen.

Name	Typ	Definition
Benutzer.Anzeigename	string	Der Anzeigename des Benutzenden, der aktuell mit dem Agenten spricht.
User.Email	string	Die E-Mail-Adresse des Benutzers, der gerade mit dem Agent kommuniziert.
Benutzer.Vorname	string	Der Vorname des Benutzenden, der aktuell mit dem Agenten spricht.
User.Id	string	Die einzigartige ID des Benutzenden, der aktuell mit dem Agenten spricht.
User.IsLoggedIn	Boolean	Boolesches Kennzeichen, das angibt, ob der Benutzer, der gerade mit dem Agent spricht, authentifiziert ist oder nicht.
Benutzer.Nachname	string	Der Familienname des Benutzers, der gerade mit der Agent spricht.
User.PrincipalName	string	Der Benutzerprinzipalname des Benutzers, der derzeit mit der Agent kommuniziert.

Variablen für die manuelle Authentifizierung mit generischem OAuth 2

Die folgenden Variablen sind für Agents verfügbar, die für die Verwendung des generischen Dienstanbieters OAuth 2 konfiguriert sind.

Name	Typ	Definition
User.AccessToken	string	Der Zugriffstoken für den Benutzenden, der sich bei dem Agenten authentifiziert.
Benutzer.Anzeigename	string	Der Anzeigename des Benutzenden, der aktuell mit dem Agenten spricht.
User.Id	string	Die einzigartige ID des Benutzenden, der aktuell mit dem Agenten spricht.
User.IsLoggedIn	Boolean	Boolesches Kennzeichen, das angibt, ob der Benutzer, der gerade mit dem Agent spricht, authentifiziert ist oder nicht.

Variablen für die manuelle Authentifizierung mit Microsoft Entra ID

Die folgenden Variablen sind für Agents verfügbar, die für die Verwendung der Microsoft Entra ID- Dienstanbieter (zuvor Azure Active Directory) konfiguriert sind.

Name	Typ	Definition
User.AccessToken	string	Der Zugriffstoken für den Benutzenden, der sich bei dem Agenten authentifiziert.
Benutzer.Anzeigename	string	Der Anzeigename des Benutzenden, der aktuell mit dem Agenten spricht.
User.Email	string	Die E-Mail-Adresse des Benutzers, der gerade mit dem Agent kommuniziert.
Benutzer.Vorname	string	Der Vorname des Benutzenden, der aktuell mit dem Agenten spricht.
User.Id	string	Die einzigartige ID des Benutzenden, der aktuell mit dem Agenten spricht.
User.IsLoggedIn	Boolean	Boolesches Kennzeichen, das angibt, ob der Benutzer, der gerade mit dem Agent spricht, authentifiziert ist oder nicht.
Benutzer.Nachname	string	Der Familienname des Benutzers, der gerade mit der Agent spricht.
User.PrincipalName	string	Der Hauptbenutzername des Benutzers, der gerade mit dem Agent spricht.