Comprendre le protocole d’activité

Le protocole d’activité est un protocole de communication standard utilisé à travers Microsoft dans de nombreux SDK, services et clients Microsoft. Le protocole d’activité est utilisé par Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams et Microsoft 365 Agents SDK. Activity Protocol définit la structure d’une Activity et la façon dont les messages, événements et interactions circulent depuis un canal vers votre code et dans tous les autres contextes intermédiaires. Les assistants peuvent se connecter à un ou plusieurs canaux pour interagir avec les utilisateurs et collaborer avec d’autres assistants. Le protocole d’activité standardise le protocole de communication avec tout client avec lequel vous travaillez, y compris les clients Microsoft et non-Microsoft, afin que vous n’ayez pas à créer une logique personnalisée pour chaque canal.

Qu’est-ce qu’une activité ?

Une Activity est un objet JSON structuré qui représente toute interaction entre un utilisateur et votre assistant. Les activités ne se limitent pas aux messages textuels. Elles peuvent inclure divers types d’interactions, tels que des événements comme l’entrée ou la sortie d’un utilisateur pour des clients supportant plusieurs utilisateurs, des indicateurs de saisie, des téléversements de fichiers, des actions de carte et des événements personnalisés conçus par les développeurs.

Chaque activité inclut des métadonnées concernant :

Qui l’a envoyé (de)
Qui doit le recevoir (destinataire)
Contexte de la conversation
Le canal d’où il provient
Le type d’interaction
Les données de la charge utile

Schéma d’activité - propriétés clés

Cette spécification définit le Protocole d’Activité : Protocole d’Activité - Activité. Certaines des propriétés clés définies dans le protocole d’activité sont :

Propriété	Description
`Id`	Généralement généré par le canal si l’activité provient d’un canal
`Type`	Le type contrôle la signification d’une activité, par exemple le type de message
`ChannelID`	Le `ChannelID` fait référence au canal d’origine de l’activité. Par exemple : `msteams`.
`From`	L’expéditeur de l’activité (qui peut être un utilisateur ou un assistant)
`Recipient`	Le destinataire cible de l’activité
`Text`	Le texte du message
`Attachment`	Contenu riche comme des cartes, images de fichiers

Accéder aux données d’activité

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

Vous pouvez trouver une classe TurnContext dans chaque version de langue du Microsoft 365 Agents SDK :

.NET : TurnContext
Python : TurnContext
JavaScript : TurnContext

Note

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

TurnContext est un objet important utilisé à chaque tour de conversation dans le Microsoft 365 Agents SDK. Il donne accès à l’activité entrante, aux méthodes d’envoi de réponses, à la gestion de l’état de la conversation, ainsi qu’au contexte nécessaire pour gérer un seul tour de conversation. Utilisez-le pour maintenir le contexte, envoyer des réponses appropriées et interagir efficacement avec vos utilisateurs dans leur client ou leur canal. Chaque fois que votre assistant reçoit une nouvelle activité d’un canal, le SDK des assistants crée une instance TurnContext et la transmet à vos gestionnaires ou méthodes enregistrés. Cet objet de contexte existe pendant le tour unique et est ensuite éliminé une fois le tour terminé.

Un tour est défini comme l’aller-retour d’un message envoyé depuis le client jusqu’à votre code. Votre code gère ces données et peut éventuellement envoyer une réponse pour compléter le tour. Ce trajet aller-retour peut être décomposé en étapes suivantes :

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

Accéder aux données de TurnContext, comme :

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

Cet extrait de code montre un exemple d’un 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);
});

Au sein de la classe TurnContext, les informations clés couramment utilisées incluent :

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

Types d’activité

Le type d’activité définit ce que le reste de l’activité exige ou attend entre clients, utilisateurs et assistants.

notamment les suivants :

Message
ConversationUpdate
Événement
Appeler
Saisie

Message

Un type d’activité courant est le type Message d’Activity. Ce type Activity peut inclure du texte, des pièces jointes et des actions suggérées.

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

ConversationUpdate

Le type ConversationUpdate d’Activity informe votre assistant lorsque des membres rejoignent ou quittent une conversation. Tous les clients ne prennent pas en charge cette notification, mais Microsoft Teams la prend en charge.

L’extrait de code suivant accueille les nouveaux membres dans 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.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Événements

Le type Événement d’Activity est un événement personnalisé utilisé par les canaux ou les clients pour envoyer des données structurées à votre assistant. Ces données ne sont pas prédéfinies dans la structure de la charge utile Activity.

Vous devez créer une méthode ou un gestionnaire de route pour le type Event spécifique. Ensuite, gérez la logique souhaitée en fonction de :

Nom : Le nom de l’événement ou l’identifiant fourni par le client
Valeur : Charge utile d’é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 Invoquer est Activity un type d’activité spécifique qu’un client appelle dans un assistant pour exécuter une commande ou une opération. Ce n’est pas simplement un message. Des exemples de ces types d’activités sont courants dans Microsoft Teams pour task/fetch et task/submit. Ces types d’activités ne sont pas pris en charge par tous les canaux.

Saisie

Un type Saisie d’Activity est une classification de l’activité pour indiquer qu’un utilisateur saisit du texte dans une conversation. Cette activité est couramment observée lors de conversations entre humains dans le client Microsoft Teams, par exemple. Les activités de saisie ne sont pas prises en charge dans tous les clients. 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, TurnContext fournit plusieurs méthodes pour envoyer 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

Les assistants travaillent souvent avec des pièces jointes que les utilisateurs (ou même d’autres assistants) envoient. Le client envoie une activité Message qui inclut une pièce jointe (il ne s’agit pas d’un type d’activité particulier). Votre code doit gérer la réception du message avec la pièce jointe, lire les métadonnées et récupérer le fichier en toute sécurité à partir de l’URL fournie par le client. En général, vous déplacez le fichier dans 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 général, pour recevoir le fichier associé à la pièce jointe, le client envoie une requête authentifiée GET afin d’en récupérer le contenu réel. Chaque adaptateur a sa propre façon d’obtenir ces données. Par exemple, Teams, OneDrive, etc. Il est également important de savoir que ces URL sont généralement temporaires ; il ne faut donc pas supposer qu’elles restent valides longtemps. Cette limitation explique pourquoi il est important de passer à votre propre stockage si vous devez consulter le contenu plus tard.

Références

Il est important de savoir que Pièces jointe et Citation ne sont pas du même type d’objet. Les clients, tels que Microsoft Teams, traitent les citations à leur manière. Ils utilisent la propriété Entités de l’Activity. Vous pouvez ajouter des citations avec activity.Entities.Add et ajouter un nouvel objet Entity qui possède la définition spécifique Citation selon votre client. Il est sérialisé en tant qu’objet JSON que le client désérialise ensuite en fonction de son rendu 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 de la charge utile Activity.

Considérations spécifiques au canal

Le Microsoft 365 Agents SDK est conçu comme un « hub » que les développeurs utilisent pour créer des assistants pouvant fonctionner avec tout client, y compris les clients que nous prenons en charge. Il fournit aux développeurs les outils pour construire leur propre adaptateur de canal en utilisant le même framework. Cette architecture offre aux développeurs une grande flexibilité en matière d’assistants et fournit une extensibilité aux clients pour se connecter à ce hub, qui peut inclure un ou plusieurs clients comme Microsoft Teams, Slack, et d’autres.

Les différents canaux ont leurs propres capacités et limitations.

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

Les canaux incluent des données spécifiques qui ne se conforment pas à la charge utile générique Activity commune à tous les canaux. Vous pouvez accéder à ces données depuis la propriété TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) en les lançant dans des variables pour les utiliser dans votre code.

Les sections suivantes résument les considérations à considérer lors du travail avec des clients ordinaires.

Microsoft Teams

Prend en charge les cartes adaptatives riches 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, comme les mentions et les informations de réunion.
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 références dans les réponses.
Nécessite des réponses en streaming.
Prise en charge limitée des cartes riches et cartes adaptatives.

Chat Web/DirectLine

Chat Web est un protocole HTTP que les assistants peuvent utiliser pour communiquer via HTTPS.

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

Canaux hors Microsoft

Ces canaux incluent Slack, Facebook, et bien d’autres.

Le support peut être limité pour certains types d’activité.
Le rendu de la carte peut être différent ou non pris en charge.
Consultez la documentation spécifique à chaque canal.

Étapes suivantes

Découvrez AgentApplication

Commentaires

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

Last updated on 2026-07-30