Forstå aktivitetsprotokoll

Aktivitetsprotokoll er en standard kommunikasjonsprotokoll som brukes på tvers av Microsoft i mange Microsoft SDK-er, tjenester og klienter. Activity Protocol brukes av Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams og SDK for Microsoft 365-agenter. Aktivitetsprotokoll definerer strukturen til en Activity og hvordan meldinger, hendelser og samhandlinger flyter fra en kanal til koden din og alt annet imellom. Agenter kan koble seg til en eller flere kanaler for å samhandle med brukere og samarbeide med andre agenter. Activity Protocol standardiserer kommunikasjonsprotokollen med alle klienter du jobber med, inkludert Microsoft- og ikke-Microsoft-klienter, slik at du ikke trenger å lage egendefinert logikk for hver kanal.

Hva er en aktivitet?

En Activity er et strukturert JSON-objekt som representerer enhver samhandling mellom en bruker og agenten din. Aktivitetene er ikke begrenset til tekstbaserte meldinger. De kan inkludere ulike typer samhandling, for eksempel hendelser som når en bruker slutter seg til eller forlater (for klienter som støtter flere brukere), skriveindikatorer, filopplastinger, korthandlinger og egendefinerte hendelser som utviklere oppretter.

Hver aktivitet inkluderer metadata om:

Hvem som sendte den (fra)
Hvem som skal motta den (mottaker)
Samtalekonteksten
Kanalen den stammer fra
Typen samhandling
Nyttelastdata

Aktivitetsskjema – nøkkelegenskaper

Denne spesifikasjonen definerer Aktivitetsprotokoll: Aktivitetsprotokoll – Aktivitet. Noen av de viktigste egenskapene definert i aktivitetsprotokollen er:

Egenskap	Description
`Id`	Vanligvis generert av kanalen hvis den stammer fra en kanal
`Type`	Typen bestemmer betydningen av en aktivitet, f.eks. meldingstype
`ChannelID`	`ChannelID` angir kanalen som aktiviteten kommer fra. Eksempel: `msteams`.
`From`	Avsenderen av aktiviteten (som kan være en bruker eller agent)
`Recipient`	Den tiltenkte mottakeren av aktiviteten
`Text`	Tekstinnholdet i meldingen
`Attachment`	Rikt innhold som kort, bilder av filer

Få tilgang til aktivitetsdata

For å utføre handlinger fra objektet TurnContext må utviklere få tilgang til dataene i aktiviteten.

Du kan finne en TurnContext-klasse i hver programmeringsspråkversjon av SDK for Microsoft 365-agenter:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Notat

Kodesnuttene i denne artikkelen bruker C#. Syntaksen og API-strukturen for JavaScript- og Python-versjonene er tilsvarende.

TurnContext er et viktig objekt som brukes i hver samtalerunde i SDK for Microsoft 365-agenter. Den gir tilgang til den innkommende aktiviteten, metoder for å sende svar, håndtering av samtaletilstand og konteksten som trengs for å håndtere en enkelt samtalerunde. Bruk den til å opprettholde kontekst, sende passende svar og samhandle effektivt med brukerne dine i klienten eller kanalen deres. Hver gang agenten din mottar en ny aktivitet fra en kanal, oppretter SDK for agenter en ny TurnContext-forekomst og sender den videre til dine registrerte håndterere eller metoder. Dette kontekstobjektet eksisterer under én samtalerunde og fjernes når samtalerunden er avsluttet.

En omgang defineres som rundturen av en melding sendt fra klienten og reisen til koden din. Koden din håndterer de dataene og kan eventuelt sende et svar tilbake for å fullføre runden. Den rundturen kan deles inn i følgende trinn:

Innkommende aktivitet: Brukeren sender en melding eller utfører en handling som skaper en aktivitet.
Koden din mottar aktiviteten, og agenten behandler den ved hjelp av TurnContext.
Agenten din sender én eller flere aktiviteter tilbake.
Turen avsluttes, og den TurnContext blir kastet.

Få tilgang til data fra TurnContext, slik som:

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

Denne kodesnutten viser et eksempel på en fullstendig samtalerunde:

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

Innenfor TurnContext-klassen er vanlig brukt nøkkelinformasjon:

Aktivitet: Hovedmetoden for å hente informasjon fra aktiviteten
Adapter: Kanaladapteren som opprettet aktiviteten
TurnState: Tilstanden for omgangen

Aktivitetstyper

Aktivitetstypen bestemmer hvilke krav og forventninger som gjelder for kommunikasjon mellom klienter, brukere og agenter.

Disse omfatter:

Melding
ConversationUpdate
Hendelse
Aktiver
Skriver

Melding

En vanlig type aktivitet er Melding-typen av Activity. Denne Activity-typen kan inneholde tekst, vedlegg og foreslåtte handlinger.

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

ConversationUpdate-typen av Activity varsler agenten din når medlemmer blir med eller forlater en samtale. Ikke alle klienter støtter denne varslingen, men Microsoft Teams støtter den.

Følgende kodesnutt hilser nye medlemmer velkommen 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.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Hendelser

Hendelse-typen av Activity er en egendefinert hendelse som kanaler eller klienter benytter for å sende strukturert data til agenten din. Denne dataen er ikke forhåndsdefinert i Activity-nyttelaststrukturen.

Du må lage en metode eller rutehandler for den spesifikke Event-typen. Deretter håndterer du ønsket logikk basert på:

Navn: Hendelsens navn eller identifikator fra klienten
Verdi: Hendelsens nyttelast, typisk 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)
});

Aktiver

En Invoke-type av Activity er en spesifikk type aktivitet som en klient kaller til en agent for å utføre en kommando eller operasjon. Det er ikke bare en melding. Eksempler på disse typene aktiviteter er vanlige i Microsoft Teams for task/fetch og task/submit. Ikke alle kanaler støtter disse typene aktiviteter.

Skriver

En Skriver-type av Activity er en klassifisering av aktivitet som indikerer at noen skriver i en samtale. Denne aktiviteten sees for eksempel ofte mellom samtaler mellom mennesker i Microsoft Teams-klienten. Skriveaktiviteter støttes ikke i alle klienter. Det er verdt å merke seg at Microsoft 365 Copilot ikke støtter skriveaktiviteter.

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

Opprett og send aktiviteter

For å sende svar tilbyr TurnContextflere metoder for å sende svar til brukeren.

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
}

Arbeid med vedlegg

Agenter arbeider ofte med vedlegg som brukere (eller til og med andre agenter) laster opp. Klienten sender en Message-aktivitet som inkluderer et vedlegg (det er ikke en spesifikk type aktivitet). Koden din må håndtere mottak av meldingen med vedlegget, lese metadataene og på en sikker måte hente filen fra nettadressen som klienten har oppgitt. Vanligvis flytter du filen til ditt eget lagringsområde.

Motta et vedlegg

Følgende kode viser hvordan du mottar et vedlegg.

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

Vanligvis sender klienten en autentisert GET-forespørsel for å hente det faktiske innholdet i vedlegget. Hver adapter har sin egen måte å hente de dataene på. Eksempel: Teams, OneDrive og så videre. Det er også viktig å vite at disse nettadressene vanligvis har kort levetid, så du bør ikke anta at nettadressene forblir gyldige lenge. Denne begrensningen er grunnen til at det er viktig å flytte innholdet til en egen lagringsløsning hvis du må henvise til det senere.

Henvisninger

Det er viktig å vite at Vedlegg og Sitat ikke er samme objekttype. Klienter, som Microsoft Teams, håndterer sitater på sine egne måter. De bruker Enheter-egenskapen til Activity. Du kan legge til sitater med activity.Entities.Add og legge til et nytt Entity-objekt som har den spesifikke Citation-definisjonen basert på klienten din. Det blir serialisert som et JSON-objekt som klienten deretter deserialiserer basert på hvordan det gjengir i klienten. Grunnleggende sett er vedlegg meldinger, og henvisninger kan henviser til vedlegg og er et annet objekt som sendes inn Entities i Activity-nyttelasten.

Kanalspesifikke hensyn

SDK for Microsoft 365-agenter er bygd som et senter som lar utviklere lage agenter som kan fungere med enhver klient, inkludert de klientene vi støtter. Den gir verktøy for utviklere til å bygge sin egen kanaladapter ved å bruke samme rammeverk. Denne arkitekturen gir utviklere bredde når det gjelder agenter og gir utvidbarhet for klienter til å koble til senteret, som kan være en eller flere kunder som Microsoft Teams, Slack og flere.

Ulike kanaler har ulike muligheter og begrensninger.

Du kan sjekke hvilken kanal du mottok aktiviteten fra ved å inspisere channelId-egenskapen i Activity.

Kanaler inkluderer spesifikke data som ikke samsvarer med den generiske Activity-nyttelasten på tvers av alle kanaler. Du kan hente ut disse dataene fra TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata)-egenskapen ved å typekaste dem til variabler for bruk i koden din.

Følgende deler oppsummerer vurderinger når du jobber med vanlige kunder.

Microsoft Teams

Støtter rike dynamiske kort med avanserte funksjoner.
Støtter oppdatering og sletting av meldinger.
Har spesifikke kanaldata for Teams-funksjoner, som omtaler og møteinformasjon.
Støtter aktiveringsaktiviteter for oppgavemoduler.

Microsoft 365 Copilot

Hovedsakelig fokusert på meldingsaktiviteter.
Støtter henvisninger og referanser i svar.
Krever strømming av svar.
Begrenset støtte for innholdsrike kort og dynamiske kort.

Web Chat/DirectLine

Web Chat er en HTTP-protokoll som agenter kan bruke for å kommunisere over HTTPS.

Full støtte for alle aktivitetstyper.
Støtter egendefinerte kanaldata.

Ikke-Microsoft-kanaler

Disse kanalene inkluderer Slack, Facebook og andre.

Kan ha begrenset støtte for visse aktivitetstyper.
Kortgjengivelse kan være annerledes eller ikke støttet.
Sjekk alltid dokumentasjonen for spesifikke kanaler.

Neste trinn

Finn ut mer om AgentApplication

Tilbakemeldinger

Var denne siden nyttig?

Last updated on 2026-07-29