Activiteitenprotocol begrijpen

Het Activiteitenprotocol is een standaard communicatieprotocol dat door Microsoft in veel Microsoft SDK's, services en clients wordt gebruikt. Het Activiteitenprotocol wordt gebruikt door Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams en de SDK voor Microsoft 365-agenten. Het Activiteitenprotocol definieert de structuur van een Activity en hoe berichten, gebeurtenissen en interacties van een kanaal naar uw code en alle tussenliggende stappen stromen. Agents kunnen verbinding maken met een of meer kanalen om met gebruikers te communiceren en met andere agents samen te werken. Het Activiteitenprotocol standaardiseert het communicatieprotocol met elke client waarmee u werkt, inclusief Microsoft- en niet-Microsoft-clients, zodat u geen aangepaste logica voor elk kanaal hoeft te schrijven.

Wat is een activiteit?

Een Activity is een gestructureerd JSON-object dat elke interactie tussen een gebruiker en uw agent vertegenwoordigt. Activiteiten zijn niet beperkt tot tekstberichten. Ze kunnen verschillende soorten interacties omvatten, zoals gebeurtenissen zoals het toetreden of verlaten van een gebruiker voor clients die meerdere gebruikers ondersteunen, typindicatoren, bestandsuploads, kaartacties en aangepaste gebeurtenissen die door ontwikkelaars worden ontworpen.

Elke activiteit bevat metadata over:

• Wie het heeft verzonden (van)
• Wie het moet ontvangen (ontvanger)
• De conversatiecontext
• Het kanaal waar het vandaan komt
• Het type interactie
• De payloadgegevens

Activiteitsschema - belangrijke eigenschappen

Deze specificatie definieert het Activiteitsprotocol: Activiteitsprotocol - Activiteit. Enkele van de belangrijkste eigenschappen die in het Activiteitsprotocol zijn gedefinieerd, zijn:

Eigenschap	Omschrijving
Id	Doorgaans gegenereerd door het kanaal als het afkomstig is van een kanaal
Type	Het type bepaalt de betekenis van een activiteit, bijvoorbeeld het berichttype
ChannelID	De ChannelID verwijst naar het kanaal waar de activiteit vandaan komt. Voorbeeld: msteams.
From	De afzender van de activiteit (dit kan een gebruiker of agent zijn)
Recipient	De beoogde ontvanger van de activiteit
Text	De tekstinhoud van het bericht
Attachment	Rijke inhoud zoals kaarten, afbeeldingen of bestanden

Toegang tot activiteitsgegevens

Om acties van het TurnContext-object te voltooien, moeten ontwikkelaars toegang hebben tot de gegevens binnen de activiteit.

U vindt een TurnContext-klasse in elke taalversie van de SDK voor Microsoft 365-agenten:

• .NET: TurnContext
• Python: TurnContext
• JavaScript: TurnContext

Notitie

De codefragmenten in dit artikel gebruiken C#. De syntaxis en API-structuur voor de JavaScript- en Python-versies zijn vergelijkbaar.

De TurnContext is een belangrijk object dat in elke gespreksronde in de SDK voor Microsoft 365-agenten wordt gebruikt. Het biedt toegang tot de binnenkomende activiteit, methoden voor het verzenden van reacties, beheer van de gespreksstatus en de context die nodig is om een ​​enkele gespreksronde af te handelen. Gebruik het om de context te behouden, passende reacties te verzenden en effectief met uw gebruikers in hun client of kanaal te communiceren. Telkens wanneer uw agent een nieuwe activiteit van een kanaal ontvangt, maakt de Agents SDK een nieuwe TurnContext instantie aan en geeft deze door aan uw geregistreerde handlers of methoden. Dit contextobject bestaat gedurende de enkele gespreksronde en wordt vervolgens verwijderd zodra de ronde is afgelopen.

Een ronde wordt gedefinieerd als de heen-en-terugreis van een bericht dat vanaf de client wordt verzonden en zijn weg vindt naar uw code. Uw code verwerkt die gegevens en kan optioneel een reactie terugsturen om de ronde te voltooien. Die heen-en-terugreis kan worden opgesplitst in de volgende stappen:

1. Inkomende activiteit: De gebruiker verzendt een bericht of voert een actie uit die een activiteit creëert.

2. Uw code ontvangt de activiteit en de agent verwerkt deze met behulp van TurnContext.

3. Uw agent stuurt een of meer activiteiten terug.

4. De beurt eindigt en de TurnContext wordt verwijderd.

Toegang tot gegevens van de TurnContext, zoals:

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

Dit codefragment toont een voorbeeld van een complete beurt:

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

Binnen de TurnContext-klasse wordt vaak de volgende sleutelinformatie gebruikt:

• Activiteit: De belangrijkste manier om informatie van de activiteit te verkrijgen
• Adapter: De kanaaladapter die de activiteit heeft aangemaakt
• Beurtstatus: De status van de beurt

Typen activiteit

Het type van een activiteit definieert wat de rest van de activiteit vereist of verwacht tussen clients, gebruikers en agenten.

Hieronder vallen:

• Bericht
• ConversationUpdate
• Gebeurtenis
• Aanroepen
• Typen

Bericht

Een veelvoorkomend type activiteit is het Bericht type van Activity. Dit Activity type kan tekst, bijlagen en voorgestelde acties bevatten.

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

Het ConversationUpdate type van Activity stelt uw agent op de hoogte wanneer leden deelnemen aan of een gesprek verlaten. Niet alle clients ondersteunen deze melding, maar Microsoft Teams wel.

Het volgende codefragment begroet nieuwe leden in een gesprek:

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

Gebeurtenissen

Een gebeurtenis van het type Activity is een aangepaste gebeurtenis die kanalen of clients gebruiken om gestructureerde gegevens naar uw agent te verzenden. Deze gegevens zijn niet vooraf gedefinieerd in de Activity payloadstructuur.

U moet een methode of routehandler maken voor het specifieke Event type. Beheer vervolgens de gewenste logica op basis van:

• Naam: De naam of identificatiecode van de gebeurtenis van de client
• Waarde: De payload van de gebeurtenis, meestal een JSON-object

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

Aanroepen

Een Invoke-type van Activity is een specifiek type activiteit waarbij een client een agent aanroept om een ​​opdracht of bewerking uit te voeren. Het is niet zomaar een bericht. Voorbeelden van dit soort activiteiten komen vaak voor in Microsoft Teams voor task/fetch en task/submit. Niet alle kanalen ondersteunen dit soort activiteiten.

Bezig met typen

Een activiteittype Aan het typen is een classificatie Activity van de activiteit om aan te geven dat iemand aan het typen is in een gesprek. Deze activiteit wordt vaak gezien bij mens-tot-mens-gesprekken in bijvoorbeeld de Microsoft Teams-client. Typactiviteiten worden niet in elke client ondersteund. Met name Microsoft 365 Copilot ondersteunt geen typactiviteiten.

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

Activiteiten maken en verzenden

Om reacties te verzenden, biedt de TurnContextmeerdere methoden om reacties terug te sturen naar de gebruiker.

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
}

Werken met bijlagen

Agenten werken vaak met bijlagen die gebruikers (of zelfs andere agenten) indienen. De client verzendt een Message-activiteit die een bijlage bevat (het is geen specifiek type activiteit). Uw code moet het bericht met de bijlage ontvangen, de metadata lezen en het bestand veilig ophalen van de URL die de client heeft opgegeven. Normaal gesproken verplaatst u het bestand naar uw eigen opslag.

Een bijlage ontvangen

De volgende code laat zien hoe u een bijlage kunt ontvangen.

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

Normaal gesproken verzendt de client een geauthenticeerd GET-verzoek om de daadwerkelijke inhoud van de bijlage op te halen. Elke adapter heeft zijn eigen manier om die gegevens te verkrijgen. Bijvoorbeeld Teams, OneDrive, enzovoort. Het is ook belangrijk om te weten dat die URL's doorgaans een korte levensduur hebben, dus ga er niet vanuit dat de URL's lang geldig blijven. Deze beperking is de reden waarom het belangrijk is om de gegevens naar uw eigen opslag te verplaatsen als u de inhoud later wilt raadplegen.

Citaten

Het is belangrijk om te weten dat Bijlage en Citaat niet hetzelfde objecttype zijn. Clients, zoals Microsoft Teams, behandelen citaten op hun eigen manier. Ze gebruiken de Entiteiten-eigenschap van de Activity. U kunt citaten toevoegen met activity.Entities.Add en een nieuw Entity-object toevoegen met de specifieke Citation-definitie op basis van uw client. Het wordt geserialiseerd als een JSON-object dat de client vervolgens deserialiseert op basis van hoe het in de client wordt weergegeven. In principe zijn bijlagen berichten, en citaten kunnen naar bijlagen verwijzen en zijn een ander object dat wordt verzonden in Entities van de payload Activity.

Kanaalspecifieke overwegingen

De SDK voor Microsoft 365-agenten is gebouwd als een 'hub' die ontwikkelaars gebruiken om agents te maken die kunnen werken met elke client, inclusief de clients die wij ondersteunen. Het biedt ontwikkelaars de tools om hun eigen kanaaladapter te bouwen met behulp van hetzelfde framework. Deze architectuur geeft ontwikkelaars een brede reeks mogelijkheden als het gaat om agents en biedt uitbreidbaarheid voor clients om verbinding te maken met die hub, die één of meer clients kan zijn, zoals Microsoft Teams, Slack en meer.

Verschillende kanalen hebben verschillende mogelijkheden en beperkingen.

U kunt controleren van welk kanaal u de activiteit hebt ontvangen door de eigenschap channelId in de Activity te inspecteren.

Kanalen bevatten specifieke gegevens die niet overeenkomen met de generieke payload Activity voor alle kanalen. U kunt deze gegevens van de TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata)-eigenschap benaderen door ze naar variabelen te casten voor gebruik in uw code.

De volgende secties geven een overzicht van de aandachtspunten bij het werken met veelvoorkomende clients.

Microsoft Teams

• Ondersteunt uitgebreide Adaptieve kaarten met geavanceerde functies.
• Ondersteunt het bijwerken en verwijderen van berichten.
• Beschikt over specifieke kanaalgegevens voor Teams-functies, zoals vermeldingen en vergaderinformatie.
• Ondersteunt het aanroepen van activiteiten voor taakmodules.

Microsoft 365 Copilot

• Voornamelijk gericht op berichtactiviteiten.
• Ondersteunt citaten en referenties in antwoorden.
• Vereist streamingantwoorden.
• Beperkte ondersteuning voor uitgebreide kaarten en adaptieve kaarten.

Webchat/DirectLine

Webchat is een HTTP-protocol dat agenten kunnen gebruiken om via HTTPS te communiceren.

• Volledige ondersteuning voor alle activiteitstypen.
• Ondersteunt aangepaste kanaalgegevens.

Niet-Microsoft-kanalen

Deze kanalen omvatten Slack, Facebook en meer.

• Mogelijk beperkte ondersteuning voor bepaalde activiteitstypen.
• De weergave van kaarten kan afwijken of niet worden ondersteund.
• Controleer altijd de specifieke kanaaldocumentatie.

Volgende stappen

• Meer informatie over AgentApplication