Comprendre les concepts de l’agent

Les interactions d’un agent peuvent utiliser du texte, de la parole, des images ou des vidéos. Il traite l’entrée de l’utilisateur pour comprendre sa demande et évalue l’entrée pour effectuer les tâches pertinentes. Un agent peut demander des informations ou activer l’accès aux services, et répond à l’utilisateur.

Étendues d’agent

Les agents de Microsoft Teams peuvent participer à une conversation en tête-à-tête, à une conversation de groupe ou à un canal au sein d’une équipe. Chaque étendue offre des opportunités et des défis uniques pour votre agent conversationnel.

Dans un canal	Dans une conversation de groupe	Dans une conversation privée
Portée massive	Moins de membres	Mode traditionnel
Interactions individuelles concises	@mention à l’agent	Agent Q&A
@mention à l’agent	Similaire au canal	Des agents qui racontent des blagues et prennent des notes

Dans un canal

Les canaux contiennent des conversations à thread entre plusieurs personnes, jusqu’à 2000. Cela peut donner à votre agent une portée massive, mais les interactions individuelles doivent être concises. Les interactions multitours traditionnelles ne fonctionnent pas. Au lieu de cela, vous devez chercher à utiliser des cartes ou des boîtes de dialogue interactives (appelées modules de tâche dans TeamsJS v1.x), ou déplacer la conversation vers une conversation en tête-à-tête pour collecter beaucoup d’informations. Votre agent n’a accès aux messages que dans les emplacements .@mentioned Vous pouvez récupérer des messages supplémentaires à partir de la conversation à l’aide d’autorisations Microsoft Graph et au niveau de l’organisation.

Les agents fonctionnent mieux dans un canal dans les cas suivants :

• Notifications, où vous fournissez une carte interactive permettant aux utilisateurs de prendre des informations supplémentaires.
• Scénarios de commentaires, tels que les sondages et les enquêtes.
• Un cycle de requête ou de réponse unique résout les interactions et les résultats sont utiles pour plusieurs membres de la conversation.
• Agents sociaux ou amusants, où vous obtenez une image de chat impressionnante, choisissez un gagnant au hasard, etc.

Dans une conversation de groupe

Les conversations de groupe sont des conversations non thématiques entre trois personnes au minimum. Elles impliquent généralement moins de membres qu’un canal et sont plus éphémères. Comme pour un canal, votre agent n’a accès qu’aux messages dans les endroits où il est @mentioned directement.

Les agents qui fonctionnent mieux dans un canal fonctionnent également mieux dans une conversation de groupe.

Dans une conversation privée

La conversation en tête-à-tête est un moyen traditionnel pour un agent conversationnel d’interagir avec un utilisateur. Voici quelques exemples d’agents conversationnels individuels :

• Agent Q&A
• des agents qui lancent des workflows dans d’autres systèmes.
• des agents qui racontent des blagues.
• des agents qui prennent des notes. Avant de créer des agents un-à-un, déterminez si une interface basée sur la conversation est la meilleure façon de présenter vos fonctionnalités.

Gestionnaire d’activités et logique de l’agent

Pour créer une application d’agent qui répond à vos besoins, il est essentiel de comprendre la logique du gestionnaire d’activités et de l’agent Microsoft Teams. Ces deux composants clés fonctionnent ensemble pour organiser la logique conversationnelle.

• Gestionnaire d’activités Teams : processus Événements et interactions spécifiques aux équipes, tels que la création de canaux, les ajouts de membres d’équipe et d’autres actions propres à l’environnement Teams. Dans le SDK Teams v2, les gestionnaires sont enregistrés directement sur une instance plutôt que via un App héritage de classe.

• Logique de l’agent : l’objet App abrite la logique conversationnelle de l’agent et est chargé de prendre des décisions en fonction des entrées de l’utilisateur. Les activités entrantes sont acheminées vers le gestionnaire approprié en fonction du type d’activité et de la correspondance de modèle facultative.

Gestionnaire d’activités Teams

Le gestionnaire d’activités est au cœur des fonctionnalités d’un agent, gérant et traitant les interactions utilisateur. Dans le SDK Teams v2 :

• Vous instanciez un App objet et enregistrez des gestionnaires sur celui-ci.
• Les gestionnaires reçoivent un objet de contexte typé (IActivityContext en TypeScript, IContext<TActivity> en C#, ActivityContext[TActivity] en Python).
• Les réponses et les messages proactifs sont envoyés via ctx.reply() ou ctx.send().

Lorsqu’un agent Teams reçoit une activité, le SDK l’achemine via le gestionnaire enregistré. Les événements spécifiques à Teams (cycle de vie des canaux, modifications des membres, etc.) sont affichés sous forme d’événements nommés distincts, de sorte que vous n’avez pas besoin d’inspecter channelData.eventType manuellement.

Remarque

Si le traitement d’une activité d’agent prend plus de 15 secondes, Teams envoie une demande de nouvelle tentative au point de terminaison de l’agent, de sorte que vous pouvez voir des demandes en double.

Extraits de code du gestionnaire d’activités

Les extraits de code suivants montrent les gestionnaires d’activité Teams pour les événements de canal et de cycle de vie d’équipe.

SDK C# v2.1

Les agents sont créés à l’aide du Microsoft.Teams.Apps package. Vous instanciez des inscriptions de gestionnaires de chaîne an App et en utilisant des méthodes d’extension telles que OnMessage(), OnChannelCreated(), etc. Tous les gestionnaires reçoivent un IContext<TActivity> objet.

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

Les modifications de message sont gérées via OnMessageUpdate. Les suppressions réversibles sont gérées par OnMessageDelete.

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

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

SDK<C# 2.1(hérité)

Les agents sont créés à l’aide du Microsoft.Teams.Apps package. Vous instanciez des inscriptions de gestionnaires de chaîne an App et en utilisant des méthodes d’extension telles que OnMessage(), OnChannelCreated(), etc. Tous les gestionnaires reçoivent un IContext<TActivity> objet.

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

Les modifications de message sont gérées via OnMessageUpdate. Les suppressions réversibles sont gérées par OnMessageDelete.

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

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

TypeScript

Les agents sont créés à l’aide du @microsoft/teams.apps package. Vous instanciez un App et inscrivez les gestionnaires avec app.on(eventName, handler). Le Kit de développement logiciel (SDK) achemine les activités vers le gestionnaire correct en fonction de la chaîne de nom d’événement.

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

Les modifications de message s’affichent sous la forme messageUpdate. Les suppressions réversibles sont présentées comme — messageDelete le activity.channelData.eventType sera 'softDeleteMessage'.

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

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

Python

Les agents sont créés à l’aide du microsoft-teams-apps package. Les gestionnaires sont enregistrés à l’aide de décorateurs sur une App instance. Chaque gestionnaire est une async fonction qui reçoit un ActivityContext[TActivity] objet.

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 (membres ajoutés / supprimés)

Les événements ajoutés et supprimés de membres sont gérés via on_conversation_update. Inspecter ctx.activity.members_added et 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

Exemple de gestionnaire d’activité d’agent

Le code suivant fournit un exemple d’activité d’agent :

SDK C# v2.1

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

SDK<C# 2.1(hérité)

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

TypeScript

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

Python

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

Logique de l’agent

La logique de l’agent intègre les règles fondamentales et les cadres de prise de décision qui dictent les actions et les interactions d’un agent. Il décrit comment l’agent interprète les entrées utilisateur, formule des réponses et participe aux conversations.

Dans le SDK v2 de Teams, la logique d’agent traite les activités entrantes à partir d’un ou plusieurs canaux d’agent et génère des activités sortantes. Tout le routage d’activité est géré par l’instance App : vous enregistrez les gestionnaires et le SDK leur distribue automatiquement les activités.

C#

Gestionnaires d’activités principales

La App classe expose les méthodes d’extension pour inscrire des gestionnaires. Les méthodes sont renvoyées App pour le chaînage fluide.

Événement	Méthode d’extension	Description
Tout type d’activité reçu	OnActivity(handler)	Le gestionnaire fourre-tout a appelé pour chaque activité.
Activité de message reçue	OnMessage(handler)	Gérer les SMS entrants. Passez une chaîne regex comme premier argument pour la correspondance de modèle.
Mise à jour de conversation reçue	OnConversationUpdate(handler)	Activité brute de mise à jour des conversations.
Membres non-agent joints	OnMembersAdded(handler)	Se déclenche lorsque MembersAdded.Length > 0.
Membres non-agent restants	OnMembersRemoved(handler)	Se déclenche lorsque MembersRemoved.Length > 0.
Installation ajoutée	OnInstall(handler)	L’agent a été installé.

Gestionnaires d’activités spécifiques à Teams

Événement	Méthode d’extension	Description
Chaîne créée	OnChannelCreated(handler)	Un canal Teams a été créé.
Canal supprimé	OnChannelDeleted(handler)	Un canal Teams a été supprimé.
Canal renommé	OnChannelRenamed(handler)	Un canal Teams a été renommé.
Équipe renommée	OnTeamRenamed(handler)	L’équipe a été renommée.
Message modifié	OnMessageUpdate(handler)	Un message a été modifié.
Message supprimé de manière réversible	OnMessageDelete(handler)	Un message a été supprimé de manière réversible.

Teams appeler des activités

Type d’appel	Méthode d’extension	Description
CardAction.Invoke	OnExecuteAction(handler)	Une activité d’appel d’action de carte a été reçue.
task/fetch	OnTaskFetch(handler)	Une boîte de dialogue (module de tâche) a été récupérée.
task/submit	OnTaskSubmit(handler)	Une boîte de dialogue (module de tâche) a été soumise.
fileConsent/invoke	OnFileConsent(handler)	Une activité de la carte de consentement de fichier a été reçue.
signin/verifyState	Géré automatiquement par le SDK (flux OAuth)	Se connecter pour vérifier l’activité de l’état.

TypeScript

Gestionnaires d’activités principales

La liste des noms d’événement pris en charge par app.on() comprend les éléments suivants :

Événement	Chaîne du nom de l’événement	Description
Tout type d’activité reçu	'activity'	Le gestionnaire fourre-tout a appelé pour chaque activité.
Activité de message reçue	'message'	Gérer les SMS entrants. À utiliser app.message(pattern, handler) pour la correspondance d’expressions régulières.
Mise à jour de conversation reçue	'conversationUpdate'	Activité brute de mise à jour des conversations.
Installation ajoutée	'install.add'	L’agent a été installé.
Installation supprimée	'install.remove'	L’agent a été désinstallé.
Membres ajoutés	'membersAdded'	Un ou plusieurs membres se sont joints à la conversation.
Membres supprimés	'membersRemoved'	Un ou plusieurs membres ont quitté la conversation.
Message modifié	'messageUpdate'	Un message de la conversation a été modifié.
Message supprimé de manière réversible	'messageDelete'	Un message a été suppriméactivity.channelData.eventType === 'softDeleteMessage' (().
Confirmation de lecture reçue	'readReceipt'	Une confirmation de lecture a été reçue.

Gestionnaires d’événements spécifiques à Teams

app.on() prend en charge les chaînes de nom d’événement spécifiques à Teams suivantes :

Événement	Chaîne du nom de l’événement	Description
channelCreated	'channelCreated'	Un canal Teams a été créé.
channelDeleted	'channelDeleted'	Un canal Teams a été supprimé.
channelRenamed	'channelRenamed'	Un canal Teams a été renommé.
channelRestored	'channelRestored'	Un canal Teams a été restauré.
channelMemberAdded	'channelMemberAdded'	Un membre a été ajouté à un canal.
channelMemberRemoved	'channelMemberRemoved'	Un membre a été supprimé d’un canal.
teamRenamed	'teamRenamed'	L’équipe a été renommée.
teamArchived	'teamArchived'	L’équipe a été archivée.
teamDeleted	'teamDeleted'	L’équipe a été supprimée.
teamRestored	'teamRestored'	L’équipe a été restaurée.
Réunion démarrée	'meetingStart'	Une réunion a commencé.
Réunion terminée	'meetingEnd'	Une réunion s’est terminée.
Un participant a rejoint	'meetingParticipantJoin'	Un participant a rejoint une réunion.
Partie gauche du participant	'meetingParticipantLeave'	Un participant a quitté une réunion.

Teams appeler des activités

Le tableau suivant répertorie les gestionnaires d’activité d’appel disponibles via app.on():

Type d’appel	Chaîne du nom de l’événement	Description
CardAction.Invoke	'card.action'	Une activité d’appel d’action de carte a été reçue (adaptiveCard/action).
signin/verifyState	Géré automatiquement par le SDK (flux OAuth)	Se connecter pour vérifier l’activité de l’état.
task/fetch	'dialog.open'	Une boîte de dialogue (module de tâche) a été récupérée.
task/submit	'dialog.submit'	Une boîte de dialogue (module de tâche) a été soumise.

Python

Gestionnaires d’activités principales

La App classe expose l’inscription du gestionnaire de style décorateur.

Événement	Décorateur	Description
Toute activité reçue	@app.on_activity	Gestionnaire fourre-tout pour chaque activité.
Message reçu	@app.on_message	Gérer les SMS entrants.
Message avec modèle	@app.on_message_pattern(re.compile(...))	Traiter les messages correspondant à un modèle d’expression régulière.
Mise à jour de la conversation	@app.on_conversation_update	Mise à jour de la conversation brute ; members_added / members_removedcase activée .
Installation ajoutée	@app.on_install_add	L’agent a été installé.
Installation supprimée	@app.on_install_remove	L’agent a été désinstallé.

Gestionnaires d’activités spécifiques à Teams

Événement	Décorateur	Description
Chaîne créée	@app.on_channel_created	Un canal Teams a été créé.
Canal supprimé	@app.on_channel_deleted	Un canal Teams a été supprimé.
Canal renommé	@app.on_channel_renamed	Un canal Teams a été renommé.
Équipe renommée	@app.on_team_renamed	L’équipe a été renommée.
Message modifié	@app.on_edit_message	Un message a été modifié.
Message supprimé de manière réversible	@app.on_soft_delete_message	Un message a été supprimé de manière réversible.
Message non supprimé	@app.on_undelete_message	Un message supprimé a été restauré.
Réunion démarrée	@app.on_meeting_start	Une réunion a commencé.
Réunion terminée	@app.on_meeting_end	Une réunion s’est terminée.
Un participant a rejoint	@app.on_meeting_participant_join	Un participant a rejoint une réunion.
Partie gauche du participant	@app.on_meeting_participant_leave	Un participant a quitté une réunion.

Teams appeler des activités

Type d’appel	Décorateur	Description
CardAction.Invoke	@app.on_card_action	Une activité d’appel d’action de carte a été reçue.
task/fetch	@app.on_dialog_open	Une boîte de dialogue (module de tâche) a été récupérée.
task/submit	@app.on_dialog_submit	Une boîte de dialogue (module de tâche) a été soumise.
fileConsent/invoke	@app.on_file_consent	Une activité de la carte de consentement de fichier a été reçue.
signin/verifyState	Géré automatiquement par le SDK (flux OAuth)	Se connecter pour vérifier l’activité de l’état.

Maintenant que vous vous êtes familiarisé avec les gestionnaires d’activité d’agent, voyons comment les agents se comportent différemment en fonction de la conversation et des messages qu’ils reçoivent ou envoient.

Recommandations

Un dialogue étendu entre votre agent et l’utilisateur est un moyen lent et complexe d’accomplir une tâche. Un agent qui prend en charge un nombre excessif de commandes, en particulier un large éventail de commandes, n’est pas efficace ou perçu positivement par les utilisateurs.

• Éviter les expériences à plusieurs tours dans la conversation Une boîte de dialogue étendue nécessite que le développeur conserve l’état. Pour quitter cet état, un utilisateur doit soit expirer, soit sélectionner Annuler. En outre, le processus est fastidieux. Par exemple, consultez le scénario de conversation suivant :

  UTILISATEUR : planifier une réunion avec Megan.

  AGENT : J’ai trouvé 200 résultats, dont un prénom et un nom.

  UTILISATEUR : Planifiez une réunion avec Megan Bowen.

  AGENT : OK, à quelle heure aimeriez-vous rencontrer Megan Bowen ?

  UTILISATEUR : 13:00.

  AGENT : Quel jour ?

• Prend en charge six commandes fréquentes ou moins Comme il n’y a que six commandes visibles dans le menu actuel de l’agent, il est peu probable que quoi que ce soit d’autre soit utilisé fréquemment. Les agents qui vont en profondeur dans un domaine spécifique plutôt que d’essayer d’être un large assistant travaillent et s’en sortent mieux.

• Optimiser la taille de la base de connaissances pour une interaction plus rapide L’un des inconvénients des agents est qu’il est difficile de maintenir une grande base de connaissances de récupération avec des réponses non classées. Les agents sont mieux adaptés aux interactions courtes et rapides, et ne pas passer au crible de longues listes à la recherche d’une réponse.

Remarque

La plateforme Teams prend uniquement en charge le protocole TLS (Transport Layer Security) version 1.2. Veillez à configurer votre environnement d’agent en conséquence.

Explorer d’autres fonctionnalités d’agent

En plus des fonctionnalités d’agent conventionnelles, vous pouvez également explorer les fonctionnalités avancées disponibles dans une application d’agent Teams :

• Obtenez le contexte spécifique à Teams pour votre agent.
• Agents d’appels et de réunions en ligne.
• Activez l’authentification unique pour votre application.

Exemple de code

Exemple de nom	Description	TypeScript	C#	Python
Agent de conversation Teams	Cette application illustre les événements de base de l’agent.	View	View	View