エージェントの概念を理解する

エージェントの対話は、テキスト、音声、画像、またはビデオを使用できます。 ユーザーの入力を処理して要求を理解し、関連するタスクを実行するために入力を評価します。 エージェントは、情報を要求したり、サービスへのアクセスを有効にしたりして、ユーザーに応答することができます。

エージェント スコープ

Microsoft Teamsのエージェントは、1 対 1 の会話、グループ チャット、またはチーム内のチャネルに参加できます。 各スコープは、会話エージェントに固有の機会と課題を提供します。

チャネル	グループ チャット	1 対 1 のチャット
大規模なリーチ	減少したメンバー	従来の方法
簡潔な個々のやり取り	@mention エージェントへ	Q&A エージェント
@mention エージェントへ	チャネルと同様	ジョークを伝え、メモを取るエージェント

チャネル

チャネルには、最大 2000 人まで、複数のユーザー間のスレッド化された会話が含まれています。 これにより、エージェントに大規模な範囲が与えられる可能性がありますが、個々の操作は簡潔にする必要があります。 従来のマルチターン操作は機能しません。 代わりに、対話型のカードまたはダイアログ (TeamsJS v1.x ではタスク モジュールと呼ばれます) を使用するか、会話を 1 対 1 の会話に移動して多くの情報を収集する必要があります。 エージェントは、 @mentionedされているメッセージにのみアクセスできます。 Microsoft Graph および組織レベルのアクセス許可を使用して会話から追加のメッセージを取得できます。

エージェントは、次の場合にチャネルでより適切に機能します。

• ユーザーが追加情報を取得するための対話型カードを提供する通知。
• 投票やアンケート調査などのフィードバック シナリオ。
• 単一の要求または応答サイクルは対話を解決し、結果は複数のメンバーで会話をする場合に役立ちます。
• ソーシャルエージェントや楽しいエージェントは、素晴らしい猫の画像を取得し、ランダムに勝者を選びます。

グループ チャット

グループ チャットは、3 人以上のユーザー同士で行われる非スレッドの会話です。 チャネルよりもメンバーは少なく、一時的な会話が多いのが特徴です。 チャネルと同様に、エージェントは直接 @mentioned メッセージにのみアクセスできます。

チャネルでより適切に機能するエージェントは、グループ チャットでもより適切に機能します。

1 対 1 のチャット

1 対 1 のチャットは、会話エージェントがユーザーと対話するための従来の方法です。 1 対 1 の会話エージェントの例を次に示します。

• Q&A エージェント
• 他のシステムでワークフローを開始するエージェント。
• ジョークを伝えるエージェント。
• エージェントがメモを取ります。 1 対 1 のエージェントを作成する前に、会話ベースのインターフェイスが機能を提示する最善の方法であるかどうかを検討してください。

アクティビティ ハンドラーとエージェント ロジック

ニーズを満たすエージェント アプリを作成するには、アクティビティ ハンドラーとエージェント ロジックMicrosoft Teams理解することが不可欠です。 これら 2 つの主要なコンポーネントが連携して、会話ロジックを整理します。

• Teams アクティビティ ハンドラー: チャネルの作成、チーム メンバーの追加、Teams 環境固有のその他のアクションなど、Teams 固有のイベントと相互作用を処理します。 Teams SDK v2 では、ハンドラーはクラス継承ではなく、 App インスタンスに直接登録されます。

• エージェント ロジック: App オブジェクトは、エージェントの会話ロジックを格納し、ユーザー入力に基づいて意思決定を行います。 受信アクティビティは、アクティビティの種類とオプションのパターン マッチングに基づいて、適切なハンドラーにルーティングされます。

Teams アクティビティ ハンドラー

アクティビティ ハンドラーは、エージェントの機能の中核であり、ユーザー操作の管理と処理を行います。 Teams SDK v2 で次の手順を実行します。

• App オブジェクトをインスタンス化し、そのオブジェクトにハンドラーを登録します。
• ハンドラーは、型指定されたコンテキスト オブジェクト (TypeScript ではIActivityContext 、C# では IContext<TActivity> 、Python では ActivityContext[TActivity] ) を受け取ります。
• 応答とプロアクティブ メッセージは、 ctx.reply() または ctx.send()経由で送信されます。

Teams エージェントがアクティビティを受け取ると、SDK は登録されたハンドラーを介してアクティビティをルーティングします。 Teams 固有のイベント (チャネル ライフサイクル、メンバーの変更など) は個別の名前付きイベントとして表示されるため、手動で channelData.eventType を検査する必要はありません。

注:

エージェント アクティビティの処理に 15 秒以上かかる場合、Teams はエージェント エンドポイントに再試行要求を送信するため、重複した要求が表示される場合があります。

アクティビティ ハンドラーのコード スニペット

次のスニペットは、チャネル イベントとチーム ライフサイクル イベントの Teams アクティビティ ハンドラーを示しています。

TypeScript

エージェントは、 @microsoft/teams.apps パッケージを使用して構築されます。 Appをインスタンス化し、ハンドラーを app.on(eventName, handler) に登録します。 SDK は、イベント名の文字列に基づいてアクティビティを正しいハンドラーにルーティングします。

channelCreated

import { App } from '@microsoft/teams.apps';

const app = new App();

app.on('channelCreated', async ({ activity }) => {
  const channel = activity.channelData.channel; // { id, name }
  const team    = activity.channelData.team;    // { id, name }
  // Code logic here
});

channelDeleted

app.on('channelDeleted', async ({ activity }) => {
  // Code logic here
});

channelRenamed

app.on('channelRenamed', async ({ activity }) => {
  // Code logic here
});

teamRenamed

app.on('teamRenamed', async ({ activity }) => {
  // Code logic here
});

membersAdded / membersRemoved

app.on('membersAdded', async ({ activity, send }) => {
  for (const member of activity.membersAdded) {
    await send(`Welcome, ${member.name}!`);
  }
});

app.on('membersRemoved', async ({ activity }) => {
  // Code logic here
});

messageUpdate / messageDelete

メッセージの編集は、 messageUpdateとして表示されます。 論理的な削除は messageDelete として表示されます。 activity.channelData.eventType は 'softDeleteMessage'されます。

app.on('messageUpdate', async ({ activity }) => {
  // Code logic here
});

app.on('messageDelete', async ({ activity }) => {
  // activity.channelData.eventType === 'softDeleteMessage' for soft deletes
  // Code logic here
});

C#

エージェントは、 Microsoft.Teams.Apps パッケージを使用して構築されます。 OnMessage()、OnChannelCreated()などの拡張メソッドを使用して、Appとチェーン ハンドラーの登録をインスタンス化します。すべてのハンドラーは、IContext<TActivity> オブジェクトを受け取ります。

OnChannelCreated

using Microsoft.Teams.Apps;

var app = new App();

app.OnChannelCreated(async context => {
    var channel = context.Activity.ChannelData.Channel;
    var team    = context.Activity.ChannelData.Team;
    // Code logic here
});

OnChannelDeleted

app.OnChannelDeleted(async context => {
    // Code logic here
});

OnChannelRenamed

app.OnChannelRenamed(async context => {
    // Code logic here
});

OnTeamRenamed

app.OnTeamRenamed(async context => {
    // Code logic here
});

OnMembersAdded

app.OnMembersAdded(async context => {
    foreach (var member in context.Activity.MembersAdded) {
        // Code logic here
    }
});

OnMembersRemoved

app.OnMembersRemoved(async context => {
    foreach (var member in context.Activity.MembersRemoved) {
        // Code logic here
    }
});

OnMessageUpdate / OnMessageDelete

メッセージの編集は、 OnMessageUpdateを介して処理されます。 論理的な削除は、 OnMessageDelete経由で処理されます。

app.OnMessageUpdate(async context => {
    // Code logic here
});

app.OnMessageDelete(async context => {
    // Code logic here
});

Python

エージェントは、 microsoft-teams-apps パッケージを使用して構築されます。 ハンドラーは、 App インスタンスのデコレーターを使用して登録されます。 各ハンドラーは、ActivityContext[TActivity] オブジェクトを受け取るasync関数です。

on_channel_created

from microsoft_teams.apps import App, ActivityContext
from microsoft_teams.api.activities import ConversationUpdateActivity

app = App()

@app.on_channel_created
async def handle_channel_created(ctx: ActivityContext[ConversationUpdateActivity]):
    channel = ctx.activity.channel_data.channel
    team    = ctx.activity.channel_data.team
    # Code logic here

on_channel_deleted

@app.on_channel_deleted
async def handle_channel_deleted(ctx: ActivityContext[ConversationUpdateActivity]):
    # Code logic here

on_channel_renamed

@app.on_channel_renamed
async def handle_channel_renamed(ctx: ActivityContext[ConversationUpdateActivity]):
    # Code logic here

on_team_renamed

@app.on_team_renamed
async def handle_team_renamed(ctx: ActivityContext[ConversationUpdateActivity]):
    # Code logic here

on_conversation_update (メンバーの追加/削除)

追加および削除されたイベントのメンバーは、 on_conversation_updateを介して処理されます。 ctx.activity.members_addedとctx.activity.members_removedを検査します。

@app.on_conversation_update
async def handle_conversation_update(ctx: ActivityContext[ConversationUpdateActivity]):
    if ctx.activity.members_added:
        for member in ctx.activity.members_added:
            await ctx.send(f"Welcome, {member.name}!")
    if ctx.activity.members_removed:
        # Code logic here

on_edit_message / on_soft_delete_message / on_undelete_message

@app.on_edit_message
async def handle_edit_message(ctx: ActivityContext):
    # Code logic here

@app.on_soft_delete_message
async def handle_soft_delete_message(ctx: ActivityContext):
    # Code logic here

@app.on_undelete_message
async def handle_undelete_message(ctx: ActivityContext):
    # Code logic here

エージェント アクティビティ ハンドラーの例

次のコードは、エージェント アクティビティの例を示しています。

TypeScript

import { App } from '@microsoft/teams.apps';

const app = new App();

app.on('message', async ({ activity, reply }) => {
  const senderName = activity.from.name;
  await send(`Hello <at>${senderName}</at>.`);
});

app.start().catch(console.error);

C#

using Microsoft.Teams.Apps.Activities;
using Microsoft.Teams.Apps.Extensions;
using Microsoft.Teams.Plugins.AspNetCore.DevTools.Extensions;
using Microsoft.Teams.Plugins.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.AddTeams().AddTeamsDevTools();
var app = builder.Build();
var teams = app.UseTeams();

teams.OnMessage(async (context, cancellationToken) =>
{
    var senderName = context.Activity.From.Name;
    await context.Send($"Hello <at>{senderName}</at>.", cancellationToken);
});

app.Run();

Python

import asyncio
from microsoft_teams.apps import App, ActivityContext
from microsoft_teams.api import MessageActivity

app = App()

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    sender_name = ctx.activity.from_property.name
    await ctx.send(f"Hello <at>{sender_name}</at>.")

if __name__ == "__main__":
    asyncio.run(app.start())

エージェント ロジック

エージェント ロジックには、エージェントのアクションと相互作用を決定する基本的なルールと意思決定フレームワークが組み込まれています。 エージェントがユーザー入力を解釈し、応答を作成し、会話に参加する方法について説明します。

Teams SDK v2 では、エージェント ロジックは 1 つ以上のエージェント チャネルからの受信アクティビティを処理し、送信アクティビティを生成します。 すべてのアクティビティ ルーティングは、 App インスタンスによって処理されます。ハンドラーを登録すると、SDK によってアクティビティが自動的にディスパッチされます。

TypeScript

コア アクティビティ ハンドラー

app.on()でサポートされているイベント名の一覧には、次のものが含まれます。

イベント	イベント名の文字列	説明
任意のアクティビティの種類を受信しました	'activity'	すべてのアクティビティに対して呼び出される Catch-all ハンドラー。
メッセージ アクティビティを受信しました	'message'	受信テキスト メッセージを処理します。 正規表現の照合には app.message(pattern, handler) を使用します。
受信した会話の更新	'conversationUpdate'	未加工の会話更新アクティビティ。
インストールの追加	'install.add'	エージェントがインストールされました。
インストールが削除されました	'install.remove'	エージェントがアンインストールされました。
メンバーが追加されました	'membersAdded'	1 人以上のメンバーが会話に参加しました。
削除されたメンバー	'membersRemoved'	1 人以上のメンバーが会話を終了しました。
編集されたメッセージ	'messageUpdate'	会話内のメッセージが編集されました。
論理的に削除されたメッセージ	'messageDelete'	メッセージが論理的に削除されました (activity.channelData.eventType === 'softDeleteMessage')。
受信した開封確認	'readReceipt'	開封確認メッセージが受信されました。

Teams 固有のイベント ハンドラー

app.on() では、次の Teams 固有のイベント名文字列がサポートされています。

イベント	イベント名の文字列	説明
channelCreated	'channelCreated'	Teams チャネルが作成されました。
channelDeleted	'channelDeleted'	Teams チャネルが削除されました。
channelRenamed	'channelRenamed'	Teams チャネルの名前が変更されました。
channelRestored	'channelRestored'	Teams チャネルが復元されました。
channelMemberAdded	'channelMemberAdded'	メンバーがチャネルに追加されました。
channelMemberRemoved	'channelMemberRemoved'	メンバーがチャネルから削除されました。
teamRenamed	'teamRenamed'	チームの名前が変更されました。
teamArchived	'teamArchived'	チームはアーカイブされました。
teamDeleted	'teamDeleted'	チームが削除されました。
teamRestored	'teamRestored'	チームが復元されました。
会議の開始	'meetingStart'	会議が開始されました。
会議が終了しました	'meetingEnd'	会議が終了しました。
参加している参加者	'meetingParticipantJoin'	参加者が会議に参加しました。
参加者が左へ	'meetingParticipantLeave'	参加者が会議を離れた。

Teams の呼び出しアクティビティ

次の表に、 app.on()で使用できる呼び出しアクティビティ ハンドラーの一覧を示します。

呼び出しの種類	イベント名の文字列	説明
CardAction.Invoke	'card.action'	カード アクション呼び出しアクティビティが受信されました (adaptiveCard/action)。
signin/verifyState	SDK によって自動的に処理される (OAuth フロー)	サインインの状態の確認アクティビティ。
task/fetch	'dialog.open'	ダイアログ (タスク モジュール) がフェッチされました。
task/submit	'dialog.submit'	ダイアログ (タスク モジュール) が送信されました。

C#

コア アクティビティ ハンドラー

App クラスは、ハンドラーを登録するための拡張メソッドを公開します。 メソッドは、fluent チェーンの App を返します。

イベント	拡張メソッド	説明
任意のアクティビティの種類を受信しました	OnActivity(handler)	すべてのアクティビティに対して呼び出される Catch-all ハンドラー。
メッセージ アクティビティを受信しました	OnMessage(handler)	受信テキスト メッセージを処理します。 パターン マッチングの最初の引数として正規表現文字列を渡します。
受信した会話の更新	OnConversationUpdate(handler)	未加工の会話更新アクティビティ。
エージェント以外のメンバーが参加している	OnMembersAdded(handler)	MembersAdded.Length > 0時に起動します。
エージェント以外のメンバーが左	OnMembersRemoved(handler)	MembersRemoved.Length > 0時に起動します。
インストールの追加	OnInstall(handler)	エージェントがインストールされました。

Teams 固有のアクティビティ ハンドラー

イベント	拡張メソッド	説明
チャネルを作成しました	OnChannelCreated(handler)	Teams チャネルが作成されました。
チャネルが削除されました	OnChannelDeleted(handler)	Teams チャネルが削除されました。
チャネルの名前が変更されました	OnChannelRenamed(handler)	Teams チャネルの名前が変更されました。
チャットの名前が変更されました	OnTeamRenamed(handler)	チームの名前が変更されました。
編集されたメッセージ	OnMessageUpdate(handler)	メッセージが編集されました。
論理的に削除されたメッセージ	OnMessageDelete(handler)	メッセージが論理的に削除されました。

Teams の呼び出しアクティビティ

呼び出しの種類	拡張メソッド	説明
CardAction.Invoke	OnExecuteAction(handler)	カード アクション呼び出しアクティビティが受信されました。
task/fetch	OnTaskFetch(handler)	ダイアログ (タスク モジュール) がフェッチされました。
task/submit	OnTaskSubmit(handler)	ダイアログ (タスク モジュール) が送信されました。
fileConsent/invoke	OnFileConsent(handler)	アクティビティカードファイルの同意を受け取った。
signin/verifyState	SDK によって自動的に処理される (OAuth フロー)	サインインの状態の確認アクティビティ。

Python

コア アクティビティ ハンドラー

App クラスは、デコレーター スタイルのハンドラー登録を公開します。

イベント	デコレータ	説明
受信したアクティビティ	@app.on_activity	すべてのアクティビティの Catch-all ハンドラー。
受信したメッセージ	@app.on_message	受信テキスト メッセージを処理します。
パターンを含むメッセージ	@app.on_message_pattern(re.compile(...))	正規表現パターンに一致するメッセージを処理します。
会話の更新	@app.on_conversation_update	未加工の会話の更新。チェック members_added / members_removed。
インストールの追加	@app.on_install_add	エージェントがインストールされました。
インストールが削除されました	@app.on_install_remove	エージェントがアンインストールされました。

Teams 固有のアクティビティ ハンドラー

イベント	デコレータ	説明
チャネルを作成しました	@app.on_channel_created	Teams チャネルが作成されました。
チャネルが削除されました	@app.on_channel_deleted	Teams チャネルが削除されました。
チャネルの名前が変更されました	@app.on_channel_renamed	Teams チャネルの名前が変更されました。
チャットの名前が変更されました	@app.on_team_renamed	チームの名前が変更されました。
編集されたメッセージ	@app.on_edit_message	メッセージが編集されました。
論理的に削除されたメッセージ	@app.on_soft_delete_message	メッセージが論理的に削除されました。
メッセージが削除されていない	@app.on_undelete_message	削除されたメッセージが復元されました。
会議の開始	@app.on_meeting_start	会議が開始されました。
会議が終了しました	@app.on_meeting_end	会議が終了しました。
参加している参加者	@app.on_meeting_participant_join	参加者が会議に参加しました。
参加者が左へ	@app.on_meeting_participant_leave	参加者が会議を離れた。

Teams の呼び出しアクティビティ

呼び出しの種類	デコレータ	説明
CardAction.Invoke	@app.on_card_action	カード アクション呼び出しアクティビティが受信されました。
task/fetch	@app.on_dialog_open	ダイアログ (タスク モジュール) がフェッチされました。
task/submit	@app.on_dialog_submit	ダイアログ (タスク モジュール) が送信されました。
fileConsent/invoke	@app.on_file_consent	アクティビティカードファイルの同意を受け取った。
signin/verifyState	SDK によって自動的に処理される (OAuth フロー)	サインインの状態の確認アクティビティ。

エージェント アクティビティ ハンドラーに慣れたので、会話と、受信または送信するメッセージに応じてエージェントの動作がどのように異なるかを確認しましょう。

推奨事項

エージェントとユーザーの間の広範なダイアログは、タスクを完了するための遅くて複雑な方法です。 過剰なコマンド (特に幅広いコマンド) をサポートするエージェントは、成功しないか、ユーザーによって肯定的に表示されます。

• チャットでのマルチターン エクスペリエンスを回避 する広範なダイアログでは、開発者が状態を維持する必要があります。 この状態を終了するには、ユーザーがタイムアウトするか、[ キャンセル] を選択する必要があります。 また、このプロセスは面倒です。 たとえば、次の会話シナリオを参照してください。

  ユーザー: Megan との会議をスケジュールして。

  エージェント: 200 件の結果が見つかりました。姓と名を含めます。

  ユーザー: Megan Bowen との会議をスケジュールして。

  エージェント: 何時にミーガン・ボーエンと会いたいですか?

  ユーザー: 午後 1 時に。

  エージェント: どの日ですか?

• 6 つ以下のコマンドをサポート する現在のエージェント メニューには表示されるコマンドが 6 つしかないため、それ以上のコマンドを頻度で使用する可能性は低くなります。 広範なアシスタントの仕事と運賃をより良くしようとするのではなく、特定の領域に深く入り込むエージェント。

• より迅速な対話のためにサポート情報のサイズを最適化する エージェントの欠点の 1 つは、ランクなしの応答で大きな取得サポート情報を維持することが困難であるということです。 エージェントは、短くて迅速な対話に最適であり、回答を探している長いリストを調べることはありません。

注:

Teams プラットフォームでは、トランスポート層セキュリティ (TLS) バージョン 1.2 のみがサポートされています。 それに応じてエージェント環境を構成してください。

その他のエージェント機能を調べる

従来のエージェント機能に加えて、Teams エージェント アプリで使用できる高度な機能を調べることができます。

• エージェントの Teams 固有のコンテキストを取得します。
• 通話およびオンライン会議エージェント。
• アプリの SSO を有効にします。

コード サンプル

サンプルの名前	説明	TypeScript	C#	Python
Teams 会話エージェント	このアプリは、基本的なエージェント イベントを示します。	表示	表示	表示