Informatie over het Activiteitenprotocol

Het activiteitsprotocol is het communicatieprotocol en het standaardprotocol dat wordt gebruikt in Microsoft in veel Microsoft SDK's, -services en -clients. Dit omvat Microsoft 365 Copilot, Microsoft Copilot Studio en de Microsoft 365 Agents SDK. Het activiteitsprotocol definieert de vorm van een Activity en hoe berichten, gebeurtenissen en interacties van kanaal naar uw code en overal daartussen stromen. Agents kunnen verbinding maken met een of meer kanalen om te communiceren met gebruikers en met andere agents te werken. Het Activity-protocol standaardiseert het communicatieprotocol tussen elke client waarmee u werkt, inclusief Clients van Microsoft en derden, zodat u geen aangepaste logica hoeft te maken per kanaal waarmee u werkt.

Wat is een activiteit?

Een Activity is een gestructureerd JSON-object dat elke interactie tussen een gebruiker en uw agent vertegenwoordigt. Activiteiten zijn niet alleen op tekst gebaseerde berichten, ze kunnen verschillende soorten interactie bevatten, waaronder gebeurtenissen zoals een gebruiker die deelneemt aan of verlaat voor klanten die meerdere gebruikers ondersteunen, indicatoren typen, bestandsuploads, kaartacties en aangepaste gebeurtenissen die ontwikkelaars zelf 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 activiteitsprotocol: Activiteitsprotocol - Activiteit. Enkele van de belangrijkste eigenschappen die zijn gedefinieerd in het activiteitenprotocol zijn:

Vastgoed	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. Voorbeeld: `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 binnen de activiteit om acties van het TurnContext object te voltooien.

U vindt een TurnContext klasse in elke taalversie van de Microsoft 365 Agents SDK:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Opmerking

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

Het TurnContext is een belangrijk object dat wordt gebruikt in elke gesprekswisseling in de Microsoft 365 Agents SDK. 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. Het wordt gebruikt om context te onderhouden, geschikte antwoorden te verzenden en effectief te communiceren met uw gebruikers in hun client/kanaal. Telkens wanneer uw agent een nieuwe activiteit ontvangt van een kanaal, maakt de Agents SDK een nieuw TurnContext exemplaar en geeft deze door aan uw geregistreerde handlers/methoden. Dit contextobject bestaat tijdens de enkele draai en wordt vervolgens verwijderd zodra de draai eindigt.

Een ronde wordt gedefinieerd als de heen-en-weerbeweging van een bericht dat van de cliënt wordt verzonden, door uw code wordt verwerkt en waarop de code een reactie kan sturen om de ronde te voltooien. Die rondreis kan worden opgesplitst in:

Binnenkomende activiteit: de gebruiker verzendt een bericht of voert een actie uit waarmee een activiteit wordt gemaakt.
Uw code ontvangt de activiteit en de agent verwerkt deze met behulp van TurnContext.
Uw agent stuurt een of meer activiteiten terug.
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 is belangrijk omdat hiermee wordt gedefinieerd wat vereist of verwacht is in de rest van de activiteit tussen clients, gebruikers en agents.

Message

Een veelvoorkomend type activiteit is het berichttypeActivity, dat tekst, bijlagen en voorgestelde acties kan bevatten om een aantal veelgebruikte toepassingen voor dit type te noemen.

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 dit, een opmerkelijke client die dat wel doet, is Microsoft Teams.

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

Evenementen

Het eventtype van Activity zijn aangepaste gebeurtenissen waarmee kanalen of clients gestructureerde gegevens naar uw agent kunnen verzenden, wat niet vooraf gedefinieerd is in de Activity payload-structuur.

U moet een methode/route-handler maken voor het specifieke Event type en vervolgens de gewenste logica beheren op basis van:

Naam - De gebeurtenisnaam of id van de client Waarde - Gegevenspayload van gebeurtenis 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, en niet alleen een bericht. Voorbeelden van deze typen activiteiten zijn gebruikelijk in Microsoft Teams voor task/fetch en task/submit. Niet alle kanalen ondersteunen dit type 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. Dit wordt vaak gezien tussen menselijke tot menselijke gesprekken in de Microsoft Teams-client, bijvoorbeeld. Typen van activiteiten wordt niet ondersteund in elke client, en met name Microsoft 365 Copilot biedt geen ondersteuning voor typen.

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 TurnContext 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

Het is gebruikelijk dat agents werken met bijlagen die zijn verzonden door gebruikers (of zelfs andere agents). De client verzendt een Message activiteit die een bijlage bevat (dit is geen specifiek type activiteit) en 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. Het is gebruikelijk om het bestand vervolgens naar uw eigen opslag te verplaatsen.

Om een bijlage te ontvangen

De volgende code laat zien hoe u een bijlage ontvangt en toevoegt.

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 te ontvangen in de bijlage. 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 meestal kort duren en dus niet aannemen dat ze daar blijven. Daarom is het belangrijk om naar uw eigen opslag te gaan als u dit later moet raadplegen.

Citaten

Het is belangrijk te weten dat bijlage en bronvermelding niet hetzelfde objecttype zijn. Citaten worden op hun eigen manier afgehandeld door clients, zoals Microsoft Teams, en gebruiken de eigenschap Entiteiten van de Activity en kunnen worden toegevoegd met activity.Entities.Add en een nieuw Entity object toevoegen dat de specifieke Citation definitie op basis van uw client heeft. Het wordt geserialiseerd als een JSON-object dat de client vervolgens ontserialiseerd op basis van de weergave in de client. Bijlagen zijn in feite berichten, en bronvermeldingen kunnen naar bijlagen verwijzen en vormen een ander object dat binnen de Entities van de Activity payload wordt verzonden.

Kanaalspecifieke overwegingen

De Microsoft 365 Agents SDK is gebouwd als een hub waarmee de ontwikkelaars agents kunnen maken die met elke client kunnen werken, met inbegrip van de clients die we ondersteunen en de hulpprogramma's bieden voor ontwikkelaars om hun eigen kanaaladapter te bouwen met hetzelfde framework. Dit 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 en het volgende is een overzicht van overwegingen bij het werken met algemene clients.

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

Kanalen bevatten specifieke gegevens die niet voldoen aan de algemene Activity payload in alle kanalen en die kunnen worden benaderd vanuit de TurnContext.Activity.ChannelData, waarbij deze specifiek kunnen worden omgezet naar variabelen voor gebruik in uw code.

Microsoft Teams

Ondersteunt uitgebreide adaptieve kaarten met geavanceerde functies
Ondersteunt berichtupdates en verwijderingen
Heeft specifieke kanaalgegevens voor Teams-functies (vermeldingen, vergaderingsgegevens, enzovoort)
Ondersteunt het aanroepen van activiteiten voor taakmodules

Microsoft 365 Copilot

Voornamelijk gericht op berichtactiviteiten
Ondersteunt bronvermeldingen en verwijzingen in antwoorden
Streaming-antwoorden vereist
Beperkte ondersteuning voor uitgebreide kaarten/adaptieve kaarten

WebChat/DirectLine

Web Chat is een HTTP-protocol dat wordt gebruikt voor agents om via HTTPS te praten

Volledige ondersteuning voor alle activiteitstypen
Ondersteunt aangepaste kanaalgegevens

Kanalen van derden

Dit zijn Slack, Facebook en meer.

Kan beperkte ondersteuning hebben voor bepaalde activiteitstypen
Kaartweergave kan afwijken of niet worden ondersteund
Altijd specifieke kanaaldocumentatie controleren

Feedback

Is deze pagina nuttig?

Last updated on 2025-10-29