Forstå aktivitetsprotokoll

Activity Protocol er en standard kommunikasjonsprotokoll som brukes på tvers av Microsoft i mange Microsoft SDK-er, tjenester og klienter. Aktivitetsprotokoll brukes av Microsoft 365 Copilot, Microsoft Copilot Studio og SDK for Microsoft 365-agenter. Activity Protocol definerer strukturen for en Activity og hvordan meldinger, hendelser og samhandlinger flyter fra en kanal til koden og overalt ellers i mellom. Agenter kan koble til én eller flere kanaler for å samhandle med brukere og arbeide med andre agenter. Activity Protocol standardiserer kommunikasjonsprotokollen med en klient du arbeider med, inkludert Microsoft og ikke-Microsoft klienter, slik at du ikke trenger å opprette egendefinert logikk for hver kanal.

Hva er en aktivitet?

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

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 Activity Protocol: Activity Protocol - Activity. Noen av de viktigste egenskapene som er definert i Aktivitetsprotokoll, er:

Få tilgang til aktivitetsdata

Hvis du vil fullføre handlinger fra TurnContext objektet, må utviklere få tilgang til dataene i aktiviteten.

Du finner en TurnContext klasse i hver språkversjon av SDK for Microsoft 365-agenter:

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

TurnContext er et viktig objekt som brukes i hver samtale, i SDK for Microsoft 365-agenter. Den gir tilgang til innkommende aktivitet, metoder for å sende svar, administrasjon av samtaletilstand og konteksten som kreves for å håndtere én enkelt samtale. Bruk den til å opprettholde kontekst, sende riktige svar og samhandle med brukerne i klienten eller 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 eller metoder. Dette kontekstobjektet finnes i løpet av én sving, og fjernes deretter når svingen slutter.

En runde defineres som en rundtur av en melding som sendes fra klienten og reiser til koden din. Koden håndterer disse dataene og kan eventuelt sende et svar tilbake for å fullføre svingen. Denne rundturen kan deles opp i følgende trinn:

1. Innkommende aktivitet: Brukeren sender en melding eller utfører en handling som oppretter en aktivitet.

2. Koden mottar aktiviteten, og agenten behandler den ved hjelp av TurnContext.

3. Agenten din sender én eller flere aktiviteter tilbake.

4. 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 definerer hva resten av aktiviteten krever eller forventer mellom klienter, brukere og agenter.

Disse omfatter:

• Melding
• SamtaleOppdatering
• Hendelse
• Aktiver
• Skrive

Melding

En vanlig type aktivitet er meldingstypenActivityfor . 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);
});

SamtaleOppdatering

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

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

Hendelser

HendelsestypenActivity er en egendefinert hendelse som kanaler eller klienter bruker til å sende strukturerte data til agenten din. Disse dataene er ikke forhåndsdefinert i Activity nyttelaststrukturen.

Du må opprette en metode eller rutebehandling for den bestemte Event typen. Deretter kan du administrere den ønskede logikken basert på:

• Navn: Hendelsesnavnet eller identifikatoren fra klienten
• Verdi: Nyttelast for hendelser 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. 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 denne typen aktiviteter.

Skrive

En skrivetypeActivity er en klassifisering av aktivitet for å angi at noen skriver i en samtale. Denne aktiviteten er ofte sett mellom menneskelige og menneskelige samtaler i Microsoft Teams klient, for eksempel. Skriveaktiviteter støttes ikke i alle klienter. 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

Hvis du vil sende svar, gir du TurnContextflere metoder for å sende svar tilbake 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 andre agenter) sender inn. Klienten sender en Message aktivitet som inneholder et vedlegg (det er ikke en bestemt type aktivitet). Koden må håndtere mottak av meldingen med vedlegget, lese metadataene og hente filen på en sikker måte fra nettadressen som klienten oppgav. Vanligvis flytter du filen til din egen lagringsplass.

Slik mottar du 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
        };
    }
}

Hvis du vanligvis vil motta dokumentet for 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 nettadressene forblir gyldige for lenge. Denne begrensningen er grunnen til at flytting til din egen lagringsplass er viktig hvis du må referere til innholdet senere.

Henvisninger

Det er viktig å vite at Vedlegg og Sitat ikke er den samme objekttypen. Klienter, som Microsoft Teams, håndterer sitater på sine egne måter. De bruker enhetsegenskapen av Activity. Du kan legge til sitater med activity.Entities.Add og legge til et nytt Entity objekt som har den bestemte Citation definisjonen basert på klienten. Det blir 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

SDK for Microsoft 365-agenter er bygget som en Hub som utviklere bruker til å opprette agenter som kan arbeide med anyklienten, inkludert klientene vi støtter. Det gir utviklere verktøy for å bygge sin egen kanaladapter ved hjelp av samme rammeverk. Denne arkitekturen gir utviklere bredde når det gjelder agenter, og gir kundene mulighet til å koble til denne huben, som kan være én eller flere klienter som Microsoft Teams, Slack og mer.

Ulike kanaler har ulike funksjoner og begrensninger.

Du kan kontrollere kanalen du mottok 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. Du kan få tilgang til disse dataene fra egenskapen ved å sende dem TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) til variabler for bruk i koden.

Avsnittene nedenfor oppsummerer hensyn når du arbeider med vanlige klienter.

Microsoft Teams

• Støtter rik Dynamiske kort med avanserte funksjoner.
• Støtter meldingsoppdateringer og slettinger.
• Har spesifikke kanaldata for Teams-funksjoner, for eksempel omtaler og møteinformasjon.
• 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 og adaptive kort.

Web Chat/DirectLine

Web Chat er en HTTP-protokoll som agenter kan bruke til å kommunisere via HTTPS.

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

Ikke-Microsoft kanaler

Disse kanalene 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.

Neste trinn

• Finn ut mer om AgentApplication