Obtenha o contexto específico do Teams para o seu agente

Um agente pode acessar dados de contexto adicionais sobre a equipe ou chat onde ele está instalado. Essas informações podem ser usadas para personalizar respostas e criar fluxos de trabalho mais avançados.

Buscar a lista ou perfil de usuário

O agente pode consultar a lista de membros da equipe ou chat atual e usar esses dados para personalizar respostas ou direcionar ações de acompanhamento.

Use a API de membros de conversas do SDK do Teams para recuperar informações de lista.

Para recuperação de membro da conversa:

  • Tamanho mínimo da página: 50
  • Tamanho de página padrão: 200
  • Tamanho máximo da página: 500

Não use a recuperação de membro não paginada em equipes e canais. Para grandes listas, as chamadas não paginadas podem ser incompletas ou limitadas.

Observação

  • A paginação está disponível em conversas de equipe e canal.
  • Não há suporte para paginação em conversas de chat. Nos chats, a lista completa é retornada pelo serviço.

O código de exemplo a seguir usa a recuperação de membro paginado:

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

Depois de buscar a lista, você pode obter detalhes de um único membro.

Obter detalhes de membro único

Você pode recuperar detalhes de um membro específico usando identificadores de usuário do contexto da atividade.

O código de exemplo a seguir usa APIs do SDK do Teams:

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)

Depois de obter os detalhes de um membro, você pode recuperar os detalhes da equipe.

Obter detalhes da equipe

Quando instalado em uma equipe, o agente pode consultar metadados como a ID da equipe e a ID do grupo do Microsoft Entra.

O código de exemplo a seguir usa APIs do SDK do Teams:

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)

Depois de obter os detalhes da equipe, você pode obter a lista de canais dessa equipe.

Obter a lista de canais em uma equipe

O agente pode consultar a lista de canais em uma equipe.

Observação

  • O nome do canal geral padrão é retornado como null para permitir a localização.
  • A ID do canal para o canal Geral sempre corresponde à ID da equipe.

O código de exemplo a seguir é usado para obter a lista de canais em uma equipe:

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)

Se você precisar de pontos de extremidade REST do conector bruto, use a API do SDK do Teams para a maioria dos cenários de agente e use o REST diretamente para casos avançados que não são cobertos por abstrações do SDK.

Próxima etapa

Enviar e receber arquivos usando o agente

Confira também

  • Last updated on