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

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

ほとんどの場合、カスタムアプリは、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チャネルに公開するを参照してください。

Important

このセクションの手順に従うには、ソフトウェア開発スキルが必要です。この手順は、開発者ツール、ユーティリティ、IDE (統合開発環境) を十分に理解している IT 管理者や開発者などの経験豊富な IT プロフェッショナルに適した専門知識のレベルを前提としています。

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

作成したエージェントに接続するには、エージェントの名前とトークンエンドポイントを取得して識別します。

Copilot Studioで、エージェントの Overview ページに移動し、エージェントの名前をコピーします。
チャンネル>モバイルアプリ を選択します。
モバイルアプリ ページで、トークンエンドポイント の横にある コピーを選択します。 Direct Line トークンを取得するステップではこのエンドポイントが必要です。

Direct Line トークンを取得

エージェントと会話を始めるには Direct Line トークンが必要です。このトークンを取得するには、Copilot Studio画面に表示されるエンドポイントに GET 要求を送信します。このトークンは、ダイレクトライン 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」を参照>。

引き継ぎ活動を処理する

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

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

ユーザーが会話を開始したときにエージェントから Greeting システムトピックが自動的に送信されるようにするには、 Type=event と Name=startConversationを使用してアクティビティを送信します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-02