モバイルアプリやカスタムアプリでエージェントを公開する

2025-06-20

エージェントをカスタムアプリに接続して、アプリのユーザーがアプリ内から直接エージェントと対話できるようにします。

ほとんどの場合、カスタムアプリは、Web ベースのアプリか、ネイティブアプリ、またはビジネスに必要な他のサービスへのアダプターのいずれかであるモバイルデバイスアプリです。

モバイルアプリに接続するには異なる手順があり、アプリが Web ベースのアプリか、またはネイティブアプリかによります。

エージェントを Web ベースのアプリに接続するのは、コードスニペットをアプリにコピーすることになるため、比較的簡単です。ただし、Web ベースのアプリおよびネイティブ、またはカスタムアプリのどちらも、エージェントをアプリに完全に統合するための、開発者の専門知識がかなり必要となります。この記事では、両方の手順について説明します。

前提条件

.NET Core SDK バージョン 2.1。
NuGet パッケージ Microsoft.Bot.Connector.DirectLine。
アプリに接続する Copilot Studio で作成されたエージェント。

エージェントを Web ベースのアプリに接続する

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>

リクエストが成功すると、Direct Line トークン、有効期限、リクエストされたエージェントの conversationId が返されます。

例:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

Direct Line トークンのコード例を取得する

次の例では、Copilot Studio エージェントの Direct Line トークンを取得します。

/// <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 トークン取得した後、使用している Direct Line の Copilot Studio エージェントと会話の準備ができます。会話を開始して、メッセージを送受信するには、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 を使用してエージェントの応答を取得します。取得した Direct Line 応答アクティビティには、ユーザーとエージェントの両方のメッセージが含まれます。エージェントの名前で応答活動をフィルター処理して、エージェントの応答メッセージのみを取得できます。

   // 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 で確認できます。

ハンドオフ活動を処理する

アプリケーションがライブチャットオペレータープロバイダーにハンドオフする必要がある場合は、ハンドオフ活動を処理する必要があります。 "エージェントに転送" ノードがヒットすると、ハンドオフ活動が送信されます。詳細については、ハンドオフ活動のペイロードを参照してください。

ウェルカムメッセージをトリガーする

ユーザーが会話を開始したときに、エージェントにグリーティングシステムトピックを自動的に送信させる場合は、Type=event と Name=startConversation を使用して活動を送信できます。

次の方法で共有

モバイル アプリやカスタム アプリでエージェントを公開する