Présentation du protocole d’activité

Le protocole d’activité est le protocole de communication et le protocole standard utilisé par Microsoft dans de nombreux sdk, services et clients Microsoft. Cela inclut Microsoft 365 Copilot, Microsoft Copilot Studio et le Kit de développement logiciel (SDK) Microsoft 365 Agents. Le protocole d’activité définit la structure d’un Activity ainsi que le flux des messages, des événements et des interactions, allant du canal à votre code et partout ailleurs. Les agents peuvent se connecter à un ou plusieurs canaux pour interagir avec les utilisateurs et travailler avec d’autres agents. Le protocole d’activité normalise le protocole de communication entre tous les clients avec lesquels vous travaillez, y compris les clients Microsoft et tiers. Vous n’avez donc pas besoin de créer une logique personnalisée par canal avec lequel vous travaillez.

Qu’est-ce qu’une activité ?

Il Activity s’agit d’un objet JSON structuré qui représente toute interaction entre un utilisateur et votre agent. Les activités ne sont pas seulement des messages textuels, elles peuvent inclure divers types d’interactions, notamment pour les clients permettant le support de plusieurs utilisateurs, des événements tels qu’un utilisateur qui rejoint ou quitte, les indicateurs de saisie, les chargements de fichiers, les actions de carte et des événements personnalisés conçus par les développeurs eux-mêmes.

Chaque activité comprend des métadonnées sur les éléments suivants :

Qui l'a envoyé et depuis où ?
Qui doit le recevoir (destinataire)
Contexte de conversation
Canal à partir duquel il provient
Type d’interaction
Données de charge utile

Schéma d’activité - Propriétés de clé

Cette spécification définit le protocole d’activité : protocole d’activité - Activité. Voici quelques-unes des propriétés clés définies dans le protocole d’activité :

Propriété	Descriptif
`Id`	Généralement généré par le canal s’il provient d’un canal
`Type`	Le type contrôle la signification d’une activité, par exemple le type de message
`ChannelID`	La référence `ChannelID` indique le canal d'où provient l'activité. Par exemple : `msteams`.
`From`	Expéditeur de l’activité (qui peut être un utilisateur ou un agent)
`Recipient`	Destinataire prévu de l’activité
`Text`	Le texte du message
`Attachment`	Contenu enrichi, comme des cartes, des images de fichiers

Accéder aux données d’activité

Les développeurs doivent accéder aux données de l’activité pour effectuer des actions à partir de l’objet TurnContext .

Vous trouverez une TurnContext classe dans chaque version linguistique du Kit de développement logiciel (SDK) Microsoft 365 Agents :

.NET : TurnContext
Python : TurnContext
JavaScript : TurnContext

Note

Les extraits de code de cet article utilisent C#. La syntaxe et la structure d’API pour les versions JavaScript et Python sont similaires.

TurnContext est un objet important utilisé à chaque échange de conversation dans le SDK Microsoft 365 Agents. Il fournit l’accès à l’activité entrante, aux méthodes d’envoi de réponses, à la gestion de l’état de conversation et au contexte nécessaire pour gérer un seul tour de conversation. Il est utilisé pour maintenir le contexte, envoyer des réponses appropriées et interagir efficacement avec vos utilisateurs dans leur client/canal. Chaque fois que votre agent reçoit une nouvelle activité à partir d’un canal, le Kit de développement logiciel (SDK) Agents crée une nouvelle TurnContext instance et le transmet à vos gestionnaires/méthodes inscrits. Cet objet de contexte existe pendant le tour unique, puis supprimé une fois le tour terminé.

Un tour est défini comme l’aller-retour d’un message envoyé par le client jusqu’à votre code : votre code traite ces données et peut, de manière optionnelle, envoyer une réponse pour compléter le tour. Ce aller-retour peut être divisé en :

Activité entrante : l’utilisateur envoie un message ou effectue une action qui crée une activité.
Votre code reçoit l’activité et l’agent la traite à l’aide de TurnContext.
Votre agent renvoie une ou plusieurs activités.
Le tour se termine et le TurnContext est éliminé.

Accédez aux données du TurnContext, telles que :

var messageText = turnContext.Activity.Text
var channelID = turnContext.Activity.ChannelId

Cet extrait de code montre un exemple de tour complet :

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

À l’intérieur de la TurnContext classe, les informations de clé couramment utilisées sont les suivantes :

Activité : le moyen principal d’obtenir des informations à partir de l’activité
Adaptateur : adaptateur de canal qui a créé l’activité
TurnState : état du tour

Types d’activité

Le type d’une activité est important, car il définit ce qui est requis ou attendu dans le reste de l’activité entre les clients, les utilisateurs et les agents.

Message

Un type d’activité courant est le type message de Activity, qui peut inclure du texte, des pièces jointes et des actions suggérées pour nommer quelques utilisations courantes pour ce type.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

Mise à jour de la conversation

Le type Activity avertit votre agent lorsque les membres rejoignent ou quittent une conversation. Tous les clients ne prennent pas cela en charge, mais un client notable qui le fait est Microsoft Teams.

L’extrait de code suivant salue les nouveaux membres d’une conversation :

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded
    if (membersAdded != null)
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Événements

Le type Événement de Activity sont des événements personnalisés qui permettent aux canaux ou aux clients d’envoyer des données structurées à votre assistant, ce qui n’est pas prédéfini dans la structure de charge utile Activity.

Vous devez créer un gestionnaire de méthode/de routage pour le type spécifique Event , puis gérer la logique souhaitée en fonction des éléments suivants :

Nom - Le nom ou identificateur de l’événement du client Valeur - Charge utile de l’événement qui est généralement un objet JSON

agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>)
{
    var eventName = turnContext.Activity.Name
    var eventValue = turnContext.Activity.Value

    // custom event (E.g. a switch on eventName)
}

Appeler

Un type Invoke est un type spécifique d’activité où un client demande à un agent d’exécuter une opération ou des instructions, et pas simplement d’envoyer un message. Les exemples de ces types d’activités sont courants dans Microsoft Teams pour task/fetch et task/submit. Tous les canaux ne prennent pas en charge ces types d’activités.

Typing

Un type de saisieActivity est une classification d’activité pour indiquer qu’une personne tape dans une conversation. Cela est souvent observé entre les conversations entre humains dans le client Microsoft Teams, par exemple. Les activités de saisie ne sont pas prises en charge dans chaque client, et notamment Microsoft 365 Copilot ne prend pas en charge les activités de saisie.

await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken); 
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken)

Créer et envoyer des activités

Pour envoyer des réponses, le « TurnContext » fournit plusieurs méthodes pour renvoyer des réponses à l’utilisateur.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
    await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken) // uses string directly
    await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken) // uses Message Factory
    await turnContext.SendActivitiesAsync(activities, cancellationToken) // send multiple activities in an Activity array
}

Utilisation des pièces jointes

Il est courant que les agents fonctionnent avec des pièces jointes soumises par des utilisateurs (ou même d’autres agents). Le client envoie une activité qui inclut une Message pièce jointe (ce n’est pas un type spécifique d’activité) et votre code doit gérer la réception du message avec la pièce jointe, lire les métadonnées et extraire en toute sécurité le fichier à partir de l’URL fournie par le client. Il serait courant de déplacer le fichier vers votre propre stockage.

Pour recevoir une pièce jointe

Le code suivant montre comment recevoir une pièce jointe

agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
    var activity = turnContext.Activity;
    if (activity.Attachments != null && activity.Attachments.Count >0)
    {
        foreach (var attachment in activity.Attachments)
        {
            // get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
            // use the URL to securely download the attachment and complete your business logic
        }
    }
}

En règle générale, pour recevoir le document sur la pièce jointe, le client envoie une demande authentifiée GET pour récupérer le contenu réel : chaque adaptateur a sa propre façon d’obtenir ces données, par exemple, Teams, OneDrive, et ainsi de suite. Il est également important de savoir que ces URL sont généralement de courte durée, et ne supposez donc pas qu’elles resteront là, ce qui explique pourquoi le déplacement vers votre propre stockage est important si vous devez vous référer à cette version ultérieure.

Références

Il est important de savoir que pièce jointe et citation ne sont pas du même type d’objet. Les références sont gérées par des applications clientes, comme Microsoft Teams, chacune de manière spécifique, et utilisent la propriété Entities de leur Activity système. Elles peuvent être ajoutées avec activity.Entities.Add , et on peut ajouter un nouvel objet Entity qui a une définition spécifique Citation en fonction de l'application cliente utilisée. Il serait sérialisé en tant qu’objet JSON que le client désérialise ensuite en fonction de la façon dont il s’affiche dans le client. Fondamentalement, les pièces jointes sont des messages, et les citations peuvent référencer des pièces jointes et sont un autre objet envoyé dans Entities la Activity charge utile.

Considérations spécifiques au canal

Le Kit de développement logiciel (SDK) Microsoft 365 Agents est conçu en tant que « hub » qui permet aux développeurs de créer des agents pouvant fonctionner avec n’importe quel client, y compris les clients que nous prenons en charge et de fournir aux développeurs les outils nécessaires pour créer leur propre adaptateur de canal à l’aide du même framework. Cela offre aux développeurs une large gamme d'options en matière d'agents et fournit aux clients la possibilité de se connecter à ce hub, qui peut être une ou plusieurs applications telles que Microsoft Teams, Slack, et d'autres.

Différents canaux ont des fonctionnalités et des limitations différentes, et voici un résumé des considérations relatives à l’utilisation de clients courants.

Vous pouvez vérifier le canal à partir duquel vous avez reçu l’activité en inspectant la channelId propriété dans le Activity.

Les canaux incluent des données spécifiques qui ne sont pas conformes à la charge utile générique Activity sur tous les canaux, et elles peuvent être accessibles à partir de TurnContext.Activity.ChannelData en les castant spécifiquement sur des variables à utiliser dans votre code.

Microsoft Teams

Prend en charge des cartes adaptatives enrichies avec des fonctionnalités avancées
Prend en charge les mises à jour et suppressions de messages
Contient des données de canal spécifiques pour les fonctionnalités de Teams (mentions, informations de réunion, et autres)
Prend en charge les activités d'invocation pour les modules de tâches

Microsoft 365 Copilot

Principalement axé sur les activités de messagerie
Prend en charge les citations et les références dans les réponses
Nécessite des réponses en flux continu
Prise en charge limitée des cartes enrichies/cartes adaptatives

WebChat/DirectLine

Web Chat est un protocole HTTP utilisé pour que les agents parlent via HTTPS

Prise en charge complète de tous les types d’activités
Prend en charge les données de canal personnalisées

Canaux tiers

Il s’agit notamment de Slack, Facebook et bien plus encore.

Peut avoir une prise en charge limitée de certains types d’activités
L'affichage de la carte peut être différent ou non pris en charge
Vérifier toujours la documentation de canal spécifique

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-10-21