Azure Bot Service チャネルに Copilot Studio コパイロットを追加する

  • [アーティクル]

重要

Power Virtual Agents 機能は、生成 AI への多大な投資と Microsoft Copilot 全体の統合の強化により、現在 Microsoft Copilot Studio の一部となっています。

ドキュメントやトレーニング コンテンツが更新される間、一部の記事やスクリーンショットで Power Virtual Agents が参照される場合があります。

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

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

チップ

このドキュメントに従って、Copilot Studio コパイロットを Web サイト、Facebook、または Microsoft Teams に追加する必要はありません。 Web ベースのカスタム アプリまたはネイティブ アプリに接続する場合、開発者は詳細を コパイロットをモバイル アプリおよびカスタム アプリに追加する で詳細を確認できます。

重要

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

前提条件

コード サンプル

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

参照

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

既存の 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 を使用します。

    Slack チャネル。

  4. トークン エンドポイント 値をコピーして保存するには、コピー を選択します。 コパイロットを Azure Bot Service チャネルに接続するには、エンドポイントが必要です。

    ボット パラメーターを取得します。

Copilot Studio コパイロットを使用して会話セッションを管理する

Azure Bot Service チャネルと Copilot Studio コパイロットとの Direct Line 接続の間には、複数の会話が可能です。

Azure Bot Service ボットは、Azure Bot Service チャネルから、Copilot Studio コパイロットとの Direct Line 会話、またはその逆に、会話をマップして中継する必要があります。

サンプル コードの例

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

  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. 複数のセッションを管理するには、外部の Azure Bot Service チャネル会話に対応する Copilot Studio コパイロット会話へのマッピングを維持する必要があります。 Copilot Studio コパイロット会話は、2 つのプロパティで識別および接続されます: ConversationtId および Token。

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

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

    /// <summary>
/// Data model class for Copilot Studio copilot conversation
/// </summary>
public class PowerVirtualAgentsConversation
{
    public string ConversationtId { get; set; } // The Copilot Studio copilot 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 copilot
}

  3. 新しい Copilot Studio コパイロット会話が始まったら、キーと値のペア (external_Azure_Bot_Service_channel_conversationID、PowerVirtualAgentsConversation) をマッピング テーブルに追加します。

    // After new Copilot Studio copilot 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 copilot and get response
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Retrieve copilot conversation from mapping table
    // If not exists for the given external conversation ID, start a new Copilot Studio copilot 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. Copilot Studio コパイロットの応答を取得する方法については、Direct Line を使用してコパイロットと通信 を参照してください。 Copilot Studio コパイロットの応答を受信したら、外部 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 チャネル で表示されます。