エージェントの Teams 固有のコンテキストを取得する

エージェントは、チームに関する追加のコンテキスト データにアクセスしたり、インストールされている場所でチャットしたりできます。 この情報を使用して、応答をカスタマイズし、より豊富なワークフローを構築できます。

名簿またはユーザー プロファイルをフェッチする

エージェントは、現在のチームまたはチャットのメンバーの一覧を照会し、そのデータを使用して応答またはターゲットのフォローアップ アクションをカスタマイズできます。

Teams SDK 会話メンバー API を使用して、名簿情報を取得します。

会話メンバー取得の場合:

  • 最小ページ サイズ: 50
  • 既定のページ サイズ: 200
  • 最大ページ サイズ: 500

チームとチャネルでページ分割されていないメンバー取得を使用しないでください。 大規模な名簿の場合、ページ分割されていない呼び出しが不完全または調整される可能性があります。

注:

  • 改ページは、チームとチャネルの会話で使用できます。
  • チャットの会話では、改ページはサポートされていません。 チャットでは、完全な名簿がサービスによって返されます。

次のサンプル コードでは、ページングされたメンバー取得を使用します。

app.OnMessage(async (context, cancellationToken) =>
{
    var membersClient = context.Api.Conversations.Members;
    var allMembers = new List<TeamsChannelAccount>();
    string? continuationToken = null;

    do
    {
        var page = await membersClient.GetPagedAsync(
            context.Conversation.Id,
            pageSize: 50,
            continuationToken: continuationToken,
            cancellationToken: cancellationToken
        );

        allMembers.AddRange(page.Members.Where(m => m is not null).Select(m => m!));
        continuationToken = page.ContinuationToken;
    }
    while (!string.IsNullOrEmpty(continuationToken));
});

app.on("message", async ({ activity, api }) => {
  const membersClient = api.conversations.members(activity.conversation.id);
  const allMembers = [];
  let continuationToken = undefined;

  do {
    const page = await membersClient.getPaged({
      pageSize: 50,
      continuationToken,
    });

    allMembers.push(...page.members);
    continuationToken = page.continuationToken;
  } while (continuationToken);
});

@app.on_message
async def list_members(ctx: ActivityContext[MessageActivity]) -> None:
    members_client = ctx.api.conversations.members(ctx.activity.conversation.id)

    all_members = []
    continuation_token: str | None = None

    while True:
        result = await members_client.get_paged(
            page_size=50,
            continuation_token=continuation_token,
        )
        all_members.extend(result.members)

        if not result.continuation_token:
            break

        continuation_token = result.continuation_token

名簿をフェッチすると、1 人のメンバーの詳細を取得できます。

単一のメンバーの詳細を取得する

アクティビティ コンテキストからユーザー識別子を使用して、特定のメンバーの詳細を取得できます。

次のサンプル コードでは、Teams SDK API を使用します。

app.OnMessage(async (context, cancellationToken) =>
{
    var memberId = context.Activity.From?.Id;
    if (string.IsNullOrEmpty(memberId))
    {
        return;
    }

    var member = await context.Api.Conversations.Members.GetByIdAsync(
        context.Conversation.Id,
        memberId,
        cancellationToken: cancellationToken
    );
});

app.on("message", async ({ activity, api }) => {
    const memberId = activity.from?.id;
    if (!memberId) {
        return;
    }

    const member = await api.conversations
        .member.getById(activity.conversation.id, memberId);
});

@app.on_message
async def get_member(ctx: ActivityContext[MessageActivity]) -> None:
    member_id = ctx.activity.from_.id
    member = await ctx.api.conversations.member.get_by_id(ctx.activity.conversation.id, member_id)

メンバーの詳細を取得したら、チームの詳細を取得できます。

チームの詳細を取得する

チームにインストールすると、エージェントはチーム ID やMicrosoft Entra グループ ID などのメタデータに対してクエリを実行できます。

次のサンプル コードでは、Teams SDK API を使用します。

app.OnMessage(async (context, cancellationToken) =>
{
    var teamId = context.Activity.ChannelData?.Team?.Id;
    if (string.IsNullOrEmpty(teamId))
    {
        return;
    }

    var team = await context.Api.Teams.GetByIdAsync(
        teamId,
        cancellationToken: cancellationToken
    );
});

app.on("message", async ({ activity, api }) => {
    const teamId = activity.channelData?.team?.id;
    if (!teamId) {
        return;
    }

    const team = await api.teams.getById(teamId);
});

@app.on_message
async def get_team_details(ctx: ActivityContext[MessageActivity]) -> None:
    team_id = ctx.activity.channel_data.team.id
    team = await ctx.api.teams.get_by_id(team_id)

チームの詳細を取得したら、そのチームのチャネルの一覧を取得できます。

チーム内のチャネルの一覧を取得します。

エージェントは、チーム内のチャネルの一覧を照会できます。

注:

  • ローカリゼーションを可能にするために、既定の一般チャネルの名前が null として返されます。
  • 一般チャネルのチャネル ID は、常にチーム ID と一致します。

次のサンプル コードは、チーム内のチャネルのリストを取得するために使用されます。

app.OnMessage(async (context, cancellationToken) =>
{
    var teamId = context.Activity.ChannelData?.Team?.Id;
    if (string.IsNullOrEmpty(teamId))
    {
        return;
    }

    var channels = await context.Api.Teams.GetConversationsAsync(
        teamId,
        cancellationToken: cancellationToken
    );
});

app.on("message", async ({ activity, api }) => {
  const teamId = activity.channelData?.team?.id;
  if (!teamId) {
    return;
  }

  const channels = await api.teams.getConversations(teamId);
});

@app.on_message
async def list_channels(ctx: ActivityContext[MessageActivity]) -> None:
    team_id = ctx.activity.channel_data.team.id
    channels = await ctx.api.teams.get_conversations(team_id)

未加工のコネクタ REST エンドポイントが必要な場合は、ほとんどのエージェント シナリオで Teams SDK API を使用し、SDK の抽象化でカバーされていない高度なケースにのみ REST を直接使用します。

次の手順

エージェントを使用してファイルを送受信する

関連項目

  • Last updated on