Forstå aktivitetsprotokollen

Aktivitetsprotokollen er kommunikasjonsprotokollen og standardprotokollen som brukes på tvers av Microsoft i mange Microsoft SDK-er, tjenester og klienter. Dette inkluderer Microsoft 365 Copilot, Microsoft Copilot Studio og Microsoft 365 Agents SDK. Aktivitetsprotokollen definerer formen på en Activity og hvordan meldinger, hendelser og samhandlinger flyter fra kanal, til koden din og overalt ellers i mellom. Agenter kan koble til én eller flere kanaler for å samhandle med brukere og arbeide med andre agenter. Aktivitetsprotokollen standardiserer kommunikasjonsprotokollen mellom alle klienter du arbeider med, inkludert Microsoft og tredjepartsklienter, slik at du ikke trenger å opprette egendefinert logikk per kanal du arbeider med.

Hva er en aktivitet?

Et Activity er et strukturert JSON-objekt som representerer samhandling mellom en bruker og agenten din. Aktiviteter er ikke bare tekstbaserte meldinger, de kan inkludere ulike typer samhandling, inkludert hendelser som en bruker som blir med i eller forlater klienter som støtter flere brukere, skriveindikatorer, filopplastinger, korthandlinger og utviklere av egendefinerte hendelser utformer seg selv.

Hver aktivitet inkluderer metadata om:

Hvem som sendte den (fra)
Hvem som skal motta den (mottaker)
Samtalekonteksten
Kanalen den stammer fra
Samhandlingstypen
Nyttelastdataene

Aktivitetsskjema – nøkkelegenskaper

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

Egenskap	Beskrivelse
`Id`	Vanligvis generert av kanalen hvis den kommer fra en kanal
`Type`	Typen styrer betydningen av en aktivitet, for eksempel meldingstype
`ChannelID`	Referansene `ChannelID` til kanalen som aktiviteten stammer 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, for eksempel kort, bilder av filer

Access-aktivitetsdata

Utviklere må få tilgang til dataene i aktiviteten for å fullføre handlinger fra TurnContext objektet.

Du finner en TurnContext klasse i hver språkversjon av Microsoft 365 Agents SDK:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Note

Kodesnuttene i denne artikkelen bruker C#. Syntaks- og API-strukturen for JavaScript- og Python-versjonene ligner.

Er TurnContext et viktig objekt som brukes i hver samtale, i Microsoft 365 Agents SDK. Den gir tilgang til innkommende aktivitet, metoder for å sende svar, administrasjon av samtaletilstand og konteksten som kreves for å håndtere én enkelt samtale. Den brukes til å opprettholde kontekst, sende riktige svar og samhandle med brukerne i klienten/kanalen effektivt. Hver gang agenten mottar en ny aktivitet fra en kanal, oppretter Agents SDK en ny TurnContext forekomst og sender den til registrerte behandlere/metoder. Dette kontekstobjektet finnes i løpet av enkelt sving og deretter avhendes når svingen slutter.

En sving defineres som rundtur av en melding som sendes fra klienten og gjør reisen til koden din, koden håndterer dataene, og koden kan eventuelt sende et svar tilbake for å fullføre svingen. Den rundturen kan deles opp i:

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

Få tilgang til data fra TurnContext, for eksempel:

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

Denne kodesnutten viser et eksempel på en fullstendig vending:

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

TurnContext I klassen omfatter ofte brukt nøkkelinformasjon:

Aktivitet: Den viktigste måten å få informasjon fra aktiviteten på
Adapter: Kanaladapteren som opprettet aktiviteten
TurnState: Tilstanden for omgangen

Aktivitetstyper

Typen aktivitet er viktig da den definerer hva som kreves eller forventes i resten av aktiviteten mellom klienter, brukere og agenter.

Melding

En vanlig type aktivitet er meldingstypenActivity, som kan omfatte tekst, vedlegg og foreslåtte handlinger for å gi navn til noen vanlige bruksområder for denne typen.

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

SamtaleOppdatering

ConversationUpdate-typenActivity varsler agenten din når medlemmer blir med i eller forlater en samtale. Ikke alle klienter støtter dette, en bemerkelsesverdig klient som gjør det, er Microsoft Teams.

Følgende kodesnutt 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);
            }
        }
    }
})

Hendelser

HendelsestypenActivity er egendefinerte hendelser som gjør det mulig for kanaler eller klienter å sende strukturerte data til agenten Activity din, som ikke er forhåndsdefinert i nyttelaststrukturen.

Du må opprette en metode-/rutebehandling for den bestemte Event typen og deretter administrere den ønskede logikken basert på følgende:

Navn – hendelsesnavnet eller identifikatoren fra klientverdien – hendelsesnyttelast som vanligvis 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)
}

Aktiver

En aktiveringstypeActivity er en bestemt type aktivitet som en klient kaller inn til en agent for å utføre en kommando eller operasjon, og 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 denne typen aktiviteter.

Skrive

En skrivetypeActivity er en klassifisering av aktivitet for å angi at noen skriver i en samtale. Dette er ofte sett mellom menneskelige og menneskelige samtaler i Microsoft Teams-klienten for eksempel. Skriveaktiviteter støttes ikke i alle klienter, og microsoft 365 Copilot støtter ikke skriveaktiviteter.

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

Opprette og sende aktiviteter

TurnContext inneholder flere metoder for å sende svar tilbake til brukeren for å sende svar.

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
}

Arbeide med vedlegg

Det er vanlig at agenter arbeider med vedlegg som er sendt inn av brukere (eller andre agenter). Klienten sender en Message aktivitet som inkluderer et vedlegg (det er ikke en bestemt type aktivitet), og koden må håndtere mottak av meldingen med vedlegget, lese metadataene og hente filen på en sikker måte fra nettadressen som klienten oppgav. Det ville være vanlig å flytte filen til din egen lagringsplass.

Slik mottar du et vedlegg

Følgende kode viser hvordan du mottar og 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
        }
    }
}

Hvis du vanligvis vil motta dokumentet på vedlegget, sender klienten en godkjent GET forespørsel om å hente det faktiske innholdet – hver adapter har sin egen måte å hente disse dataene på, for eksempel Teams, OneDrive og så videre. Det er også viktig å vite at disse nettadressene vanligvis er kortvarige, og derfor ikke anta at de blir der, og derfor er det viktig å flytte til din egen lagringsplass hvis du trenger å referere til dette senere.

Sitater

Det er viktig å vite at Vedlegg og Sitat ikke er den samme objekttypen. Sitater håndteres av klienter, for eksempel Microsoft Teams, på sine egne måter, og bruker egenskapenActivity Enheter for og kan legges til med activity.Entities.Add og legge til et nytt Entity objekt som har den bestemte Citation definisjonen basert på klienten din. Det ville bli serialisert som et JSON-objekt som klienten deretter deserialiserer basert på hvordan det gjengis i klienten. Vedlegg er i bunn og grunn meldinger, og sitater kan referere til vedlegg og er et annet objekt som sendes inn av Entities nyttelasten Activity .

Kanalspesifikke hensyn

Microsoft 365 Agents SDK er bygget som en Hub som gjør det mulig for utviklere å opprette agenter som kan arbeide med en hvilken som helst klient, inkludert klientene vi støtter og gir utviklerne verktøy til å bygge sin egen kanaladapter ved hjelp av samme rammeverk. Dette gir utviklere bredde når det gjelder agenter, og gir kundene mulighet til å koble til denne huben, som kan være én eller flere kunder som Microsoft Teams, Slack og mer.

Ulike kanaler har ulike funksjoner og begrensninger, og følgende er et sammendrag av hensyn når du arbeider med vanlige klienter.

Du kan kontrollere kanalen du har mottatt aktiviteten fra, ved å channelId undersøke egenskapen i Activity.

Kanaler inkluderer bestemte data som ikke samsvarer med den generiske Activity nyttelasten på tvers av alle kanaler, og dette kan nås fra TurnContext.Activity.ChannelData og spesielt kaste den til variabler for bruk i koden.

Microsoft Teams

Støtter rike adaptive kort med avanserte funksjoner
Støtter meldingsoppdateringer og slettinger
Har spesifikke kanaldata for Teams-funksjoner (omtaler, møteinformasjon og så videre)
Støtter aktivering av aktiviteter for oppgavemoduler

Microsoft 365 Copilot

Primært fokusert på meldingsaktiviteter
Støtter sitater og referanser i svar
Krever svar på strømming
Begrenset støtte for rike kort/adaptive kort

WebChat/DirectLine

WebChat er en HTTP-protokoll som brukes for agenter til å snakke over HTTPS

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

Tredjepartskanaler

Disse inkluderer Slack, Facebook og mer.

Kan ha begrenset støtte for bestemte aktivitetstyper
Kortgjengivelse kan være forskjellig eller støttes ikke
Kontroller alltid spesifikk kanaldokumentasjon

Tilbakemeldinger

Var denne siden nyttig?

Last updated on 2025-10-21