Copilot Studio エージェントでクライアント API を使用する

$pages.agent オブジェクト

Power Pages Client API $pages.agent オブジェクトとその SendActivity メソッドを使用して、現在のユーザーが使用できるMicrosoft Copilot Studio エージェントでメッセージを送信したり、イベントを呼び出したりします。 応答コールバックとエラー コールバックは、サイトがエージェントの結果を処理するのに役立ちます。

SendActivity メソッド

SendActivity メソッドは、メッセージを送信するか、指定したCopilot Studio エージェントでイベントを呼び出し、コールバック関数を使用して応答とエラーを処理します。

SendActivity メソッドの構文

$pages.agent.SendActivity(
    agentSchemaName: string,
    inputActivity: object,
    responseSubscriber: function,
    errorSubscriber: function
);

SendActivity メソッドのパラメーター

パラメーター名 タイプ Description
agentSchemaName String アクティビティの送信先となるボットのスキーマ名。
inputActivity Object ボットに送信するテキストまたはイベントを含むオブジェクト。
responseSubscriber 関数 エージェントが応答を送信するときに実行されるコールバック関数。
errorSubscriber 関数 エラーを処理するコールバック関数。

SendActivity メソッドはvoidを返します。 エージェントから応答を受信するには、 responseSubscriber コールバック関数を渡します。 このメソッドは、エージェントが応答を送信するときにこのコールバックを呼び出します。 エラーを処理するために errorSubscriber コールバック関数を渡します。

SendActivity 応答プロパティ

次の形式で受信したエージェントからの応答オブジェクト:

Name タイプ Description
type String メッセージなどのアクティビティの種類。
text String 省略可能。エージェントからのメッセージ。
textFormat String オプション。マークダウン、プレーン、XML など、メッセージのテキストの形式。
Id String アクティビティを一意に識別する ID。
From Object アクティビティの送信者 (ID、名前 (省略可能)、ロール情報を含む) を指定します。
Conversation Object アクティビティが属する会話の ID を格納します。
InputHint String 省略可能。ボットがユーザー入力を受け入れるか、想定しているか、無視しているかを示します。
replyToId String 応答メッセージの ID。

Examples

次の例では、応答コールバックとエラー コールバックを定義し、 SendActivity を使用してメッセージを送信したり、イベントを呼び出したりする方法を示します。

例 Description
応答コールバックとエラー コールバックを定義する エージェントの応答とエラーを処理する responseSubscriber および errorSubscriber コールバック関数を定義します。
エージェントにメッセージを送信する 指定したエージェントに Hello! テキスト アクティビティを送信し、コールバック関数を使用して応答またはエラーを処理します。
クライアント イベントを呼び出す AgentEvent クライアント イベントを呼び出し、キーと値のペイロードをエージェントに渡します。

応答コールバックとエラー コールバックを定義する

エージェントの応答とエラーを処理する responseSubscriber および errorSubscriber コールバック関数を定義します。

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';

エージェントにメッセージを送信する

この例では、指定したエージェントに Hello! テキスト アクティビティを送信し、コールバック関数を使用して応答またはエラーを処理します。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const inputActivity = {
        text: 'Hello!' // Message to the agent.
    };

    $pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, errorSubscriber);
});

クライアント イベントを呼び出す

このサンプルでは、 AgentEvent クライアント イベントを呼び出し、キー値ペイロードをエージェントに渡します。

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);
});

エラー メッセージ

ユーザーが発生する可能性があるエラー メッセージとその潜在的な原因を次に示します。

エラーの種類 原因 ユーザーのエラー メッセージ
エージェント スキーマの検証 無効なボット スキーマ名が指定されているか、ユーザーにエージェントへのアクセス許可がありません Invalid bot schema name or access denied. Check the bot schema name and try again.
トークンのフェッチ エラー 直接行トークンのフェッチ中にエラーが発生しました Something went wrong while fetching the token. Please try again.
投稿アクティビティ エラー (再試行) アクティビティの投稿中にエラーが発生し、再試行が必要です。 Something went wrong while posting the activity: retry.
投稿アクティビティ エラー (タイムアウト) 送信メッセージまたは postActivity の待機中にタイムアウトしました Timed out while posting activity: Please retry.
投稿アクティビティ エラー (無効なアクティビティ) 入力アクティビティには、イベントを呼び出すテキストまたは名前がありません。 Invalid activity: At least one of text, name, or attachments must be provided.
投稿アクティビティ エラー (ユーザー ID が見つからないか、トークンが見つかりません) セッション ストレージにトークンが見つからないか、トークンにユーザー ID が見つかりません Error retrieving user ID: {error message}
転記アクティビティ エラー (一般) アクティビティの投稿中に未指定のエラーが発生しました Something went wrong while posting the activity: Please try again.
直接接続エラー ボットとの直接接続の作成中にエラーが発生しました。 Something went wrong while creating direct line connection: Please try again.
一般的なエラー 上記のカテゴリに分類されない予期しないエラー An unexpected error occurred while sending activity: Please try again.
  • 最終更新: