Entender os conceitos do agente

As interações de um agente podem ser usando texto, fala, imagens ou vídeo. Ele processa a entrada do usuário para entender sua solicitação e avalia a entrada para executar tarefas relevantes. Um agente pode solicitar informações ou habilitar o acesso a serviços e responde ao usuário.

Escopos do agente

Os agentes no Microsoft Teams podem fazer parte de uma conversa individual, um chat em grupo ou um canal em uma equipe. Cada escopo oferece oportunidades e desafios únicos para seu agente de conversação.

Em um canal.	Em um chat em grupo	Chat Privado
Alcance enorme	Menos membros	Maneira tradicional
Interações individuais concisas	@mention para o agente	Agentes de P&R
@mention para o agente	Semelhante ao canal	Agentes que contam piadas e fazem anotações

Em um canal.

Os canais contêm conversas encadeadas entre várias pessoas, até 2000. Isso potencialmente dá ao seu agente um alcance massivo, mas as interações individuais devem ser concisas. As interações tradicionais com várias voltas não funcionam. Em vez disso, você deve procurar usar cartões interativos ou caixas de diálogo (chamados de módulos de tarefa no TeamsJS v1.x) ou mover a conversa para uma conversa individual para coletar muitas informações. Seu agente só tem acesso às mensagens onde está @mentioned. Você pode recuperar mensagens adicionais da conversa usando as permissões do Microsoft Graph no nível da organização.

Os agentes funcionam melhor em um canal nos seguintes casos:

Notificações, em que você fornece um cartão interativo para os usuários obterem informações adicionais.
Comentários cenários como votações e pesquisas.
Um único ciclo de solicitação ou resposta resolve interações e os resultados são úteis para vários membros da conversa.
Agentes sociais ou divertidos, onde você obtém uma imagem incrível de gato, escolhe aleatoriamente um vencedor e assim por diante.

Em um chat em grupo

Os chats de grupo são conversas não-encadeadas entre três ou mais pessoas. Tendem a ter menos membros do que um canal e são mais temporários. Semelhante a um canal, seu agente só tem acesso às mensagens em que está @mentioned diretamente.

Os agentes que funcionam melhor em um canal também funcionam melhor em um chat em grupo.

Chat Privado

O chat individual é uma maneira tradicional de um agente de conversação interagir com um usuário. Alguns exemplos de agentes de conversa individuais são:

Agentes de P&R
agentes que iniciam fluxos de trabalho em outros sistemas.
agentes que contam piadas.
agentes que fazem anotações. Antes de criar agentes individuais, considere se uma interface baseada em conversa é a melhor maneira de apresentar sua funcionalidade.

Lógica do manipulador de atividades e do agente

Para criar um aplicativo de agente que atenda às suas necessidades, é essencial entender a lógica do manipulador de atividades e do agente do Microsoft Teams. Esses dois componentes principais trabalham juntos para organizar a lógica conversacional.

Manipulador de atividades do Teams: processa eventos e interações específicos do Teams, como criação de canais, adições de membros da equipe e outras ações exclusivas do ambiente do Teams. No SDK do Teams v2, os manipuladores são registrados diretamente em uma App instância em vez de por herança de classe.
Lógica do agente: o App objeto hospeda a lógica de conversação do agente e é responsável por tomar decisões com base na entrada do usuário. As atividades de entrada são roteadas para o manipulador apropriado com base no tipo de atividade e na correspondência de padrões opcional.

Manipulador de atividades do Teams

O manipulador de atividades é o núcleo da funcionalidade de um agente, gerenciando e processando as interações do usuário. No SDK do Teams v2:

Você instancia um App objeto e registra manipuladores nele.
Os manipuladores recebem um objeto de contexto tipado (IActivityContext em TypeScript, IContext<TActivity> em C#, ActivityContext[TActivity] em Python).
As respostas e as mensagens proativas são enviadas via ctx.reply() ou ctx.send().

Quando um agente do Teams recebe uma atividade, o SDK a roteia por meio do manipulador registrado. Os eventos específicos do Teams (ciclo de vida do canal, alterações de membros etc.) são exibidos como eventos com nomes distintos, portanto, você não precisa inspecionar channelData.eventType manualmente.

Observação

Se uma atividade de agente demorar mais de 15 segundos para ser processada, o Teams enviará uma solicitação de repetição ao ponto de extremidade do agente, para que você possa ver solicitações duplicadas.

Trechos de código do manipulador de atividades

Os snippets a seguir mostram manipuladores de atividades do Teams para eventos de ciclo de vida de equipe e canal.

Os agentes são criados usando o Microsoft.Teams.Apps pacote. Você instancia um App e registra o manipulador de cadeia usando métodos de extensão como OnMessage(), OnChannelCreated(), etc. Todos os manipuladores recebem um IContext<TActivity> objeto.

OnChannelCreated

using Microsoft.Teams.Apps;

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddTeamsBotApplication();

WebApplication app = builder.Build();
TeamsBotApplication teams = app.UseTeamsBotApplication();

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

OnChannelDeleted

teams.OnChannelDeleted(async (context, cancellationToken) =>
{
    // Code logic here
});

OnChannelRenamed

teams.OnChannelRenamed(async (context, cancellationToken) =>
{
    // Code logic here
});

OnTeamRenamed

teams.OnTeamRenamed(async (context, cancellationToken) =>
{
    // Code logic here
});

OnMembersAdded

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

OnMembersRemoved

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

OnMessageUpdate / OnMessageDelete

As edições de mensagens são tratadas via OnMessageUpdate. As exclusões temporárias são manipuladas por meio do OnMessageDelete

teams.OnMessageUpdate(async (context, cancellationToken) =>
{
    // Code logic here
});

teams.OnMessageDelete(async (context, cancellationToken) =>
{
    // Code logic here
});

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

As edições de mensagens são tratadas via OnMessageUpdate. As exclusões temporárias são manipuladas por meio do OnMessageDelete

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

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

Os agentes são criados usando o @microsoft/teams.apps pacote. Você instancia e App registra manipuladores com app.on(eventName, handler). O SDK roteia atividades para o manipulador correto com base na cadeia de caracteres do nome do evento.

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

As edições de mensagens são exibidas como messageUpdate. As exclusões temporárias são exibidas como messageDelete — o activity.channelData.eventType será 'softDeleteMessage'.

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

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

Os agentes são criados usando o microsoft-teams-apps pacote. Os manipuladores são registrados usando decoradores em uma App instância. Cada manipulador é uma async função que recebe um ActivityContext[TActivity] objeto.

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 (membros adicionados / removidos)

Os eventos adicionados e removidos dos membros são tratados via on_conversation_update. Inspecionar ctx.activity.members_added e 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

Exemplo de manipulador de atividade do agente

O código a seguir fornece um exemplo de uma atividade de agente:

using Microsoft.Teams.Apps;

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddTeamsBotApplication();

WebApplication app = builder.Build();
TeamsBotApplication teams = app.UseTeamsBotApplication();

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

app.Run();

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();

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);

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())

Lógica do agente

A lógica do agente incorpora as regras fundamentais e as estruturas de tomada de decisão que ditam as ações e interações de um agente. Ele descreve como o agente interpreta a entrada do usuário, formula respostas e participa de conversas.

No SDK do Teams v2, a lógica do agente processa as atividades de entrada de um ou mais canais do agente e gera as atividades de saída. Todo o App roteamento de atividades é tratado pela instância — você registra os manipuladores e o SDK despacha atividades para eles automaticamente.

Manipuladores de atividades principais

A App classe expõe métodos de extensão para registrar manipuladores. Os métodos retornam App para encadeamento fluente.

Evento	Método de extensão	Descrição
Qualquer tipo de atividade recebida	`OnActivity(handler)`	O manipulador catch-all chamado para todas as atividades.
Atividade de mensagem recebida	`OnMessage(handler)`	Lidar com mensagens de texto de entrada. Passe uma cadeia de caracteres regex como o primeiro argumento para correspondência de padrões.
Atualização de conversa recebida	`OnConversationUpdate(handler)`	Atividade de atualização de conversa bruta.
Membros não agentes ingressaram	`OnMembersAdded(handler)`	Acionado quando `MembersAdded.Length > 0`.
Membros não agentes restantes	`OnMembersRemoved(handler)`	Acionado quando `MembersRemoved.Length > 0`.
Instalação adicionada	`OnInstall(handler)`	O agente foi instalado.

Manipuladores de atividades específicos do Teams

Evento	Método de extensão	Descrição
Canal criado	`OnChannelCreated(handler)`	Foi criado um canal do Teams.
Canal excluído	`OnChannelDeleted(handler)`	Um canal do Teams foi excluído.
Canal renomeado	`OnChannelRenamed(handler)`	Um canal do Teams foi renomeado.
Equipe renomeada	`OnTeamRenamed(handler)`	A equipe foi renomeada.
Mensagem editada	`OnMessageUpdate(handler)`	Uma mensagem foi editada.
Mensagem excluída temporariamente	`OnMessageDelete(handler)`	Uma mensagem foi excluída temporariamente.

Atividades de invocação do Teams

Invocar tipo	Método de extensão	Descrição
`CardAction.Invoke`	`OnExecuteAction(handler)`	Uma atividade de invocação de ação de card foi recebida.
`task/fetch`	`OnTaskFetch(handler)`	Uma caixa de diálogo (módulo de tarefa) foi buscada.
`task/submit`	`OnTaskSubmit(handler)`	Uma caixa de diálogo (módulo de tarefa) foi enviada.
`fileConsent/invoke`	`OnFileConsent(handler)`	Uma atividade de card de consentimento de arquivo foi recebida.
`signin/verifyState`	Manipulado automaticamente pelo SDK (fluxo OAuth)	Atividade de estado de verificação de entrada.

Manipuladores de atividades principais

A lista de nomes de eventos com suporte inclui app.on() o seguinte:

Evento	Cadeia de caracteres de nome do evento	Descrição
Qualquer tipo de atividade recebida	`'activity'`	O manipulador catch-all chamado para todas as atividades.
Atividade de mensagem recebida	`'message'`	Lidar com mensagens de texto de entrada. Use `app.message(pattern, handler)` para correspondência de regex.
Atualização de conversa recebida	`'conversationUpdate'`	Atividade de atualização de conversa bruta.
Instalação adicionada	`'install.add'`	O agente foi instalado.
Instalação removida	`'install.remove'`	O agente foi desinstalado.
Membros adicionados	`'membersAdded'`	Um ou mais membros participaram da conversa.
Membros removidos	`'membersRemoved'`	Um ou mais membros saíram da conversa.
Mensagem editada	`'messageUpdate'`	Uma mensagem na conversa foi editada.
Mensagem excluída temporariamente	`'messageDelete'`	Uma mensagem foi excluída temporariamente (`activity.channelData.eventType === 'softDeleteMessage'`).
Confirmação de leitura recebida	`'readReceipt'`	Uma confirmação de leitura foi recebida.

Manipuladores de eventos específicos do Teams

app.on() dá suporte às seguintes cadeias de caracteres de nome de evento específicas do Teams:

Evento	Cadeia de caracteres de nome do evento	Descrição
`channelCreated`	`'channelCreated'`	Foi criado um canal do Teams.
`channelDeleted`	`'channelDeleted'`	Um canal do Teams foi excluído.
`channelRenamed`	`'channelRenamed'`	Um canal do Teams foi renomeado.
`channelRestored`	`'channelRestored'`	Um canal do Teams foi restaurado.
`channelMemberAdded`	`'channelMemberAdded'`	Um membro foi adicionado a um canal.
`channelMemberRemoved`	`'channelMemberRemoved'`	Um membro foi removido de um canal.
`teamRenamed`	`'teamRenamed'`	A equipe foi renomeada.
`teamArchived`	`'teamArchived'`	A equipe foi arquivada.
`teamDeleted`	`'teamDeleted'`	A equipe foi excluída.
`teamRestored`	`'teamRestored'`	A equipe foi restaurada.
Reunião iniciada	`'meetingStart'`	Uma reunião foi iniciada.
Reunião encerrada	`'meetingEnd'`	Uma reunião terminou.
O participante ingressou	`'meetingParticipantJoin'`	Um participante ingressou em uma reunião.
Participante à esquerda	`'meetingParticipantLeave'`	Um participante saiu de uma reunião.

Atividades de invocação do Teams

A tabela a seguir lista invocam manipuladores de atividades disponíveis por meio de app.on():

Invocar tipo	Cadeia de caracteres de nome do evento	Descrição
`CardAction.Invoke`	`'card.action'`	Uma atividade de invocação de ação de card foi recebida (`adaptiveCard/action`).
`signin/verifyState`	Manipulado automaticamente pelo SDK (fluxo OAuth)	Atividade de estado de verificação de entrada.
`task/fetch`	`'dialog.open'`	Uma caixa de diálogo (módulo de tarefa) foi buscada.
`task/submit`	`'dialog.submit'`	Uma caixa de diálogo (módulo de tarefa) foi enviada.

Manipuladores de atividades principais

A App classe expõe o registro do manipulador no estilo decorador.

Evento	Decorador	Descrição
Qualquer atividade recebida	`@app.on_activity`	Manipulador catch-all para cada atividade.
Mensagem recebida	`@app.on_message`	Lidar com mensagens de texto de entrada.
Mensagem com padrão	`@app.on_message_pattern(re.compile(...))`	Manipular mensagens que correspondam a um padrão regex.
Atualização da conversa	`@app.on_conversation_update`	Atualização de conversa bruta; `members_added` / `members_removed`marcar .
Instalação adicionada	`@app.on_install_add`	O agente foi instalado.
Instalação removida	`@app.on_install_remove`	O agente foi desinstalado.

Manipuladores de atividades específicos do Teams

Evento	Decorador	Descrição
Canal criado	`@app.on_channel_created`	Foi criado um canal do Teams.
Canal excluído	`@app.on_channel_deleted`	Um canal do Teams foi excluído.
Canal renomeado	`@app.on_channel_renamed`	Um canal do Teams foi renomeado.
Equipe renomeada	`@app.on_team_renamed`	A equipe foi renomeada.
Mensagem editada	`@app.on_edit_message`	Uma mensagem foi editada.
Mensagem excluída temporariamente	`@app.on_soft_delete_message`	Uma mensagem foi excluída temporariamente.
Mensagem não excluída	`@app.on_undelete_message`	Uma mensagem excluída foi restaurada.
Reunião iniciada	`@app.on_meeting_start`	Uma reunião foi iniciada.
Reunião encerrada	`@app.on_meeting_end`	Uma reunião terminou.
O participante ingressou	`@app.on_meeting_participant_join`	Um participante ingressou em uma reunião.
Participante à esquerda	`@app.on_meeting_participant_leave`	Um participante saiu de uma reunião.

Atividades de invocação do Teams

Invocar tipo	Decorador	Descrição
`CardAction.Invoke`	`@app.on_card_action`	Uma atividade de invocação de ação de card foi recebida.
`task/fetch`	`@app.on_dialog_open`	Uma caixa de diálogo (módulo de tarefa) foi buscada.
`task/submit`	`@app.on_dialog_submit`	Uma caixa de diálogo (módulo de tarefa) foi enviada.
`fileConsent/invoke`	`@app.on_file_consent`	Uma atividade de card de consentimento de arquivo foi recebida.
`signin/verifyState`	Manipulado automaticamente pelo SDK (fluxo OAuth)	Atividade de estado de verificação de entrada.

Agora que você já se familiarizou com os manipuladores de atividades do agente, vamos ver como os agentes se comportam de maneira diferente dependendo da conversa e das mensagens que ela recebe ou envia.

Recomendações

Um diálogo extenso entre seu agente e o usuário é uma maneira lenta e complexa de concluir uma tarefa. Um agente que dá suporte a comandos excessivos, especialmente uma ampla variedade de comandos, não é bem-sucedido ou visto positivamente pelos usuários.

Evite experiências de várias voltas no chat Um diálogo extenso requer que o desenvolvedor mantenha o estado. Para sair desse estado, um usuário deve atingir o tempo limite ou selecionar Cancelar. Além disso, o processo é entediante. Por exemplo, consulte o seguinte cenário de conversa:

USER: Agende uma reunião com Sara.

AGENTE: Encontrei 200 resultados, incluem um nome e sobrenome.

USER: Agende uma reunião com Sara Melo.

AGENTE: OK, a que horas você gostaria de se encontrar com Megan Bowen?

USUÁRIO: 13h.

AGENTE: Em que dia?
Suporta seis comandos ou menos frequentes Como há apenas seis comandos visíveis no menu do agente atual, é improvável que algo além disso seja usado com qualquer frequência. Os agentes que se aprofundam em uma área específica, em vez de tentar ser um amplo assistente, trabalham e se saem melhor.
Otimize o tamanho da base de dados de conhecimento para uma interação mais rápida Uma das desvantagens dos agentes é que é difícil manter uma grande base de dados de dados de conhecimento de recuperação com respostas não classificadas. Os agentes são mais adequados para interações curtas e rápidas, e não para vasculhar longas listas em busca de uma resposta.

Observação

A plataforma do Teams dá suporte apenas ao protocolo TLS versão 1.2. Certifique-se de configurar seu ambiente de agente adequadamente.

Explore outros recursos do agente

Além dos recursos convencionais do agente, você também pode explorar os recursos avançados disponíveis em um aplicativo de agente do Teams:

Exemplo de código

Nome do exemplo	Descrição	TypeScript	C#	Python
Agente de conversa do Teams	Este aplicativo demonstra eventos básicos de agente.	View	View	View

Comentários

Esta página foi útil?

Última atualização a 2026-08-24

Entender os conceitos do agente

Escopos do agente

Em um canal.

Em um chat em grupo

Chat Privado

Lógica do manipulador de atividades e do agente

Manipulador de atividades do Teams

Trechos de código do manipulador de atividades

Exemplo de manipulador de atividade do agente

Lógica do agente

Manipuladores de atividades principais

Manipuladores de atividades específicos do Teams

Atividades de invocação do Teams

Recomendações

Explore outros recursos do agente

Exemplo de código

Comentários

Recursos adicionais