Om aktivitetsprotokollen

Aktivitetsprotokollen er kommunikationsprotokollen og standardprotokollen, der bruges på tværs af Microsoft i mange Microsoft-SDK'er, -tjenester og -klienter. Dette omfatter Microsoft 365 Copilot, Microsoft Copilot Studio og Microsoft 365 Agents SDK. Protokollen Aktivitet definerer formen af en Activity , og hvordan meddelelser, hændelser og interaktioner flyder fra kanal til din kode og alle andre steder imellem. Agenter kan oprette forbindelse til en eller flere kanaler for at interagere med brugerne og arbejde med andre agenter. Aktivitetsprotokollen standardiserer kommunikationsprotokollen mellem en hvilken som helst klient, du arbejder med, herunder Microsoft- og tredjepartsklienter, så du ikke behøver at oprette brugerdefineret logik pr. kanal, du arbejder med.

Hvad er en aktivitet?

En Activity er et struktureret JSON-objekt, der repræsenterer enhver interaktion mellem en bruger og din agent. Aktiviteter er ikke kun tekstbaserede meddelelser, de kan omfatte forskellige typer interaktion, herunder hændelser, f.eks. en bruger, der tilmelder sig eller forlader klienter, der understøtter flere brugere, indtastningsindikatorer, filoverførsler, korthandlinger og brugerdefinerede hændelser, udviklere designer sig selv.

Hver aktivitet indeholder metadata om:

Hvem har sendt den (fra)
Hvem skal modtage den (modtager)
Samtalekonteksten
Kanalen, den stammer fra
Typen af interaktion
Nyttedata

Aktivitetsskema – nøgleegenskaber

Denne specifikation definerer protokollen Activity: Activity protocol – Activity. Nogle af de nøgleegenskaber, der er defineret i protokollen Aktivitet, er:

Egenskab	Beskrivelse
`Id`	Genereres typisk af kanalen, hvis den stammer fra en kanal
`Type`	Typen styrer betydningen af en aktivitet, f.eks. meddelelsestype
`ChannelID`	`ChannelID` Refererer til den kanal, som aktiviteten stammer fra. Eksempel: `msteams`.
`From`	Afsenderen af aktiviteten (som kan være en bruger eller agent)
`Recipient`	Den tilsigtede modtager af aktiviteten
`Text`	Meddelelsens tekstindhold
`Attachment`	Omfattende indhold, f.eks. kort, billeder af filer

Få adgang til aktivitetsdata

Udviklere skal have adgang til dataene i aktiviteten for at fuldføre handlinger fra objektet TurnContext .

Du kan finde en TurnContext klasse i hver sprogversion af Microsoft 365 Agents SDK:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Notat

Kodestykkerne i denne artikel bruger C#. Syntaksen og API-strukturen for JavaScript- og Python-versionerne er ens.

TurnContext er et vigtigt objekt, der bruges i alle samtaler i Microsoft 365 Agents SDK. Den giver adgang til den indgående aktivitet, metoder til afsendelse af svar, administration af samtaletilstand og den kontekst, der er nødvendig for at håndtere en enkelt samtale. Den bruges til at bevare konteksten, sende relevante svar og interagere effektivt med dine brugere i deres klient/kanal. Hver gang din agent modtager en ny aktivitet fra en kanal, opretter Agents SDK en ny TurnContext forekomst og sender den til dine registrerede handlere/metoder. Dette kontekstobjekt findes under den enkelte vending og fjernes derefter, når turn slutter.

En tur defineres som returturen for en meddelelse, der sendes fra klienten, og som foretager rejsen til din kode, din kode håndterer disse data, og koden kan eventuelt sende et svar tilbage for at fuldføre turen. Denne rundtur kan opdeles i:

Indgående aktivitet: Brugeren sender en meddelelse eller udfører en handling, der opretter en aktivitet.
Din kode modtager aktiviteten, og agenten behandler den ved hjælp af TurnContext.
Din agent sender en eller flere aktiviteter retur.
Den aktuelle fase slutter, og TurnContext bortskaffes.

Få adgang til data fra TurnContext, f.eks.:

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

Dette kodestykke viser et eksempel på en komplet tur:

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

I klassen TurnContext omfatter ofte anvendte nøgleoplysninger:

Aktivitet: Den primære måde at hente oplysninger fra aktiviteten på
Adapter: Kanaladapteren, der oprettede aktiviteten
TurnState: Tilstanden for omstilling

Aktivitetstyper

Typen af en aktivitet er vigtig, da den definerer, hvad der kræves eller forventes i resten af aktiviteten mellem klienter, brugere og agenter.

Meddelelse

En almindelig type aktivitet er meddelelsestypenActivity, der kan omfatte tekst, vedhæftede filer og foreslåede handlinger for at nævne nogle få almindelige anvendelser for denne type.

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

SamtaleOpdatering

Typen ConversationUpdate giver Activity din agent besked, når medlemmer deltager i eller forlader en samtale. Det er ikke alle klienter, der understøtter dette. En bemærkelsesværdig klient, der gør det, er Microsoft Teams.

Følgende kodestykke hilser nye medlemmer i en samtale:

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

Begivenhed

Hændelsestypen for Activity er brugerdefinerede hændelser, der gør det muligt for kanaler eller klienter at sende strukturerede data til din agent, som ikke er foruddefineret i Activity nyttedatastrukturen.

Du skal oprette en metode/rutehandler for den specifikke Event type og derefter administrere den ønskede logik baseret på:

Name – Hændelsesnavnet eller -id'et fra klientværdien – Hændelsesnyttedata, der typisk er et JSON-objekt

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

Kald

AktiveringstypenActivity er en bestemt type aktivitet, som en klient kalder til en agent for at udføre en kommando eller handling og ikke kun en meddelelse. Eksempler på disse typer aktiviteter er almindelige i Microsoft Teams for task/fetch og task/submit. Det er ikke alle kanaler, der understøtter denne type aktiviteter.

Indtastning

En indtastningstype af Activity er en type aktivitet, der viser, at nogen indtaster i en samtale. Dette ses ofte mellem menneskelige og menneskelige samtaler i f.eks. Microsoft Teams-klienten. Indtastningsaktiviteter understøttes ikke i alle klienter, og især understøtter Microsoft 365 Copilot ikke indtastningsaktiviteter.

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

Opret og send aktiviteter

For at sende svar indeholder 'TurnContext' flere metoder til at sende svar tilbage til brugeren.

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
}

Arbejde med vedhæftede filer

Det er almindeligt, at agenter arbejder med vedhæftede filer, der er indsendt af brugere (eller endda andre agenter). Klienten sender en Message aktivitet, der indeholder en vedhæftet fil (det er ikke en bestemt type aktivitet), og din kode skal håndtere modtagelse af meddelelsen med den vedhæftede fil, læse metadataene og hente filen sikkert fra den URL-adresse, klienten har angivet. Det vil være typisk at flytte filen til dit eget lager.

Sådan modtager du en vedhæftet fil

Følgende kode viser, hvordan du modtager og vedhæftede filer

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

For at modtage dokumentet på den vedhæftede fil sender klienten typisk en godkendt GET anmodning om at hente det faktiske indhold – hver adapter har sin egen måde at hente disse data på, f.eks. Teams, OneDrive osv. Det er også vigtigt at vide, at disse URL-adresser typisk er kortvarige, og derfor skal du ikke antage, at de bliver der, og derfor er det vigtigt at flytte til dit eget lager, hvis du har brug for at henvise til dette senere.

Citater

Det er vigtigt at vide, at vedhæftet fil og citat ikke er af samme objekttype. Citater håndteres af klienter, f.eks. Microsoft Teams, på deres egne måder og bruger egenskaben Entities for Activity og kan tilføjes sammen med activity.Entities.Add og tilføje et nyt Entity objekt, der har den specifikke Citation definition, der er baseret på din klient. Det serialiseres som et JSON-objekt, som klienten derefter deserialiserer baseret på, hvordan det gengives i klienten. Grundlæggende er vedhæftede filer meddelelser, og citater kan referere til vedhæftede filer og er et andet objekt, der sendes i Entities af Activity nyttedataene.

Kanalspecifikke overvejelser

Microsoft 365 Agents SDK er bygget som en 'Hub', der gør det muligt for udviklerne at oprette agenter, der kan arbejde med en hvilken som helst klient, herunder de klienter, vi understøtter, og levere værktøjerne til udviklere, så de kan bygge deres egen kanaladapter ved hjælp af den samme struktur. Dette giver udviklere bredden, når det kommer til agenter, og gør det muligt for klienter at oprette forbindelse til denne hub, hvilket kan være en eller flere klienter som Microsoft Teams, Slack og meget mere.

Forskellige kanaler har forskellige funktioner og begrænsninger, og følgende er en oversigt over overvejelser, når du arbejder med almindelige klienter.

Du kan kontrollere den kanal, du har modtaget aktiviteten fra, ved at channelId undersøge egenskaben i Activity.

Kanaler indeholder bestemte data, der ikke er i overensstemmelse med den generiske Activity nyttedata på tværs af alle kanaler, og det kan du få adgang til fra TurnContext.Activity.ChannelData og specifikt caste den til variabler til brug i din kode.

Microsoft Teams

Understøtter avancerede adaptive kort med avancerede funktioner
Understøtter meddelelsesopdateringer og sletninger
Indeholder specifikke kanaldata for Teams-funktioner (omtaler, mødeoplysninger osv.)
Understøtter aktivering af aktiviteter for opgavemoduler

Microsoft 365 Copilot

Primært fokuseret på meddelelsesaktiviteter
Understøtter citater og referencer i svar
Kræver streamingsvar
Begrænset understøttelse af avancerede kort/adaptive kort

WebChat/DirectLine

WebChat er en HTTP-protokol, der bruges til agenter til at tale via HTTPS

Fuld support til alle aktivitetstyper
Understøtter brugerdefinerede kanaldata

Tredjepartskanaler

Disse omfatter Slack, Facebook og meget mere.

Der kan være begrænset support til visse aktivitetstyper
Kortgengivelse kan være anderledes eller ikke-understøttet
Kontrollér altid specifik kanaldokumentation

Feedback

Var denne side nyttig?

Last updated on 2025-11-19