Förstå aktivitetsprotokoll

Activity Protocol är ett standard kommunikationsprotokoll som används över Microsoft i många Microsoft SDK:er, tjänster och klienter. Activity Protocol används av Microsoft 365 Copilot, Microsoft Copilot Studio och SDK för Microsoft 365-agenter. Aktivitetsprotokoll definierar strukturen för en Activity och hur meddelanden, händelser och interaktioner flödar från en kanal till din kod och överallt däremellan. Agenter kan ansluta till en eller flera kanaler för att interagera med användare och arbeta med andra agenter. Aktivitetsprotokollet standardiserar kommunikationsprotokollet med alla klienter som du arbetar med, inklusive Microsoft och icke-Microsoft klienter, så att du inte behöver skapa anpassad logik för varje kanal.

Vad är en aktivitet?

En Activity är ett strukturerat JSON-objekt som representerar alla interaktioner mellan en användare och din agent. Aktiviteter är inte begränsade till textbaserade meddelanden. De kan innehålla olika typer av interaktion, till exempel händelser som en användare som ansluter till eller lämnar för klienter som stöder flera användare, skriva indikatorer, filuppladdningar, kortåtgärder och anpassade händelser som utvecklare utformar.

Varje aktivitet innehåller metadata om:

• Vem skickade den (från)
• Vem som ska ta emot den (mottagare)
• Konversationskontexten
• Kanalen som den kom från
• Typen av interaktion
• Nyttolastdata

Aktivitetsschema – nyckelegenskaper

Den här specifikationen definierar Aktivitetsprotokoll: Aktivitetsprotokoll – Aktivitet. Några av de viktigaste egenskaperna som definierats i Aktivitetsprotokoll är:

Åtkomst till aktivitetsdata

För att slutföra åtgärder från TurnContext objektet måste utvecklare komma åt data i aktiviteten.

Du hittar en TurnContext klass i varje språkversion av SDK för Microsoft 365-agenter:

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

TurnContext är ett viktigt objekt som används i varje konversationssväng i SDK för Microsoft 365-agenter. Den ger åtkomst till den inkommande aktiviteten, metoder för att skicka svar, hantering av konversationstillstånd och den kontext som behövs för att hantera en enda konversationsvändning. Använd den för att upprätthålla kontexten, skicka lämpliga svar och interagera med användarna i klienten eller kanalen på ett effektivt sätt. Varje gång agenten får en ny aktivitet från en kanal skapar Agent-SDK:n en ny TurnContext instans och skickar den till dina registrerade hanterare eller metoder. Det här kontextobjektet finns under den enda svängen och tas sedan bort när svängen slutar.

En tur definieras som en rundtur för ett meddelande som skickas från klienten och som gör resan till din kod. Koden hanterar dessa data och kan eventuellt skicka ett svar tillbaka för att slutföra svängen. Den tur och retur-resan kan delas upp i följande steg:

1. Inkommande aktivitet: Användaren skickar ett meddelande eller utför en åtgärd som skapar en aktivitet.

2. Koden tar emot aktiviteten och agenten bearbetar den med hjälp av TurnContext.

3. Din agent skickar tillbaka en eller flera aktiviteter.

4. Vändningen avslutas och TurnContext tas bort.

Få åtkomst till data från TurnContext, till exempel:

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

Det här kodfragmentet visar ett exempel på en fullständig vändning:

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

Inuti TurnContext-klassen innehålls vanligt använda nyckelinformationer:

• Aktivitet: Det huvudsakliga sättet att få information från aktiviteten
• Adapter: Kanalkortet som skapade aktiviteten
• TurnState: Tillståndet för svängen

Aktivitetstyper

Typen av aktivitet definierar vad resten av aktiviteten kräver eller förväntar sig mellan klienter, användare och agenter.

Dessa omfattar:

• Meddelande
• UppdateraKonversation
• Händelse
• Anropa
• Skrivning

Meddelande

En vanlig typ av aktivitet är meddelandetypenActivity. Den här Activity typen kan innehålla text, bifogade filer och föreslagna åtgärder.

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

UppdateraKonversation

Typen ConversationUpdate meddelar Activity din agent när medlemmar ansluter eller lämnar en konversation. Alla klienter stöder inte det här meddelandet, men Microsoft Teams gör det.

Följande kodfragment hälsar nya medlemmar i en konversation:

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ändelsetypenActivity är en anpassad händelse som kanaler eller klienter använder för att skicka strukturerade data till din agent. Dessa data är inte fördefinierade i Activity nyttolaststrukturen.

Du måste skapa en metod eller routningshanterare för den specifika Event typen. Hantera sedan den önskade logiken baserat på:

• Namn: Händelsenamnet eller identifieraren från klienten
• Värde: Händelsenyttolast som vanligtvis är ett 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)
});

Anropa

En Invoke-typ av Activity är en specifik typ av aktivitet som en klient anropar till en agent för att utföra ett kommando eller en åtgärd. Det är inte bara ett meddelande. Exempel på dessa typer av aktiviteter är vanliga i Microsoft Teams för task/fetch och task/submit. Alla kanaler stöder inte dessa typer av aktiviteter.

Skrivning

En skriver typ av Activity är en klassificering av aktiviteter som anger att någon skriver i ett samtal. Den här aktiviteten ses ofta mellan mänskliga till mänskliga konversationer i Microsoft Teams klient, till exempel. Skrivaktiviteter stöds inte i varje klient. I synnerhet stöder Microsoft 365 Copilot inte skrivaktiviteter.

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

Skapa och skicka aktiviteter

För att skicka svar TurnContext innehåller flera metoder för att skicka tillbaka svar till användaren.

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
}

Arbeta med bilagor

Agenter arbetar ofta med bifogade filer som användare (eller till och med andra agenter) skickar. Klienten skickar en Message aktivitet som innehåller en bifogad fil (det är inte en specifik typ av aktivitet). Koden måste hantera mottagandet av meddelandet med den bifogade filen, läsa metadata och på ett säkert sätt hämta filen från den URL som klienten angav. Vanligtvis flyttar du filen till din egen lagring.

Ta emot en bifogad fil

Följande kod visar hur du tar emot en bifogad 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
        };
    }
}

För att ta emot dokumentet för den bifogade filen skickar klienten vanligtvis en autentiserad GET begäran för att hämta det faktiska innehållet. Varje adapter har sitt eget sätt att hämta den datan. Till exempel Teams, OneDrive och så vidare. Det är också viktigt att veta att dessa URL:er vanligtvis är kortlivade och därför inte förutsätter att URL:erna är giltiga länge. Den här begränsningen är därför det är viktigt att flytta till din egen lagring om du behöver referera till innehållet senare.

Hänvisningar

Det är viktigt att veta att Bilaga och Källhänvisning inte är samma objekttyp. Klienter, som Microsoft Teams, hanterar citat på sina egna sätt. De använder egenskapen Entiteter för Activity. Du kan lägga till citat med activity.Entities.Add och lägga till ett nytt Entity objekt som har den specifika Citation definitionen baserat på klienten. Den serialiseras som ett JSON-objekt som klienten sedan deserialiserar baserat på hur den återges i klienten. I grund och botten är bifogade filer meddelanden och Citat kan referera till bifogade filer och är ett annat objekt som skickas i EntitiesActivity nyttolasten.

Kanalspecifika överväganden

SDK för Microsoft 365-agenter skapas som en "hubb" som utvecklare använder för att skapa agenter som kan arbeta med any-klienten, inklusive de klienter som vi stöder. Den innehåller verktyg som utvecklare kan använda för att bygga en egen kanalanpassare med hjälp av samma ramverk. Den här arkitekturen ger utvecklare bredd när det gäller agenter och ger utökningsbarhet till klienter för att ansluta till hubben, vilket kan vara en eller flera klienter som Microsoft Teams, Slack med mera.

Olika kanaler har olika funktioner och begränsningar.

Du kan kontrollera kanalen från vilken du tog emot aktiviteten genom att inspektera channelId-egenskapen i Activity.

Kanaler innehåller specifika data som inte överensstämmer med den allmänna Activity nyttolasten i alla kanaler. Du kan komma åt dessa data från TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) egenskapen genom att casta dem till variabler för användning i koden.

Följande avsnitt sammanfattar överväganden när du arbetar med vanliga klienter.

Microsoft Teams

• Stöder omfattande Adaptive Cards med avancerade funktioner.
• Stöder meddelandeuppdateringar och borttagningar.
• Har specifika kanaldata för Teams-funktioner, till exempel omnämnanden och mötesinformation.
• Stöder anropa aktiviteter för aktivitetsmoduler.

Microsoft 365 Copilot

• Fokuserar främst på meddelandeaktiviteter.
• Stöder citat och referenser i svar.
• Kräver direktuppspelningssvar.
• Begränsat stöd för omfattande kort och adaptiva kort.

Web Chat/DirectLine

Web Chat är ett HTTP-protokoll som agenter kan använda för att kommunicera via HTTPS.

• Fullständigt stöd för alla aktivitetstyper.
• Stöder anpassade kanaldata.

Icke-Microsoft-kanaler

Dessa kanaler inkluderar Slack, Facebook med mera.

• Kan ha begränsat stöd för vissa aktivitetstyper.
• Kortrendering kan vara annorlunda eller stöds inte.
• Kontrollera alltid specifik kanaldokumentation.

Nästa steg

• Läs mer om AgentApplication