Om aktivitetsprotokol

Activity Protocol er en standardkommunikationsprotokol der bruges på tværs af Microsoft i mange Microsoft SDK'er, tjenester og klienter. Aktivitetsprotokollen bruges af Microsoft 365 Copilot, Microsoft Copilot Studio og SDK til Microsoft 365-agenter. Aktivitetsprotokol definerer strukturen af en Activity , og hvordan meddelelser, hændelser og interaktioner flyder fra en 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. Activity Protocol standardiserer kommunikationsprotokollen med en hvilken som helst klient, du arbejder med, herunder Microsoft og ikke-Microsoft klienter, så du ikke behøver at oprette brugerdefineret logik for hver kanal.

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 begrænset til tekstbaserede meddelelser. De kan omfatte forskellige typer interaktion, f.eks. hændelser som f.eks. en bruger, der tilmelder sig eller forlader klienter, der understøtter flere brugere, indtastningsindikatorer, filuploads, korthandlinger og brugerdefinerede hændelser, som udviklerne designer.

Hver aktivitet indeholder metadata om:

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

Aktivitetsskema – nøgleegenskaber

Denne specifikation definerer Aktivitetsprotokol: Aktivitetsprotokol - Aktivitet. Nogle af de nøgleegenskaber, der er defineret i Aktivitetsprotokol, er:

Få adgang til aktivitetsdata

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

Du kan finde en TurnContext klasse i hver sprogversion af SDK til Microsoft 365-agenter:

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

TurnContext er et vigtigt objekt, der bruges i hver samtale i SDK til Microsoft 365-agenter. 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. Brug den til at bevare konteksten, sende relevante svar og interagere effektivt med dine brugere i deres klient eller 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 eller 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 kan eventuelt sende et svar tilbage for at fuldføre turn. Denne rundtur kan opdeles i følgende trin:

1. Indgående aktivitet: Brugeren sender en meddelelse eller udfører en handling, der opretter en aktivitet.

2. Din kode modtager aktiviteten, og agenten behandler den ved hjælp af TurnContext.

3. Din agent sender en eller flere aktiviteter retur.

4. 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 definerer, hvad resten af aktiviteten kræver eller forventer mellem klienter, brugere og agenter.

Disse omfatter:

• Melding
• SamtaleOpdatering
• Hændelse
• Aktivér
• Indtastning

Melding

En almindelig type aktivitet er meddelelsestypen .Activity Denne Activity type kan omfatte tekst, vedhæftede filer og foreslåede 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);
});

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

Hændelser

Hændelsestypen for Activity er en brugerdefineret hændelse, som kanaler eller klienter bruger til at sende strukturerede data til din agent. Disse data er ikke foruddefineret i Activity nyttedatastrukturen.

Du skal oprette en metode eller en rutehandler for den specifikke Event type. Derefter skal du administrere den ønskede logik baseret på:

• Navn: Hændelsesnavnet eller -id'et fra klienten
• Værdi: 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)
});

Aktivér

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

Indtastning

En indtastningstype af Activity er en type aktivitet, der viser, at nogen indtaster i en samtale. Denne aktivitet ses ofte mellem menneskelige til menneskelige samtaler i f.eks. Microsoft Teams klient. Indtastning af aktiviteter understøttes ikke i alle klienter. Især understøtter Microsoft 365 Copilot 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);

Opret og send aktiviteter

Hvis du vil sende svar, indeholder den TurnContextflere 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

Agenter arbejder ofte med vedhæftede filer, som brugerne (eller endda andre agenter) indsender. Klienten sender en Message aktivitet, der indeholder en vedhæftet fil (det er ikke en bestemt type aktivitet). 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. Normalt flytter du filen til dit eget lager.

Sådan modtager du en vedhæftet fil

Følgende kode viser, hvordan du modtager en vedhæftet fil.

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 for 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å. For eksempel Teams, OneDrive osv. Det er også vigtigt at vide, at disse URL-adresser typisk er kortlivede, så antag ikke, at URL-adresserne forbliver gyldige i lang tid. Denne begrænsning er grunden til, at det er vigtigt at flytte til dit eget lager, hvis du har brug for at referere til indholdet senere.

Citater

Det er vigtigt at vide, at vedhæftet fil og citat ikke er af samme objekttype. Klienter, f.eks. Microsoft Teams, håndterer citater på deres egne måder. De bruger egenskaben Entities for Activity. Du kan tilføje citater med activity.Entities.Add og tilføje et nyt Entity objekt, der har den specifikke Citation definition 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

SDK til Microsoft 365-agenter er bygget som en 'Hub', som udviklere bruger til at oprette agenter, der kan arbejde med any klient, herunder de klienter, vi understøtter. Den indeholder værktøjer til udviklere, så de kan bygge deres egen kanaladapter ved hjælp af den samme struktur. Denne arkitektur 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, f.eks. Microsoft Teams, Slack og meget mere.

Forskellige kanaler har forskellige funktioner og begrænsninger.

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

Kanalerne indeholder specifikke data, som ikke stemmer overens med den generiske Activity nyttelast på tværs af alle kanaler. Du kan få adgang til disse data fra egenskaben TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) ved at caste dem til variabler, der skal bruges i din kode.

I følgende afsnit opsummeres overvejelser, når du arbejder med almindelige klienter.

Microsoft Teams

• Understøtter omfattende Adaptive kort med avancerede funktioner.
• Understøtter meddelelsesopdateringer og sletninger.
• Indeholder specifikke kanaldata for Teams-funktioner, f.eks. omtaler og mødeoplysninger.
• 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 omfattende kort og adaptive kort.

Webchat/DirectLine

Webchat er en HTTP-protokol, som agenter kan bruge til at kommunikere via HTTPS.

• Fuld support til alle aktivitetstyper.
• Understøtter brugerdefinerede kanaldata.

Kanaler, der ikke er Microsoft

Disse kanaler omfatter Slack, Facebook og meget mere.

• Der kan være begrænset understøttelse af visse aktivitetstyper.
• Kortgengivelsen kan være anderledes eller understøttes ikke.
• Kontrollér altid specifik kanaldokumentation.

Næste trin

• Få mere at vide om AgentApplication