エージェントのチャネルとグループ チャットの会話

ユーザーがチームまたはグループ チャットにエージェントをインストールできるようにするには、 teams または groupchat スコープを追加します。 これにより、会話のすべてのメンバーがエージェントと対話できるようになります。 エージェントがインストールされると、会話メンバーの一覧など、会話に関するメタデータにアクセスできます。 また、チームにインストールされている場合、エージェントは、そのチームに関する詳細とチャネルの完全なリストにアクセスできます。

既定では、グループ チャットとチャネルのエージェントは、直接 @mentionedされている場合にのみメッセージを受信します。 会話に送信された他のメッセージは受信されません。 たとえば、チームまたはチャネルがメンションされたとき、または誰かがエージェントからメッセージに返信しても、エージェントはメッセージを @mentioning せずにメッセージを受け取りません。 Teams SDK には、@mention イベントを処理するための専用のmention アクティビティ ルートが用意されています。

デザインのガイドライン

グループ チャットとチャネルでは、明確な価値、簡潔な応答、最小限のノイズを使用して、コラボレーション会話用にエージェントを設計します。

スレッド化された会話

app.OnMessage(async (context, cancellationToken) =>
{
    // Send in the same thread, no quote
    await context.Send("Acknowledged", cancellationToken);

    // Send in the same thread with a visual quote of the inbound message
    await context.Reply("Got it!", cancellationToken);
});

app.on('message', async ({ send, reply }) => {
  // Send in the same thread, no quote
  await send('Acknowledged');

  // Send in the same thread with a visual quote of the inbound message
  await reply('Got it!');
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Send in the same thread, no quote
    await ctx.send("Acknowledged")

    # Send in the same thread with a visual quote of the inbound message
    await ctx.reply("Got it!")

メッセージをスレッドにプロアクティブに送信する方法については、「 プロアクティブ メッセージ」を参照してください。

インストール時にメッセージを送信する

エージェントが最初にグループまたはチームに追加されると、 install.add ライフサイクル ルートを使用して概要メッセージを送信できます。 詳細については、「 プロアクティブ メッセージング」を参照してください。

概要メッセージを送信する場合は、エージェントの機能とその使用方法の簡単な説明を含めます。

インストール中に conversationId を格納して、後で プロアクティブ メッセージングを 有効にすることもできます。

次のコードは、インストール時にウェルカム メッセージを送信する例を示しています。

app.OnInstall(async context => 
{ 
    await context.Send("Hello! I'm your agent. Here's what I can do..."); 
}); 

app.on('install.add', async ({ send }) => 
{ 
    await send('Hello! I\'m your agent. Here\'s what I can do...'); 
}); 

@app.on_install_add 
async def handle_install_add(ctx: ActivityContext[InstalledActivity]): 
    await ctx.send("Hello! I'm your agent. Here's what I can do...") 

エージェントがチームまたはグループ チャットにインストールされている場合は、事前にウェルカム メッセージをユーザーに個別に送信しないでください。 ウェルカム メッセージを送信する場合は、インストールされている会話に投稿し、エージェントを追加したユーザーをメンションします。

次の場合はメッセージを送信しないでください。

• チームが大きい場合 (たとえば、100 人を超えるメンバー)。 エージェントはスパムと見なされ、エージェントを追加したユーザーが苦情を受け取る可能性があります。 ウェルカム メッセージを表示するすべてのユーザーに、エージェントの価値提案を明確に伝える必要があります。
• エージェントは、最初にチームに追加されるのではなく、グループまたはチャネルで最初にメンションされます。
• グループまたはチャネルの名前が変更される。
• チーム メンバーがグループまたはチャネルに追加される。

メンションの操作

グループ チャットとチャネルでは、エージェント@mentionメッセージには、メッセージ テキストにメンション エンティティが含まれます。 RSC など、すべてのメッセージを受信するようにエージェントが構成されている場合、一部の受信メッセージに @mentionが含まれていない可能性があります。 エージェントは、メッセージに記載されている他のユーザーを取得し、送信するメッセージにメンションを追加できます。 グループ チャットのエージェントは、 @mentionを使用してユーザーメンションを有効にしますが、メンションの @everyone はサポートされていません。

@mentionsを含むメッセージの場合、メッセージ テキストには<at>@agentname</at>などのメンションマークアップが含まれます。

メンションを取得する

メンションは、アクティビティ ペイロードの entities オブジェクトで返され、ユーザーの一意の ID と、メンションされたユーザーの名前の両方が含まれます。 メッセージのテキストには、<at>@John Smith<at>などのメンションも含まれます。 ただし、メッセージ内のテキストを使用してユーザーに関する情報を取得しないでください。 メッセージを送信するユーザーがメッセージを変更する可能性があります。 したがって、 entities オブジェクトを使用します。

mentionに設定されているエントリに対してアクティビティ内のentities配列をフィルター処理することで、メッセージ内のすべてのメンションtype取得できます。

次のコードは、メンションを取得する例を示しています。

app.OnMessage(async context =>
{
    var mentions = context.Activity.Entities?
        .Where(e => e.Type == "mention")
        .ToList();

    if (mentions != null && mentions.Any())
    {
        var firstMention = mentions[0].Properties["mentioned"]?["name"]?.ToString();
        await context.Send($"Hello {firstMention}");
    }
    else
    {
        await context.Send("Aw, no one was mentioned.");
    }
});

app.on('message', async ({ activity, send }) => {
    const mentions = activity.entities?.filter(e => e.type === 'mention');

    if (mentions && mentions.length > 0) {
        const firstMention = mentions[0].mentioned;
        await send(`Hello ${firstMention.name}.`);
    } else {
        await send('Aw, no one was mentioned.');
    }
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    mentions = [e for e in (ctx.activity.entities or []) if e.type == "mention"]

    if mentions:
        first_mention = mentions[0].mentioned
        await ctx.send(f"Hello {first_mention.name}")
    else:
        await ctx.send("Aw, no one was mentioned.")

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

チェックとストリップ @mention

チャネルとグループ チャットでは、ユーザーは通常、 @mentionを使用してエージェントまたはアプリに対処します。 メッセージを解釈する前に、メンションがエージェントまたはアプリを対象としていることをチェックしてから、メンションテキストを削除し、空白文字をトリミングします。 これにより、ユーザーのコマンドまたは処理のプロンプトのみが表示されます。

メンションを削除すると、エージェントまたはアプリ名がコマンドの一致、意図認識、検索、または自然言語処理を妨げることがなくなります。 また、同じハンドラーが個人用チャット、グループ チャット、チャネル全体でメッセージを一貫して処理することもできます。 他のメンションがユーザーの要求の一部である場合は保持します。

string StripMentions(MessageActivity msg)
{
    var text = msg.Text ?? "";
    if (msg.Entities == null) return text;

    foreach (var entity in msg.Entities)
    {
        if (entity is MentionEntity mention && mention.Text != null)
        {
            text = text.Replace(mention.Text, "");
        }
    }

    return text.Trim();
}

app.on('message', async ({ activity, send }) => {
  const clean = activity.stripMentionsText().text;
  await send(`You said: ${clean}`);
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    clean = ctx.activity.strip_mentions_text().text
    await ctx.send(f"You said: {clean}")

メッセージにメンションを追加する

エージェントは、チャネルに投稿されたメッセージ内の他のユーザーをメンションできます。 メッセージにメンションをインラインで含める場合は、メッセージ テキストにメンションを配置し、メンションの詳細をエンティティ配列に追加します。 メンション エンティティの text フィールドは、メッセージ本文の正確なテキストと一致する必要があります。

次のコードは、メッセージにメンションを追加する例を示しています。

app.OnMessage(async context =>
{
    var user = context.Activity.From;
    var message = new MessageActivity($"Hello <at>{user.Name}</at>!").AddMention(user);
    await context.Send(message);
});

app.on('message', async ({ send, activity }) => {
    const user = activity.from;
    const message = new MessageActivity(`Hello <at>${user.name}</at>!`).addMention(user);
    await send(message);
});

@app.on_message 
async def handle_message(ctx: ActivityContext[MessageActivity]): 
    await ctx.send(MessageActivityInput(text="Hello!").add_mention(account=ctx.activity.from_))

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

また、Microsoft Entra オブジェクト ID またはユーザー プリンシパル名 (UPN) でユーザーをメンションし、チャネル メッセージのタグをメンションすることもできます。

ユーザー メンションでのMicrosoft Entra オブジェクト ID と UPN のサポート

ボットは、ユーザー ID に加えて、オブジェクト ID またはユーザー プリンシパル名 (UPN) をMicrosoft Entraすることで、ユーザーをメンションできます。 受信 Webhook では、これらの ID 型を使用したアダプティブ カードでのユーザーメンションもサポートされます。

次のコード スニペットは、Teams SDK を使用して、Entra オブジェクト ID と UPN を持つユーザーにメンションする例を示しています。

app.OnMessage(async context =>
{
    // Mention a user by their User Principal Name (UPN)
    var user = new Account { Id = "Adele@microsoft.com", Name = "Adele" };
    await context.Send(new MessageActivity("Hello!").AddMention(user));
});

app.on('message', async ({ send }) => {
    // Mention a user by their User Principal Name (UPN)
    const user = { id: 'Adele@microsoft.com', name: 'Adele' };
    await send(new MessageActivity('Hello!').addMention(user));
});

from microsoft_teams.api import Account, MessageActivityInput

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Mention a user by their User Principal Name (UPN)
    user = Account(id="Adele@microsoft.com", name="Adele")
    await ctx.send(MessageActivityInput(text="Hello!").add_mention(account=user))

{
    "type": "mention",
    "text": "<at>Adele</at>",
    "mentioned": {
            "id": "Adele@microsoft.com",
            "name": "Adele"
    }
}

タグ メンション

エージェントは、テキスト メッセージとチャネルに投稿されたアダプティブ カードのタグをメンションできます。 エージェントがチャネル内のタグを @mentions すると、タグが強調表示され、タグに関連付けられているユーザーに通知されます。 ユーザーがタグの上にマウス ポインターを合わせると、タグの詳細が表示されたポップアップが表示されます。

テキスト メッセージ内のタグをメンションする

タグをメンションするには、メッセージに"type": "tag"を含むメンション エンティティを含めます。 id フィールドは、list teamworkTags API の base64 でエンコードされたタグ ID である必要があります。

app.OnMessage(async context =>
{
    // Mention a tag using the tag's Graph API ID
    var tag = new Account { Id = "<base64-encoded-tag-id>", Name = "Test Tag" };
    await context.Send(new MessageActivity("Hello!").AddMention(tag));
});

app.on('message', async ({ send }) => {
    // Mention a tag using the tag's Graph API ID
    const tag = { id: '<base64-encoded-tag-id>', name: 'Test Tag' };
    await send(new MessageActivity('Hello!').addMention(tag));
});

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Mention a tag using the tag's Graph API ID
    tag = Account(id="<base64-encoded-tag-id>", name="Test Tag")
    await ctx.send(MessageActivityInput(text="Hello!").add_mention(account=tag))

アダプティブ カードのタグをメンションする

アダプティブ カード スキーマの mentioned オブジェクトの下に、 "type": "tag" プロパティを追加します。 "type": "tag" プロパティが追加されていない場合、エージェントはメンションをユーザー メンションとして扱います。

チャネルで使用可能なタグの一覧は、 list teamworkTags API を使用して取得できます。

例:

{
    "type": "mention",
    "text": "<at>Test Tag</at>",
    "mentioned": {
            "id": "base64 encoded id",
            "name": "Test Tag",
            "type": "tag"
    }
}

クエリ パラメーター

エラー コード

制限の調整

スコープ、ウィンドウの種類 (短と長)、メッセージごとのタグ数、その他の要因に応じて、要求を複数の制限に対して評価できます。 最初に到達した上限に達すると、トリガーの調整が行われます。

メッセージ配信の失敗を回避するために、調整の制限を超えないようにします。 たとえば、エージェントは 5 秒間のウィンドウでタグ メンションを持つ 2 つのメッセージのみを送信でき、各メッセージに含めることができるタグは最大 10 個です。

次の表に、エージェント内のタグメンションの調整制限を示します。

制限事項

• タグメンションは、テキストとアダプティブ カードを使用したエージェントからクライアントへのメッセージ フローでのみサポートされます。
• タグメンションは、共有チャネルとプライベート チャネルではサポートされていません。
• タグメンションはコネクタではサポートされていません。
• タグメンションでは、エージェントの呼び出しフローはサポートされていません。

次の手順

関連項目

• Teams SDK - API クライアント
• Teams SDK - Microsoft Graph 統合
• グループ会話でターゲット メッセージを送受信する
• エージェントとアプリからスラッシュ コマンドを公開する
• ユーザーの代わりにプライベート チャネルを作成する
• Teams SDK - Teams 統合の概要