Comprendre les concepts de l’agent

Les interactions d’un agent peuvent être à l’aide de texte, de parole, d’images ou de 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 de l’agent

Les agents dans Microsoft Teams peuvent faire partie d’une conversation un-à-un, d’une conversation de groupe ou d’un canal dans 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	Agents Q&A
@mention à l’agent	Similaire au canal	Agents qui racontent des blagues et prennent des notes

Dans un canal

Les canaux contiennent des conversations thématiques entre plusieurs personnes, même jusqu’à 2000. Cela peut donner à votre agent une portée massive, mais les interactions individuelles doivent être concises. Les interactions multitour traditionnelles ne fonctionnent pas. Au lieu de cela, vous devez utiliser des cartes ou des dialogues interactifs (appelés modules de tâche dans TeamsJS v1.x) ou déplacer la conversation vers une conversation un-à-un pour collecter un grand nombre d’informations. Votre agent a uniquement accès aux messages où il s’agit de @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 génial, choisir au hasard un gagnant, et ainsi de suite.

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. À l’instar d’un canal, votre agent n’a accès qu’aux messages où il se trouve @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 un-à-un est un moyen traditionnel pour un agent conversationnel d’interagir avec un utilisateur. Voici quelques exemples d’agents conversationnels un-à-un :

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

Gestionnaire d’activités et logique d’agent

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

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

• Logique de l’agent : l’objet App héberge la logique conversationnelle de l’agent et est chargé de prendre des décisions en fonction de l’entrée de l’utilisateur. Les activités entrantes sont routé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, en gérant et en traitant les interactions utilisateur. Dans le Kit de développement logiciel (SDK) Teams v2 :

• Vous instanciez un App objet et vous y inscrivez des gestionnaires.
• Les gestionnaires reçoivent un objet de contexte typé (IActivityContext dans 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 inscrit. Les événements spécifiques à Teams (cycle de vie du canal, modifications de membre, etc.) sont exposés sous la forme d’événements nommés distincts, vous n’avez donc 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.

TypeScript

Les agents sont générés à l’aide du @microsoft/teams.apps package . Vous instanciez un App et inscrivez des gestionnaires avec app.on(eventName, handler). Le Kit de développement logiciel (SDK) achemine les activités vers le gestionnaire approprié 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 sont exposées sous la forme messageUpdate. Les suppressions réversibles sont exposées sous messageDelete la forme : 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
});

C#

Les agents sont générés à l’aide du Microsoft.Teams.Apps package . Vous instanciez un et chaînez les inscriptions de gestionnaires à l’aide de méthodes d’extension App 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 via OnMessageDelete.

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

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

Python

Les agents sont générés à l’aide du microsoft-teams-apps package . Les gestionnaires sont inscrits à l’aide d’éléments décoratifs sur un 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 des membres sont gérés via on_conversation_update. Inspectez 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és de l’agent

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

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

C#

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

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 frameworks de prise de décision qui dictent les actions et les interactions d’un agent. Il décrit la façon dont l’agent interprète les entrées utilisateur, formule les réponses et participe aux conversations.

Dans le Kit de développement logiciel (SDK) Teams v2, la logique de l’agent traite les activités entrantes à partir d’un ou plusieurs canaux d’agent et génère des activités sortantes. Tous les routages d’activité sont gérés par le App instance : vous inscrivez les gestionnaires et le Kit de développement logiciel (SDK) leur distribue automatiquement les activités.

TypeScript

Gestionnaires d’activités principales

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

Événement	Chaîne de nom d’événement	Description
Tout type d’activité reçu	'activity'	Gestionnaire fourre-tout appelé pour chaque activité.
Activité de message reçue	'message'	Gérer les messages texte entrants. Utilisez app.message(pattern, handler) pour la correspondance d’expression régulière.
Mise à jour de conversation reçue	'conversationUpdate'	Activité de mise à jour de conversation brute.
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 ont rejoint la conversation.
Membres supprimés	'membersRemoved'	Un ou plusieurs membres ont quitté la conversation.
Message modifié	'messageUpdate'	Un message dans la conversation a été modifié.
Message supprimé de manière réversible	'messageDelete'	Un message a été supprimé de manière réversible (activity.channelData.eventType === 'softDeleteMessage').
Confirmation de lecture reçue	'readReceipt'	Un accusé de lecture a été reçu.

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 de nom d’é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é.
Fin de la réunion	'meetingEnd'	Une réunion s’est terminée.
Participant joint	'meetingParticipantJoin'	Un participant a rejoint une réunion.
Participant gauche	'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 de nom d’événement	Description
CardAction.Invoke	'card.action'	Une activité d’appel d’action carte a été reçue (adaptiveCard/action).
signin/verifyState	Géré automatiquement par le Kit de développement logiciel (SDK) (flux OAuth)	Activité de vérification de l’état de connexion.
task/fetch	'dialog.open'	Une boîte de dialogue (module de tâche) a été extraite.
task/submit	'dialog.submit'	Une boîte de dialogue (module de tâche) a été envoyée.

C#

Gestionnaires d’activités principales

La App classe expose des méthodes d’extension pour inscrire des gestionnaires. Les méthodes retournent App pour le chaînage Fluent.

Événement	Méthode d’extension	Description
Tout type d’activité reçu	OnActivity(handler)	Gestionnaire fourre-tout appelé pour chaque activité.
Activité de message reçue	OnMessage(handler)	Gérer les messages texte entrants. Passez une chaîne d’expression régulière comme premier argument pour la correspondance de modèle.
Mise à jour de conversation reçue	OnConversationUpdate(handler)	Activité de mise à jour de conversation brute.
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 carte a été reçue.
task/fetch	OnTaskFetch(handler)	Une boîte de dialogue (module de tâche) a été extraite.
task/submit	OnTaskSubmit(handler)	Une boîte de dialogue (module de tâche) a été envoyée.
fileConsent/invoke	OnFileConsent(handler)	Un consentement de fichier carte’activité a été reçu.
signin/verifyState	Géré automatiquement par le Kit de développement logiciel (SDK) (flux OAuth)	Activité de vérification de l’état de connexion.

Python

Gestionnaires d’activités principales

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

É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 messages texte entrants.
Message avec modèle	@app.on_message_pattern(re.compile(...))	Gérer les messages correspondant à un modèle d’expression régulière.
Mise à jour de conversation	@app.on_conversation_update	Mise à jour de 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é.
Fin de la réunion	@app.on_meeting_end	Une réunion s’est terminée.
Participant joint	@app.on_meeting_participant_join	Un participant a rejoint une réunion.
Participant gauche	@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 carte a été reçue.
task/fetch	@app.on_dialog_open	Une boîte de dialogue (module de tâche) a été extraite.
task/submit	@app.on_dialog_submit	Une boîte de dialogue (module de tâche) a été envoyée.
fileConsent/invoke	@app.on_file_consent	Un consentement de fichier carte’activité a été reçu.
signin/verifyState	Géré automatiquement par le Kit de développement logiciel (SDK) (flux OAuth)	Activité de vérification de l’état de connexion.

Maintenant que vous vous êtes familiarisé avec les gestionnaires d’activités des agents, 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’effectuer une tâche. Un agent qui prend en charge des commandes excessives, en particulier un large éventail de commandes, n’est pas réussi ou n’est pas vu de manière positive par les utilisateurs.

• Éviter les expériences multitours dans la conversation Un dialogue étendu nécessite que le développeur conserve l’état. Pour quitter cet état, un utilisateur doit expirer ou 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, y compris 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 ?

• Prendre en charge six commandes ou moins fréquentes Étant donné qu’il n’y a que six commandes visibles dans le menu actuel de l’agent, il est peu probable qu’une autre commande soit utilisée avec une fréquence quelconque. 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 des base de connaissances pour une interaction plus rapide L’un des inconvénients des agents est qu’il est difficile de maintenir une récupération volumineuse base de connaissances avec des réponses non notées. Les agents sont mieux adaptés aux interactions courtes et rapides, et ne pas passer au crible les longues listes à la recherche d’une réponse.

Remarque

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

Explorer d’autres fonctionnalités de l’agent

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

• Obtenez le contexte spécifique de Teams pour votre agent.
• Appels et agents 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