エージェント をモバイルまたはカスタムアプリに公開する
エージェント をカスタム アプリに 接続 すると、アプリのユーザーはアプリ内から直接 エージェント を操作できるようになります。
ほとんどの場合、カスタム アプリは、Web ベースのアプリか、ネイティブ アプリ、またはビジネスに必要な他のサービスへのアダプターのいずれかであるモバイル デバイス アプリです。
モバイル アプリに接続するには異なる手順があり、アプリが Web ベースのアプリか、またはネイティブ アプリかによります。
エージェント をWebベースのアプリに接続するのは、コード スニペット をアプリにコピーするだけなので、比較的簡単です。 ただし、Webベースのアプリでも、ネイティブ アプリやカスタム アプリでも、エージェント をアプリに完全に統合するには、かなりの開発者の専門知識が必要です。 この記事では、両方の手順について説明します。
前提条件
- .NET Core SDK バージョン 2.1。
- NuGet パッケージ Microsoft.Bot.Connector.DirectLine。
- Copilot Studio で作成された エージェント をアプリに 接続 します。
接続 で エージェント をウェブベースのアプリに追加しましょう
Copilot Studio で、ナビゲーション メニューの チャンネル を選択します。
モバイル アプリ タイルを選択して、構成ウィンドウを開きます。
コードを Web ベースのアプリ セクションにコピーして、アプリの開発者に提供し、Web ベース アプリに追加します。
接続 で エージェント をネイティブ アプリまたはカスタム アプリに追加しましょう
チップ
このセクションではモバイル アプリへの接続方法について説明しますが、IoT (モノのインターネット) などのカスタムまたはネイティブ アプリにも同じプロセスを適用することができます。
Azure Bot Serviceチャネルに 接続 することが目標である場合、ここでの手順に従う以外に、開発者は エージェント をAzure Bot Serviceチャネルに公開する で詳細を確認できます。
重要
このセクションの手順では、ユーザーまたは開発者によるソフトウェア開発が必要です。 これは、開発者ツール、ユーティリティ、および IDE を十分に理解している IT 管理者または開発者などの経験豊富な IT プロフェッショナルを対象としています。
コード サンプル
このドキュメントで使用されているコード スニペットは次のとおりです。
参照
このドキュメントの手順では、以下のソース資料を参照しています。
Copilot Studio エージェント パラメータを取得します
構築した エージェント に 接続 するには、エージェント の名前とトークン エンドポイント を取得して識別する必要があります。
Copilot Studioで、エージェント の 概要 ページに移動し、エージェント の名前をコピーします。
チャンネル>モバイル アプリ を選択します。
モバイル アプリ ページで、 トークン エンドポイント, 選択 の横にあるをコピーします。 Direct Line トークンを取得 手順では、このエンドポイントが必要です。
Direct Line トークンを取得
エージェント との会話を開始するには、 Direct Line トークンが必要です。 このトークンは、Copilot Studio 画面内に示されているエンドポイントに GET 要求を送信することで取得できます。 このトークンは、その後の directline API 呼び出しのヘッダーとして使用する必要があります。
例:
GET <BOT TOKEN ENDPOINT>
リクエストが成功した場合、リクエストされた エージェント のトークン、有効期限、および会話IDが返されます。 Direct Line 例:
{
"token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
"expires_in": 3600,
"conversationId": "abc123"
}
サンプル コードの例
次の例では、 コネクタ サンプル コード のサンプルを使用して、 Direct Line エージェント Copilot Studio のトークンを取得します。
/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
try
{
return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
}
catch (HttpRequestException ex)
{
throw ex;
}
}
/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
public string Token { get; set; }
public int Expires_in { get; set; }
public string ConversationId { get; set; }
}
応答オブジェクトは、先ほど見た GET 要求と同じです。
{
"token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
"expires_in": 3600,
"conversationId": "abc123"
}
Direct Line を使用してエージェントと通信します
Direct Line トークンを取得したら、 Copilot Studio エージェント と Direct Line会話する準備が整います。 会話を開始して、メッセージを送受信するには、Bot Framework Direct Line API で指示に従います。
次の例では、 コネクタ サンプル コード のサンプルを使用して会話を開始し、 Copilot Studio エージェント からメッセージを送受信します。
DirectLineClient インスタンスを Direct Line トークンで初期化し、会話を開始します:
// Use the retrieved token to create a DirectLineClient instance using (var directLineClient = new DirectLineClient(token)) { var conversation = await directLineClient.Conversations.StartConversationAsync(); string conversationtId = conversation.ConversationId; }開始すると、各会話は
tokenおよびconversationtIdの組み合わせを使用して識別および接続できます。 既存の会話にユーザー メッセージを送信します。// Use the retrieved token to create a DirectLineClient instance // Use the conversationId from above step // endConversationMessage is your predefined message indicating that user wants to quit the chat while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase)) { using (var directLineClient = new DirectLineClient(token)) { // Send user message using directlineClient // Payload is a Microsoft.Bot.Connector.DirectLine.Activity await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity() { Type = ActivityTypes.Message, From = new ChannelAccount { Id = "userId", Name = "userName" }, Text = inputMessage, TextFormat = "plain", Locale = "en-Us", }); } }同じ
tokenとconversationIdを使用して エージェント's応答 を取得します。 取得された Direct Line 応答 アクティビティには、ユーザーと エージェント の両方のメッセージが含まれます。 応答 アクティビティを エージェント の名前でフィルタリングして、エージェント's応答 メッセージのみを取得できます。// Use the same token to create a directLineClient using (var directLineClient = new DirectLineClient(token)) { // To get the first response set string watermark = null // More information about watermark is available at // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0 // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark); // update watermark from response watermark = response?.Watermark; // response contains set of Activity from both user and bot // To display bot response only, filter Activity.From.Name equals to your bot name List<Activity> botResponses = response?.Activities?.Where(x => x.Type == ActivityTypes.Message && string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList(); // Display botResponses }
Direct Line トークンを最新の情報に更新
アプリケーションが エージェント と長時間の会話を行う場合は、 Direct Line トークンを更新するためのコードを追加する必要があるかもしれません。 トークンは期限切れになりますが、期限が切れる前に更新できます; 詳細は Direct Line 認証 で確認してください。
次の例では、コネクタ サンプル コード のサンプルと使用して、既存の Copilot Studio 会話のトークンを最新の情報に更新します。
// DirectLine provides a token refresh method
// Requires the currentToken valid when refreshing
string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
// create a new directline client with refreshToken
directLineClient = new DirectLineClient(refreshToken);
// use new directLineClient to communicate to your bot
エージェント からの会話ペイロードを解析します
エージェント との会話を開始すると、会話JSONペイロードは標準の Microsoft Bot Framework Direct Line アクティビティを使用します。 詳細は、Bot Framework Direct Line API で確認できます。
ハンドオフ活動を処理する
アプリケーションがライブ チャット オペレーター プロバイダーにハンドオフする必要がある場合は、ハンドオフ活動を処理する必要があります。 "エージェントに転送" ノードがヒットすると、ハンドオフ活動が送信されます。 詳細については、ハンドオフ活動のペイロードを参照 してください。
ウェルカム メッセージをトリガーする
ユーザーが会話を開始したときに エージェント がGreetingシステム トピック を自動的に送信するようにしたい場合は、 Type=event と Name=startConversation を使用してアクティビティを送信できます。