Teams でエージェント構成エクスペリエンスを作成する

エージェント構成エクスペリエンスを使用すると、ユーザーはインストール後にチャネルまたはグループ チャット スコープ内でエージェントの設定を直接設定および再構成できます。 これにより、エージェントの運用効率が最初から向上します。 エージェント構成エクスペリエンスにより、以前はアプリのタイムリーな利点を妨げ、ユーザー エクスペリエンスに影響を与えたユーザー介入を繰り返す必要がなくなります。

エージェント構成エクスペリエンスを使用すると、ユーザーが次のようにエージェントの継続的な関連性と価値を確保できます。

  • インストール中にエージェントを特定のワークフローと設定に合わせて調整します。
  • インストール後の要件の変更に合わせて設定を再構成します。

たとえば、ニュース トピックを追跡して共有したり、GitHub リポジトリを監視したりするエージェントは、最初はユーザー ワークフローに合わせて設定できます。 後で簡単に再構成して、グループ チャットから直接新しいトピックやリポジトリに応答し、Teams 環境を離れることなくコンテンツ管理と対話を合理化できます。 この柔軟な構成エクスペリエンスにより、エージェントを毎日の運用にシームレスに統合することで、ユーザー エクスペリエンスと生産性が大幅に向上します。

ユーザーがグループ チャットにエージェントを追加し、特定の要件に合わせて構成する例を次に示します。 その後、ユーザーはエージェントを再構成して状態を変更します。

構成

グループ チャットへのエージェントの追加とインストール中のエージェント設定の構成を示すグラフィカル表現。

再構成

メッセージ作成領域のエージェントの構成オプションを示すグラフィカル表現。

ボットとタブの機能をサポートするアプリの既定のランディング機能としてエージェントを構成するには、「既定の ランディング機能を構成する」を参照してください。

ビルド エージェントの構成エクスペリエンス

注:

エージェント構成エクスペリエンスは、チャネルまたはグループ チャットでのみサポートされます。

エージェント構成エクスペリエンスを構築するときは、ユーザーが最初のインストール時にエージェントを構成し、いつでも再構成できる必要があります。

エージェント構成エクスペリエンスを構築するには、次の手順に従います。

  1. アプリ マニフェストの更新

  2. ボットを構成する

アプリ マニフェストの更新

アプリ マニフェスト (以前は Teams アプリ マニフェストと呼ばれる) ファイルで、bots.configuration オブジェクトの下にある fetchTask プロパティを次のように更新します。

"bots": [
    {
      "botId": "${{AAD_APP_CLIENT_ID}}",
     "needsChannelSelector": false,
      "scopes": [
        "personal",
        "team",
        "groupChat"
      ],
      "configuration":{
        "groupChat":{
          "fetchTask": true
        },
        "team":{
          "fetchTask": true
        }
      },
      "isNotificationOnly": false
    }
  ],

詳細については、「 アプリ マニフェスト スキーマ」を参照してください。

エージェントを構成する

ユーザーがチャネルまたはグループ チャットにエージェントをインストールすると、アプリ マニフェスト ファイルの fetchTask プロパティによって、 config.fetch または config.submitが開始されます。

アプリ マニフェストで fetchTask プロパティを 次のように設定した場合:

  • false: エージェントはダイアログまたはアダプティブ カードをフェッチしません。 代わりに、エージェントは、エージェントの呼び出し時に使用される静的ダイアログまたはカードを提供する必要があります。 詳細については、「 ダイアログ」を参照してください。

  • true: エージェントは、定義された config.fetch または config.submit を開始します。 エージェントが呼び出されると、 channelData と userdata で提供されるコンテキストに応じて、アダプティブ カードまたはダイアログを返すことができます。

次の表に、呼び出し要求に関連付けられている応答の種類を示します。

呼び出し要求 応答の種類
config.fetch Type: "continue" または Type = "auth"
config.submit Type: "continue" または Type: "message"
  • type: "continue": type: "continue" は、エージェント構成内のダイアログまたはアダプティブ カードの継続を定義するために使用されます。 型が continue に設定されている場合は、エージェントが構成プロセスを続行するためにユーザーからの追加の操作を期待していることを示します。

    ユーザーが構成を送信すると、 config.submit 呼び出しがトリガーされます。 ユーザーの入力を読み取り、別のアダプティブ カードを返します。 エージェント構成を更新して ダイアログを返すこともできます。


app.OnConfigFetch(async (context) =>
{
 var card = new AdaptiveCard
 {
     Body = new List<CardElement>
     {
         new TextBlock("Configure your agent")
         {
             Weight = TextWeight.Bolder
         }
     },
     Actions = new List<Action>
     {
         new SubmitAction
         {
             Title = "Submit"
         }
     }
 };
 var taskInfo = new TaskInfo
 {
     Title = "test card",
     Width = new Union<int, Size>(600),
     Height = new Union<int, Size>(500),
     Card = new Attachment
     {
         ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
         Content = card
     }
 };
 return new ConfigTaskResponse(
     new ContinueTask(taskInfo)
 );
});
  • type: "auth": ユーザーに要求への応答として認証 config.fetch 要求するように要求することもできます。 type: "auth"構成では、指定した URL を使用してサインインするようにユーザーに求められます。これは、ブラウザーで開くことができる有効な認証ページにリンクする必要があります。 認証は、エージェントがユーザーの認証を要求するシナリオに不可欠です。 これにより、ユーザーの ID が検証され、セキュリティが維持され、エージェントの機能内で個人用に設定されたエクスペリエンスが確保されます。

    注:

    type: "auth"では、サード パーティ認証のみがサポートされます。 シングル サインオン (SSO) はサポートされていません。 サード パーティ認証の詳細については、「認証の追加」を参照してください。


app.OnConfigFetch(async (context) =>
{
 return new ConfigAuthResponse(
     new ConfigAuth
     {
         SuggestedActions = new SuggestedActions
         {
             Actions = new List<CardAction>
             {
                 new CardAction
                 {
                     Type = "openUrl",
                     Value = "https://example.com/auth",
                     Title = "Sign in to this app"
                 }
             }
         }
     }
 );
});

  • type="message": 型が message に設定されている場合は、エージェントが単純なメッセージをユーザーに送信していることを示し、対話の終わりを示すか、さらに入力を必要とせずに情報を提供します。

app.OnConfigSubmit(async (context) =>
{
 return new ConfigTaskResponse(
     new MessageTask("You have chosen to finish setting up agent")
 );
});

ユーザーがエージェントを再構成すると、アプリ マニフェスト ファイルの fetchTask プロパティによって、エージェント ロジックの config.fetch が開始されます。 ユーザーは、インストール後にエージェント設定を 2 つの方法で再構成できます。

  • @mention メッセージ作成領域のエージェント。 メッセージ作成領域の上に表示される [設定] オプションを選択します。 ダイアログボックスにエージェントの構成設定が表示、更新、または変更されます。

    メッセージ作成領域のエージェントの構成オプションを示すスクリーンショット。

  • エージェントの上にマウス ポインターを合わせると、エージェント プロファイルカードが表示されます。 エージェントの構成設定を更新または変更するには、エージェント プロファイル カードの設定アイコンを選択します。

    Teams グループ チャットのエージェントの構成オプションを示すスクリーンショット。

ベスト プラクティス

  • エージェントの個々のチャネル レベルの構成を作成する場合は、チャネルに従って構成を追跡してください。 構成データは格納されておらず、呼び出しペイロードには十分な channelData が含まれています。

  • URL、エリア パス、ダッシュボード リンクなど、エージェントが正常に動作するために必要な情報を入力するようにユーザーに求めるわかりやすいダイアログを提供します。

  • ユーザーが混乱する可能性があるため、インストール後に複数の通知や構成要求を送信しないようにします。

コード サンプル

サンプルの名前 説明 .NET Node.js マニフェスト
エージェント構成アプリ このサンプルでは、チームおよびグループ チャットでアダプティブ カードを構成および再構成するためのエージェントを示します。 表示 表示 表示
認証を使用したエージェント構成アプリ この Teams エージェントでは、アダプティブ カードで動的検索機能を使用して構成と再構成を行うことができます。 表示 表示 表示

関連項目