エージェント をAzure Bot Serviceチャンネルに公開します

既存の Azure Bot Serviceチャンネル に エージェント を 接続 することができます。これは、Azure Bot Serviceチャンネルのエンドユーザーに エージェント を 接続 する場合に役立ちます。

エージェント をAzure Bot Serviceチャネルに追加するには、相当の開発者の専門知識が必要です。 この記事は、コードの開発と記述の経験がある IT 管理者または開発者向けに書かれています。

チップ

Copilot Studio エージェント を Webサイト Facebookなどに追加するために、このドキュメントを 追従する する必要はありません Microsoft Teams。 カスタムWebベースまたはネイティブ アプリに 接続 することが目標である場合、開発者は モバイル アプリまたはカスタム アプリに エージェント を公開する で詳細を確認できます。

重要

このセクションの手順では、ユーザーまたは開発者によるソフトウェア開発が必要です。 これは、開発者ツール、ユーティリティ、および IDE を十分に理解している IT 管理者または開発者などの経験豊富な IT プロフェッショナルを対象としています。

前提条件

• Azure Bot Service サブスクリプション。
• v4 SDK を使用する Azure Bot Service ボ ット。
• .NET Core SDK バージョン 2.1。
• NuGet パッケージ Microsoft.Bot.Connector.DirectLine。
• Copilot Studio で作成された エージェント をAzure Bot Serviceチャンネルに 接続 します。
• エージェント をモバイル アプリまたはカスタム アプリに公開します。

コード サンプル

このドキュメントで使用されているコード スニペットは中継ボットのサンプル コード からのものです。

参照

このドキュメントの手順では、以下のドキュメントを参照しています。

• ボットを Azure に展開する は Azure Bot Service ボットを展開する手順について説明します。
• Azure Bot Service チャネル は任意の Azure Bot Service がサポートするチャネルに接続する方法について説明します。
• エミュレーターを使用した Azure Bot Service デバッグ は Azure Bot Service ボットのデバッグに関する手順について説明します。

既存の Azure Bot Service ボットを作成または使用する

Copilot Studio エージェント とAzure Bot Serviceチャンネル間の会話を中継できるAzure Bot Serviceボット が必要です。

中継ボットのサンプル コード は、既存の Azure Bot Service ボットがない場合に、良い開始点となります。 これは Microsoft Bot Framework ボット サンプル コード から構築され、Azure Bot Service にコンパイルされ展開されます。 サンプル コードは開始点として使用することを意図しており、運用環境で直接使用することを意図していません。 ビジネス ニーズに合わせてコードおよび最適化を追加する必要があります。

Azure Bot Service ボットが既にある場合は、Copilot Studio コネクタと会話セッションを管理するためのとコードを追加する必要があります。 次に、ボットを Azure Bot Service に展開し、Azure Portal でチャネルに接続できます。

Copilot Studio エージェント パラメータを取得する

Copilot Studioを使用して構築した エージェント に 接続 するには、エージェント の名前とトークン エンドポイント を取得する必要があります。

1. Copilot Studioにエージェントの名前をコピーします。

   

2. ナビゲーション メニューの 設定 で チャネル を選択します。

3. 接続するチャネルを選択します。 このシナリオでは、例として Slack を使用します。

   

4. トークン エンドポイント 値をコピーして保存するには、コピー を選択します。 エンドポイント を使用して、エージェント をAzure Bot Serviceチャンネルに 接続 する必要があります。

   

Copilot Studio エージェントとの会話セッションを管理する

Azure Bot Serviceチャネルと Direct Line エージェント との接続 Copilot Studio の間では複数の会話が発生する可能性があります。

Azure Bot Serviceボット は、Azure Bot Serviceチャネルからの会話を Direct Line エージェント との会話 Copilot Studio にマッピングして中継する必要があり、その逆も同様です。

サンプル コードの例

次の例では、中継ボットのサンプル コード からのサンプルを使用します。

1. 新しい外部Azure Bot Serviceチャネルの会話が始まるたびに、 Copilot Studio エージェント 会話を開始します。 ボット との新しい会話を開始する手順については、「 トークンを取得 Direct Line して 、 使用 Direct Line して エージェント と通信する 」を参照してください。

   using (var httpRequest = new HttpRequestMessage())
   {   
       httpRequest.Method = HttpMethod.Get;
       UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
       httpRequest.RequestUri = uriBuilder.Uri;
       using (var response = await s_httpClient.SendAsync(httpRequest))
       {
           var responseString = await response.Content.ReadAsStringAsync();
           string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
       }
   }
   
   /// <summary>
   /// class for serialization/deserialization DirectLineToken
   /// </summary>
   public class DirectLineToken
   {
       public string Token { get; set; }
   }
   

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

2. 複数のセッションを管理するには、対応する Copilot Studio エージェント 会話に対して、外部のAzure Bot Serviceチャネル会話の マッピング を維持する必要があります。 Copilot Studio エージェント 会話は、 ConversationtId および Tokenという2つのプロパティで識別および接続できます。

   Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();  
   

   会話のライフサイクルを管理するには、Direct Line トークンを更新するか、アイドル状態の会話をクリーンアップします。 トークンの更新について詳しくは、Direct Line トークンの更新 を参照してください。 トークンの更新をサポートする Copilot Studio エージェント 会話 Direct Line は次のように定義されます。

   /// <summary>
   /// Data model class for Copilot Studio agent conversation
   /// </summary>
   public class PowerVirtualAgentsConversation
   {
       public string ConversationtId { get; set; } // The Copilot Studio agent conversation ID retrieved from step 1
   
       public string Token { get; set; } // The DirectLine token retrieved from step 1
   
       public string WaterMark { get; set; } // Identify turn in a conversation
   
       public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh
   
       public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to agent
   }
   

3. 新しい Copilot Studio エージェント 会話が開始されたら、キー値のペア (external_Azure_Bot_Service_channel_conversationID、 PowerVirtualAgentsConversation) を マッピング テーブルに追加します。

   // After new Copilot Studio agent conversation starts
   ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
     {
       Token = token,
       ConversationtId = conversationId,
       WaterMark = null,
       LastConversationUpdateTime = DateTime.Now,
       LastTokenRefreshTime = DateTime.Now,
     }; 
   

4. 既存の会話を続行するには、新しい外部Azure Bot Serviceチャネル メッセージを受信したら、マッピング テーブルから既存の会話を取得し、外部会話アクティビティを Copilot Studio エージェント に中継して、応答 を取得します。

   次のサンプルは、ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken) method を上書きすることで会話を中継していることを示します

   // Invoked when a message activity is received from the user
   // Send the user message to Copilot Studio agent and get response
   protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
   {
       // Retrieve agent conversation from mapping table
       // If not exists for the given external conversation ID, start a new Copilot Studio agent conversation
       ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
               currentConversation : /*await StartBotConversationAsync(externalCID)*/;
   
       // Create DirectLine client with the token associated to current conversation
       DirectLineClient client = new DirectLineClient(currentConversation.Token);
   
       // Send user message using directlineClient
       await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
       {
         Type = DirectLineActivityTypes.Message,
         From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
         Text = turnContext.Activity.Text,
         TextFormat = turnContext.Activity.TextFormat,
         Locale = turnContext.Activity.Locale,
       });
   
       // Update LastConversationUpdateTime for session management
       currentConversation.LastConversationUpdateTime = DateTime.Now;
   }  
   

5. エージェント との通信 Direct Line に使用して エージェント's応答. を取得する方法を参照してください。 Copilot Studio Copilot Studio エージェント's応答 を受信した場合、応答 を外部のAzure Bot Serviceチャネル 応答 に解析する方法については、 エージェント からの会話ペイロードの解析 を参照してください。

応答解析の例は、中継ボットのサンプル コード ResponseConverter.cs にあります。

Azure Bot Service に展開する

Azure Bot Service 中継ボットの準備ができたら、ボットを Azure Bot Service に展開する 必要があります。

Azure Bot Service チャネルを設定する

Azure portal にサインインして、展開した Azure Bot Service リソース グループを選択することで、接続するチャネルを設定できます。 各チャネルの特定の手順は、Azure Bot Service チャネル で表示されます。