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.

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.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@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

@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:

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

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 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.

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.

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:

• Obtenha o contexto específico do Teams para seu agente.
• Agentes de chamadas e reuniões online.
• Habilite o SSO para seu aplicativo.

Exemplo de código