Förstå aktivitetsprotokollet

Aktivitetsprotokollet är kommunikationsprotokollet och standardprotokollet som används i Microsoft i många Microsoft SDK:er, tjänster och klienter. Detta inkluderar Microsoft 365 Copilot, Microsoft Copilot Studio och Microsoft 365 Agents SDK. Aktivitetsprotokollet definierar formen på en Activity och hur meddelanden, händelser och interaktioner flödar från 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 mellan alla klienter som du arbetar med, inklusive Microsoft- och tredjepartsklienter, så du behöver inte skapa anpassad logik per kanal som du arbetar med.

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 bara textbaserade meddelanden, de kan innehålla olika typer av interaktion, inklusive händelser som att en användare ansluter till eller lämnar för klienter som stöder flera användare, skriver indikatorer, filuppladdningar, kortåtgärder och anpassade händelser som utvecklare utformar själva.

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 aktivitetsprotokollet: Aktivitetsprotokoll – Aktivitet. Några av de viktigaste egenskaperna som definieras i aktivitetsprotokollet är:

Fastighet	Description
`Id`	Genereras vanligtvis av kanalen om den kommer från en kanal
`Type`	Typen styr innebörden av en aktivitet, till exempel meddelandetyp
`ChannelID`	Refererar `ChannelID` till kanalen som aktiviteten kommer från. Till exempel: `msteams`.
`From`	Avsändaren av aktiviteten (som kan vara en användare eller agent)
`Recipient`	Den avsedda mottagaren av aktiviteten
`Text`	Textinnehållet i meddelandet
`Attachment`	Omfattande innehåll som kort, bilder av filer

Åtkomst till aktivitetsdata

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

Du hittar en TurnContext klass i varje språkversion av Microsoft 365 Agents SDK:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Anmärkning

Kodfragmenten i den här artikeln använder C#. Syntaxen och API-strukturen för JavaScript- och Python-versionerna är liknande.

TurnContext Är ett viktigt objekt som används i varje konversationssväng i Microsoft 365 Agents SDK. 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. Den används för att upprätthålla kontexten, skicka lämpliga svar och interagera med användarna i klienten/kanalen på ett effektivt sätt. Varje gång din agent tar emot en ny aktivitet från en kanal skapar Agent-SDK:n en ny TurnContext instans och skickar den till dina registrerade hanterare/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 omgång där ett meddelande skickas från klienten till din kod, koden hanterar denna data och kan eventuellt skicka ett svar tillbaka för att slutföra omgången. Den tur och retur-resan kan delas upp i:

Inkommande aktivitet: Användaren skickar ett meddelande eller utför en åtgärd som skapar en aktivitet.
Koden tar emot aktiviteten och agenten bearbetar den med hjälp av TurnContext.
Din agent skickar tillbaka en eller flera aktiviteter.
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 är viktig eftersom den definierar vad som krävs eller förväntas i resten av aktiviteten mellan klienter, användare och agenter.

Message

En vanlig typ av aktivitet är meddelandetypenActivity, som kan innehålla text, bifogade filer och föreslagna åtgärder för att nämna några vanliga användningsområden för den här 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);
});

ConversationUpdate

Typen ConversationUpdate meddelar Activity din agent när medlemmar ansluter eller lämnar en konversation. Det är inte alla klienter som stöder detta, en viktig klient som gör det är Microsoft Teams.

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

Evenemang

HändelsetypenActivity är anpassade händelser som gör att kanaler eller klienter kan skicka strukturerade data till din agent, vilket inte är fördefinierat i Activity nyttolaststrukturen.

Du skulle behöva skapa en metod/routningshanterare för den specifika Event typen och sedan hantera önskad logik baserat på:

Namn – Händelsenamnet eller identifieraren från klientvärdet – 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)
}

Invoke

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, och 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 den här typen av aktiviteter.

Skrivning

En skriver typ av Activity är en klassificering av aktiviteter som anger att någon skriver i ett samtal. Detta ses ofta mellan mänskliga till mänskliga konversationer i Microsoft Teams-klienten, till exempel. Skrivaktiviteter stöds inte i alla klienter, och särskilt Microsoft 365 Copilot stöder 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 innehåller "TurnContext" 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 bifogade filer

Det är vanligt att agenter arbetar med bifogade filer som har skickats av användare (eller till och med andra agenter). Klienten skickar en Message aktivitet som innehåller en bifogad fil (det är inte en specifik typ av aktivitet) och 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. Det skulle vara typiskt att sedan flytta filen till din egen lagring.

Ta emot en bifogad fil

Följande kod visar hur du tar emot en bilaga.

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 i den bifogade filen skickar klienten vanligtvis en autentiserad GET begäran om att hämta det faktiska innehållet – varje adapter har sitt eget sätt att hämta den data, till exempel Teams, OneDrive och så vidare. Det är också viktigt att veta att dessa URL:er vanligtvis är kortlivade, så anta inte att de kommer att stanna där, varför det är viktigt att flytta till din egen lagring om du behöver referera till detta senare.

Citat

Det är viktigt att veta att Bilaga och Källhänvisning inte är samma objekttyp. Citat hanteras av klienter, såsom Microsoft Teams, enligt deras egna metoder och använder egenskapen Entiteter av Activity som kan läggas till med activity.Entities.Add och genom att lägga till ett nytt Entity-objekt som har en specifik Citation-definition baserat på din klient. Det skulle serialiseras som ett JSON-objekt som klienten sedan deserialiserar baserat på hur det å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

Microsoft 365 Agents SDK skapas som en "hubb" som möjliggör för utvecklarna att skapa agenter som kan arbeta med alla klienter, inklusive de klienter vi stöder, och tillhandahålls verktyg för utvecklare att bygga sina egna kanaladaptrar med samma ramverk. Detta ger utvecklare bredd när det gäller agenter och ger utökningsbarhet för klienter att ansluta till den hubben, vilket kan vara en eller flera klienter som Microsoft Teams, Slack och mer.

Olika kanaler har olika funktioner och begränsningar, och följande är en sammanfattning av överväganden när du arbetar med vanliga klienter.

Du kan kontrollera kanalen som du har tagit emot aktiviteten från genom att channelId granska egenskapen i Activity.

Kanaler inkluderar specifika data som inte överensstämmer med den generiska Activity nyttolasten som används i alla kanaler, och detta kan nås från TurnContext.Activity.ChannelData och specifikt konverteras till variabler för användning i din kod.

Microsoft Teams

Stöder omfattande adaptiva kort med avancerade funktioner
Stöder meddelandeuppdateringar och borttagningar
Har specifika kanaldata för Teams-funktioner (omnämnanden, mötesinformation och så vidare)
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 rich cards/adaptiva kort

WebChat/DirectLine

Webbchatt är ett HTTP-protokoll som används för agenter att kommunicera via HTTPS

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

Kanaler från tredje part

Dessa 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

Feedback

Var den här sidan hjälpsam?

Last updated on 2025-10-21