Présentation du protocole d’activité

Le protocole d’activité est un protocole de communication standard utilisé dans Microsoft dans de nombreux kits sdk, services et clients Microsoft. Le protocole d’activité est utilisé par Microsoft 365 Copilot, Microsoft Copilot Studio et le Microsoft 365 Agents SDK. Le protocole d’activité définit la structure d’un Activity flux de messages, d’événements et d’interactions d’un canal vers 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 avec n'importe quel client avec lequel vous travaillez, y compris les clients Microsoft et non-Microsoft, afin que vous n'ayez pas à créer de logique personnalisée pour chaque canal.

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 limitées aux messages texte. Ils peuvent inclure différents types d’interaction, tels que des événements tels qu’un utilisateur joint ou laissant pour les clients qui prennent en charge plusieurs utilisateurs, les indicateurs de saisie, les chargements de fichiers, les actions de carte et les événements personnalisés que les développeurs conçoivent.

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é	Description
`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é

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

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.

Un TurnContext est un objet important utilisé lors de chaque tour 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. Utilisez-le pour maintenir le contexte, envoyer les réponses appropriées et interagir efficacement avec vos utilisateurs dans leur client ou 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 ou méthodes inscrits. Cet objet de contexte existe pendant le tour unique et est ensuite supprimé une fois le tour terminé.

Un cycle est défini comme l’aller-retour d’un message envoyé par le client et faisant le trajet jusqu'à votre code. Votre code gère ces données et peut éventuellement renvoyer une réponse pour terminer le tour. Cet aller-retour peut être divisé 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’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é définit ce que le reste de l’activité requiert ou attend entre les clients, les utilisateurs et les agents.

Ceux-ci comprennent :

Message
Mise à jour de la conversation
Evénement
Appeler
Typing

Message

Un type d’activité courant est le type message de Activity. Ce Activity type 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);
});

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 en charge cette notification, mais Microsoft Teams le fait.

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.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Événements

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

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

Nom : nom ou identificateur de l’événement du 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 Invoke est Activity un type spécifique d’activité qu’un client appelle dans un agent pour effectuer une commande ou une opération. Ce n’est pas seulement 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. Cette activité est généralement observée entre conversations humaines sur le client Microsoft Teams, par exemple. Les activités de saisie ne sont pas prises en charge dans chaque client. 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, la méthode 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

Les agents fonctionnent souvent avec des pièces jointes que les utilisateurs (ou même d’autres agents) envoient. Le client envoie une activité qui inclut une Message pièce jointe (ce n’est pas un type spécifique d’activité). 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. En règle générale, vous déplacez 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 de 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 que les URL restent valides pendant longtemps. Cette limitation est pourquoi le passage à votre propre stockage est important si vous devez faire référence au contenu ultérieurement.

Références

Il est important de savoir que pièce jointe et citation ne sont pas du même type d’objet. Les clients, comme Microsoft Teams, gèrent les citations de leur propre manière. Ils utilisent la propriété Entities de l’objet Activity. Vous pouvez ajouter des citations avec activity.Entities.Add et ajouter un nouvel Entity objet qui a la définition spécifique Citation basée sur votre client. Il est 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 Microsoft 365 Agents SDK est créé en tant que « Hub » que les développeurs utilisent pour créer des agents qui peuvent fonctionner avec any client, y compris les clients que nous prenons en charge. Il fournit aux développeurs les outils permettant aux développeurs de créer leur propre adaptateur de canal à l’aide du même framework. Cette architecture offre aux développeurs une étendue en ce qui concerne les agents et fournit une extensibilité aux clients pour se connecter à ce hub, qui peut être un ou plusieurs clients tels que Microsoft Teams, Slack, etc.

Différents canaux ont des fonctionnalités et des limitations différentes.

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. Vous pouvez accéder à ces données à partir de la TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) propriété en les castant en variables à utiliser dans votre code.

Les sections suivantes résument les considérations lors de l'utilisation avec des clients habituels.

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 Teams, telles que les mentions et les informations sur les réunions.
Prend en charge les activités d’invocation pour les modules de tâche.

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.
Prise en charge limitée des cartes enrichies et des cartes adaptatives.

Chat Web/DirectLine

Chat Web est un protocole HTTP que les agents peuvent utiliser pour communiquer 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 non Microsoft

Ces canaux incluent 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érifiez toujours la documentation de canal spécifique.

Étapes suivantes

En savoir plus sur AgentApplication

Commentaires

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

Last updated on 2026-04-29