Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
$pages.agent-Objekt
Verwenden Sie das Power Pages Client-API-Objekt und seine SendActivity-Methode$pages.agent, um Nachrichten zu senden oder Ereignisse im Microsoft Copilot Studio-Agent aufzurufen, der für den aktuellen Benutzer verfügbar ist. Antwort- und Fehlerrückrufe helfen der Website, die Ergebnisse des Agents zu verarbeiten.
SendActivity-Methode
Die SendActivity Methode sendet eine Nachricht oder ruft ein Ereignis im angegebenen Copilot Studio-Agent auf und verwendet Rückruffunktionen zum Behandeln von Antworten und Fehlern.
Syntax der SendActivity-Methode
$pages.agent.SendActivity(
agentSchemaName: string,
inputActivity: object,
responseSubscriber: function,
errorSubscriber: function
);
Parameter der SendActivity-Methode
| Parametername | Type | Description |
|---|---|---|
agentSchemaName |
Schnur | Schemaname des Bots, an den die Aktivität gesendet wird. |
inputActivity |
Object | Objekt, das den Text oder das Ereignis enthält, der an den Bot gesendet werden soll. |
responseSubscriber |
Funktion | Rückruffunktion, die ausgeführt wird, wenn der Agent eine Antwort sendet. |
errorSubscriber |
Funktion | Rückruffunktion, die Fehler behandelt. |
Die SendActivity Methode gibt voidzurück. Um eine Antwort vom Agent zu empfangen, übergeben Sie eine responseSubscriber Rückruffunktion. Die Methode ruft diesen Rückruf auf, wenn der Agent eine Antwort sendet. Übergeben Sie eine errorSubscriber Rückruffunktion, um Fehler zu behandeln.
SendActivity-Antworteigenschaften
Antwortobjekt des Agents, das im folgenden Format empfangen wurde:
| Name | Type | Description |
|---|---|---|
type |
Schnur | Typ der Aktivität, z. B. Nachricht. |
text |
Schnur | Optional, Nachricht vom Agent. |
textFormat |
Schnur | Optional, Format des Nachrichtentexts, z. B. Markdown, nur oder XML. |
Id |
Schnur | ID, die die Aktivität eindeutig identifiziert. |
From |
Object | Gibt den Absender der Aktivität an (einschließlich ID, Name (optional) und Rolleninformationen). |
Conversation |
Object | Enthält die ID der Unterhaltung, zu der die Aktivität gehört. |
InputHint |
Schnur | Optional, gibt an, ob der Bot Benutzereingaben akzeptiert, erwartet oder ignoriert. |
replyToId |
Schnur | ID der Antwortnachricht. |
Examples
Die folgenden Beispiele zeigen, wie Sie Antwort- und Fehlerrückrufe definieren und verwenden SendActivity , um eine Nachricht zu senden oder ein Ereignis aufzurufen.
| Beispiel | Description |
|---|---|
| Definieren von Antwort- und Fehlerrückrufen | Definiert die Funktionen und errorSubscriber Rückruffunktionen, die responseSubscriber Agentantworten und -fehler behandeln. |
| Nachricht an Agent senden | Sendet eine Hello! Textaktivität an den angegebenen Agent und verwendet Rückruffunktionen, um die Antwort oder einen Fehler zu behandeln. |
| Clientereignis aufrufen | Ruft das AgentEvent Clientereignis auf und übergibt eine Schlüsselwertnutzlast an den Agent. |
Definieren von Antwort- und Fehlerrückrufen
Definieren Sie die Funktionen und responseSubscriber Rückruffunktionen für die Behandlung von errorSubscriber Agentantworten und -fehlern.
const responseSubscriber = (response) => {
// Replace with your response handling.
console.log('Agent response:', response);
};
const errorSubscriber = (error) => {
// Replace with your error handling.
console.error('Error:', error);
};
// Replace with your agent schema name.
const agentSchemaName = 'agent SchemaName';
Nachricht an Agent senden
In diesem Beispiel wird eine Hello! Textaktivität an den angegebenen Agent gesendet und Rückruffunktionen verwendet, um die Antwort oder einen Fehler zu behandeln.
Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
const inputActivity = {
text: 'Hello!' // Message to the agent.
};
$pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, errorSubscriber);
});
Clientereignis aufrufen
In diesem Beispiel wird das AgentEvent Clientereignis aufgerufen und eine Schlüsselwertnutzlast an den Agent übergeben.
Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
const inputActivity = {
name: 'AgentEvent', // The name of the event to be invoked.
value: { key1: 'value1', key2: 'value2' } // Open-ended value used to carry additional data or payloads necessary for specific agent operations or responses.
};
$pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, errorSubscriber);
});
Fehlermeldungen
Hier sind mögliche Fehlermeldungen, die Benutzer und ihre potenziellen Ursachen treffen können.
| Fehlertyp | Ursache | Fehlermeldung für Benutzer |
|---|---|---|
| Agentschemaüberprüfung | Ungültiger Bot-Schemaname oder Benutzer verfügt nicht über Zugriffsberechtigungen für den Agent. | Invalid bot schema name or access denied. Check the bot schema name and try again. |
| Abrufen des Tokenfehlers | Fehler beim Abrufen des direkten Zeilentokens | Something went wrong while fetching the token. Please try again. |
| Fehler beim Posten der Aktivität (Wiederholung) | Beim Posten der Aktivität ist ein Fehler aufgetreten, und es ist ein Wiederholungsversuche erforderlich. | Something went wrong while posting the activity: retry. |
| Aktivitätsfehler beim Posten (Timeout) | Timeout beim Warten auf ausgehende Nachrichten oder postActivity | Timed out while posting activity: Please retry. |
| Aktivitätsfehler beim Posten (ungültige Aktivität) | Die Eingabeaktivität enthält keinen Text oder einen Namen, um das Ereignis aufzurufen. | Invalid activity: At least one of text, name, or attachments must be provided. |
| Fehler beim Posten der Aktivität (Benutzer-ID nicht gefunden oder Token nicht gefunden) | Das Token wurde im Sitzungsspeicher nicht gefunden, oder die Benutzer-ID wurde im Token nicht gefunden. | Error retrieving user ID: {error message} |
| Aktivitätsfehler beim Posten (allgemein) | Beim Posten der Aktivität ist ein nicht angegebener Fehler aufgetreten. | Something went wrong while posting the activity: Please try again. |
| Fehler bei der Direkten Leitungsverbindung | Fehler beim Erstellen einer direkten Leitungsverbindung mit dem Bot. | Something went wrong while creating direct line connection: Please try again. |
| Allgemeiner Fehler | Unerwarteter Fehler, der nicht in die oben genannten Kategorien fällt | An unexpected error occurred while sending activity: Please try again. |