Compreender os conceitos do agente

As interações de um agente podem estar a utilizar texto, voz, imagens ou vídeo. Processa a entrada do utilizador para compreender o pedido e avalia a entrada para realizar tarefas relevantes. Um agente pode pedir informações ou ativar o acesso aos serviços e responder ao utilizador.

Âmbitos do agente

Os agentes no Microsoft Teams podem fazer parte de uma conversação um-para-um, de uma conversa de grupo ou de um canal numa equipa. Cada âmbito proporciona oportunidades e desafios exclusivos para o seu agente de conversação.

Em um canal.

Os canais contêm conversações por tópicos entre várias pessoas, até mesmo até 2000. Isto potencialmente dá ao agente um alcance enorme, mas as interações individuais têm de ser concisas. As interações multifator tradicionais não funcionam. Em vez disso, tem de procurar utilizar cartões ou caixas de diálogo interativos (referidos como módulos de tarefas no TeamsJS v1.x) ou mover a conversação para uma conversação um-para-um para recolher muitas informações. O agente só tem acesso a mensagens em que é @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 num 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 obtém uma imagem incrível de gato, escolhem 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, o agente só tem acesso a mensagens onde está @mentioned diretamente.

Os agentes que funcionam melhor num canal também funcionam melhor numa conversa de grupo.

Chat Privado

O chat um-para-um é uma forma tradicional de um agente de conversação interagir com um utilizador. Alguns exemplos de agentes de conversação um-para-um são:

• Q&A agents (Agentes do Q&A)
• agentes que iniciam fluxos de trabalho noutros sistemas.
• agentes que contam piadas.
• agentes que tiram notas. Antes de criar agentes um-para-um, considere se uma interface baseada em conversação é a melhor forma de apresentar a sua funcionalidade.

Processador de atividade e lógica do agente

Para criar uma aplicação de agente que satisfaça as suas necessidades, é essencial compreender o processador de atividades e a lógica do agente do Microsoft Teams. Estes dois componentes principais trabalham em conjunto para organizar a lógica de conversação.

• Processador de atividades do Teams: processa eventos e interações específicos do Teams, tais como a criação de canais, adições de membros da equipa e outras ações exclusivas para o ambiente do Teams. No SDK do Teams v2, os processadores são registados diretamente numa App instância e não através da herança de classes.

• Lógica do agente: o App objeto aloja a lógica de conversação do agente e é responsável por tomar decisões com base na entrada do utilizador. As atividades de entrada são encaminhadas para o processador adequado com base no tipo de atividade e na correspondência de padrões opcionais.

Processador de atividades do Teams

O processador de atividade é o núcleo da funcionalidade de um agente, ao gerir e processar as interações do utilizador. No SDK do Teams v2:

• Instancia um App objeto e regista processadores no mesmo.
• Os processadores recebem um objeto de contexto escrito (IActivityContext em TypeScript, IContext<TActivity> em C#, ActivityContext[TActivity] em Python).
• As respostas e as mensagens proativas são enviadas através de ctx.reply() ou ctx.send().

Quando um agente do Teams recebe uma atividade, o SDK encaminha-a através do processador registado. Os eventos específicos do Teams (ciclo de vida do canal, alterações de membros, etc.) são apresentados como eventos nomeados distintos, pelo que não precisa de inspecionar channelData.eventType manualmente.

Fragmentos de código do processador de atividades

Os fragmentos seguintes mostram os processadores de atividade do Teams para eventos de ciclo de vida do canal e da equipa.

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 processador de atividade de agente

O código seguinte 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ões que ditam as ações e interações de um agente. Descreve como o agente interpreta a entrada do utilizador, formula respostas e participa em conversações.

No SDK v2 do Teams, a lógica do agente processa as atividades recebidas de um ou mais canais de agente e gera atividades de saída. Todo o App encaminhamento de atividade é processado pela instância – regista os processadores e o SDK envia atividades para os mesmos automaticamente.

Agora que se familiarizou com os processadores de atividade do agente, deixe-nos ver como os agentes se comportam de forma diferente consoante a conversação e as mensagens que recebe ou envia.

Recomendações

Uma caixa de diálogo extensa entre o agente e o utilizador é uma forma lenta e complexa de concluir uma tarefa. Um agente que suporta comandos excessivos, especialmente uma vasta gama de comandos, não é bem-sucedido ou visto positivamente pelos utilizadores.

• Evitar experiências multi-turn no chat Uma caixa de diálogo extensa requer que o programador mantenha o estado. Para sair deste estado, um utilizador tem de exceder o limite de tempo 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.

  Encontrei 200 resultados, incluindo o nome próprio e o apelido.

  USER: Agende uma reunião com Sara Melo.

  A que horas gostaria de se encontrar com Megan Bowen?

  USUÁRIO: 13h.

  Em que dia?

• Suportar seis ou menos comandos frequentes Uma vez que existem apenas seis comandos visíveis no menu atual do agente, é pouco provável que algo mais seja utilizado com qualquer frequência. Agentes que entram profundamente numa área específica em vez de tentarem ser um trabalho amplo assistente e se safarem melhor.

• Otimizar o tamanho de 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 conhecimento de obtenção com respostas não classificadas. Os agentes são mais adequados para interações rápidas e curtas e não percorrem listas longas à procura de uma resposta.

Explorar outras funcionalidades do agente

Além das funcionalidades convencionais do agente, também pode explorar funcionalidades avançadas disponíveis numa aplicação de agente do Teams:

• Obtenha contexto específico do Teams para o seu agente.
• Agentes de chamadas e reuniões online.
• Ative o SSO para a sua aplicação.

Exemplo de código