Verwenden der Client-API mit Copilot Studio-Agents

$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.