Begrip van activiteitenprotocol

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

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 berichten op basis van tekst. Ze kunnen verschillende soorten interactie bevatten, zoals gebeurtenissen zoals een gebruiker die deelneemt of verlaat voor clients die meerdere gebruikers ondersteunen, indicatoren typen, bestandsuploads, kaartacties en aangepaste gebeurtenissen die ontwikkelaars ontwerpen.

Elke activiteit bevat metagegevens over:

• Wie heeft het verzonden?
• Wie moet het ontvangen (ontvanger)
• De gesprekscontext
• Het kanaal waaruit het afkomstig is
• Het type interactie
• De payloadgegevens

Activiteitsschema - belangrijkste eigenschappen

Deze specificatie definieert het Activity Protocol: Activity Protocol - Activity. Enkele van de belangrijkste eigenschappen die zijn gedefinieerd in Activity Protocol zijn:

Property	Description
Id	Meestal gegenereerd door het kanaal als deze afkomstig is van een kanaal
Type	Het type bepaalt de betekenis van een activiteit, bijvoorbeeld berichttype
ChannelID	Het ChannelID verwijst naar het kanaal waaruit de activiteit afkomstig is. Bijvoorbeeld: msteams.
From	De afzender van de activiteit (die een gebruiker of agent kan zijn)
Recipient	De beoogde ontvanger van de activiteit
Text	De tekstinhoud van het bericht
Attachment	Uitgebreide inhoud zoals kaarten, afbeeldingen van bestanden

Toegang tot activiteitsgegevens

Ontwikkelaars moeten toegang krijgen tot de gegevens in de activiteit om acties van het TurnContext object te voltooien.

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

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

Note

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

De TurnContext is een belangrijk object dat in elk gesprek wordt gebruikt in de SDK voor Microsoft 365-agenten. Het biedt toegang tot de binnenkomende activiteit, methoden voor het verzenden van antwoorden, gespreksstatusbeheer en de context die nodig is voor het afhandelen van één gespreksdraai. Gebruik deze functie om context te onderhouden, de juiste antwoorden te verzenden en effectief te communiceren met uw gebruikers in hun client of kanaal. Telkens wanneer uw agent een nieuwe activiteit van een kanaal ontvangt, maakt de Agents SDK een nieuw TurnContext exemplaar en geeft deze door aan uw geregistreerde handlers of methoden. Dit contextobject bestaat tijdens de enkele draai en wordt vervolgens verwijderd zodra de draai eindigt.

Een rondgang wordt gedefinieerd als de retour van een bericht dat van de client wordt verzonden en terugkeert naar uw code. Uw code verwerkt die gegevens en kan eventueel een antwoord terugsturen om de beurt te voltooien. Deze rondreis kan worden opgesplitst in deze stappen:

1. Binnenkomende activiteit: de gebruiker verzendt een bericht of voert een actie uit waarmee een activiteit wordt gemaakt.

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 draai eindigt en de TurnContext wordt verwijderd.

Toegang tot gegevens uit de TurnContext, zoals:

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

Dit codefragment toont een voorbeeld van een volledige draai:

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 omvat veelgebruikte belangrijke informatie:

• Activiteit: De belangrijkste manier om informatie op te halen uit de activiteit
• Adapter: de kanaaladapter die de activiteit heeft gemaakt
• TurnState: De status voor de draai

Typen activiteit

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

Deze omvatten:

• Message
• ConversationUpdate
• Gebeurtenis
• Invoke
• Typen

Message

Een veelvoorkomend type activiteit is het berichttypeActivity. 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 type Activity geeft uw agent een bericht 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);
            }
        }
    }
})

Evenementen

Het gebeurtenistypeActivity 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 route-handler maken voor het specifieke Event type. Beheer vervolgens de gewenste logica op basis van:

• Naam: de gebeurtenisnaam of id van de client
• Waarde: Nettolading van gebeurtenissen die doorgaans een JSON-object is

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

Invoke

Een aanroeptypeActivity is een specifiek type activiteit dat een client aanroept naar een agent om een opdracht of bewerking uit te voeren. Het is niet alleen een boodschap. Voorbeelden van deze typen activiteiten zijn gebruikelijk in Microsoft Teams voor task/fetch en task/submit. Niet alle kanalen ondersteunen dit soort activiteiten.

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 tussen menselijke tot menselijke gesprekken in Microsoft Teams client, bijvoorbeeld. Activiteiten typen worden niet in elke client ondersteund. Met name Microsoft 365 Copilot biedt geen ondersteuning voor het typen van activiteiten.

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

Als u antwoorden wilt verzenden, biedt de TurnContext functie meerdere methoden voor het terugsturen van antwoorden 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

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

Om een bijlage te ontvangen

De volgende code laat zien hoe u een bijlage ontvangt.

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 geverifieerde GET aanvraag om de werkelijke inhoud op te halen om het document voor de bijlage te ontvangen. Elke adapter heeft een eigen manier om die gegevens op te halen. Bijvoorbeeld Teams, OneDrive, enzovoort. Het is ook belangrijk om te weten dat deze URL's doorgaans kort duren en dus niet aannemen dat de URL's lang geldig blijven. Deze beperking is waarom het verplaatsen naar uw eigen opslag belangrijk is als u later naar de inhoud wilt verwijzen.

Citaten

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

Kanaalspecifieke overwegingen

De SDK voor Microsoft 365-agenten is gebouwd als een hub die ontwikkelaars gebruiken om agents te maken die kunnen werken met any-client, met inbegrip van de clients die we ondersteunen. Het biedt de hulpprogramma's voor ontwikkelaars om hun eigen kanaaladapter te bouwen met behulp van hetzelfde framework. Deze architectuur biedt ontwikkelaars veel breedte als het gaat om agents en biedt uitbreidbaarheid voor clients om verbinding te maken met die hub. Dit kan een of meer clients zijn, zoals Microsoft Teams, Slack en meer.

Verschillende kanalen hebben verschillende mogelijkheden en beperkingen.

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

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

In de volgende secties vindt u een overzicht van overwegingen bij het werken met algemene clients.

Microsoft Teams

• Ondersteunt uitgebreide Adaptieve kaarten met geavanceerde functies.
• Ondersteunt berichtupdates en verwijderingen.
• Heeft specifieke kanaalgegevens voor Teams-functies, zoals vermeldingen en vergaderingsgegevens.
• Ondersteunt het aanroepen van activiteiten voor taakmodules.

Microsoft 365 Copilot

• Voornamelijk gericht op berichtactiviteiten.
• Ondersteunt bronvermeldingen en verwijzingen in antwoorden.
• Vereist streaming-antwoorden.
• Beperkte ondersteuning voor uitgebreide kaarten en adaptieve kaarten.

Webchat/DirectLine

Webchat is een HTTP-protocol dat agents 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.

• Er kan beperkte ondersteuning zijn voor bepaalde activiteitstypen.
• Kaartweergave kan afwijken of niet worden ondersteund.
• Raadpleeg altijd specifieke kanaaldocumentatie.

Volgende stappen 

• Meer informatie over AgentApplication