Förstå aktivitetsprotokoll

Activity Protocol är ett standardkommunikationsprotokoll som används inom Microsoft i många Microsoft-SDK:er, tjänster och klienter. Activity Protocol används av Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams och SDK för Microsoft 365-agenter. Activity Protocol 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. Activity Protocol standardiserar kommunikationsprotokollet med alla klienter 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 varje interaktion mellan en användare och din agent. Aktiviteter är inte begränsade till textbaserade meddelanden. De kan omfatta olika typer av interaktioner, såsom händelser (t.ex. att en användare ansluter sig till eller lämnar för klienter som stödjer flera användare), skrivindikatorer, filuppladdningar, kortinteraktioner och skräddarsydda händelser som utvecklare definierar.

Varje aktivitet innehåller metadata om:

• Vem skickade den (från)
• Vem ska få den (mottagare)?
• Konversationens kontext
• Kanalen den härstammar från
• Interaktionstypen
• Nyttolastdata

Aktivitetsschema – nyckelegenskaper

Denna specifikation definierar Aktivitetsprotokoll: Aktivitetsprotokoll - Aktivitet. Några av de nyckelegenskaper som definieras i Activity Protocol är:

Åtkomst till aktivitetsdata

För att slutföra åtgärder från TurnContext-objektet behöver utvecklare komma åt data inom aktiviteten.

Du kan hitta en TurnContext-klass i varje programmeringsspråkversion av SDK för Microsoft 365-agenter.

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

TurnContext är ett viktigt objekt som används i varje konversationsomgång i SDK för Microsoft 365-agenter. Den ger tillgång till inkommande aktivitet, metoder för att skicka svar, hantering av konversationstillstånd och den kontext som behövs för att hantera en enda samtalsrunda. Använd den för att upprätthålla kontext, skicka lämpliga svar och interagera med dina användare på deras klient eller kanal på ett effektivt sätt. Varje gång din agent tar emot en ny aktivitet från en kanal skapar Agents SDK en ny TurnContext-instans och skickar den till dina registrerade hanterare eller metoder. Detta kontextobjekt existerar under en samtalstur och tas sedan bort när turen är slut.

En omgång definieras som en rundtur för ett meddelande som skickas från klienten och som gör resan till din kod. Din kod hanterar data och kan välja att skicka ett svar tillbaka för att slutföra turen. Den tur-och-retur-resan kan delas upp i följande steg:

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

2. Din kod 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.

Åtkomstdata från , TurnContextsåsom:

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

Inom TurnContext klassen används vanliga nyckeluppgifter:

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

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
• ConversationUpdate
• Händelse
• Anropa
• Typing

Meddelande

En vanlig typ av aktivitet är Meddelande-typen av Activity. Denna Activity typ kan inkludera text, bilagor 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);
});

ConversationUpdate

ConversationUpdate-typen av Activity notifierar din agent när medlemmar går med i eller lämnar en konversation. Inte alla klienter stöder denna avisering, men Microsoft Teams gör det.

Följande kodexempel välkomnar nya medlemmar till 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

Event-typen av Activity är en anpassad händelse som kanaler eller klienter använder för att skicka strukturerad data till din agent. Denna data är inte fördefinierad i Activity nyttolaststruktur.

Du behöver skapa en metod eller router för den specifika Event typen. Därefter hanterar du önskad logik baserat på:

• Namn: Händelsenamnet eller identifieraren från klienten
• Värde: Händelsedata 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 operation. 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 har inte stöd för dessa typer av aktiviteter.

Typing

En skriver typ av Activity är en klassificering av aktiviteter som anger att någon skriver i ett samtal. Denna aktivitet förekommer ofta i samtal mellan människor i Microsoft Teams-klienten, till exempel. Typing-aktiviteter stöds inte i alla klienter. Observera att Microsoft 365 Copilot inte stödjer typing-aktiviteter.

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 tillhandahåller TurnContextflera 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 bilagor som användare eller andra agenter lämnar in. Klienten skickar en Message-aktivitet som innehåller en bilaga (det är inte en särskild typ av aktivitet). Din kod ska hantera mottagandet av meddelandet med bilagan, läsa metadata och säkert hämta filen från den URL som klienten angav. Vanligtvis flyttar du filen till din egen lagringsplats.

Ta emot en bifogad fil

Följande kod visar hur man 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
        };
    }
}

Vanligtvis, för att ta emot dokumentet för bilagan, skickar klienten en autentiserad GET-begäran om att hämta det faktiska innehållet. Varje adapter har sin egen metod för att hämta 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 URL:erna förblir giltiga särskilt länge. Denna begränsning är anledningen till att 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 Citering inte är samma objekttyp. Klienter, som Microsoft Teams, hanterar citationer på sina egna sätt. De använder egenskapen Entiteter för Activity. Du kan lägga till referenser med activity.Entities.Add och lägga till ett nytt Entity objekt som har den specifika Citation definitionen baserat på din klient. Den serialiseras som ett JSON-objekt som klienten sedan deserialiserar beroende på hur den presenteras i klienten. I grunden är bilagor meddelanden, och citationer kan referera till bilagor och är ytterligare ett objekt som skickas i Entities i Activity-payloaden.

Kanalspecifika överväganden

SDK för Microsoft 365-agenter är byggt som en 'Hub' som utvecklare använder för att skapa agenter som kan arbeta med vilken klient som helst, inklusive de klienter vi stödjer. Den tillhandahåller verktyg för utvecklare att bygga sin egen kanaladapter med samma ramverk. Denna arkitektur ger utvecklare bredd när det gäller agenter och ger klienter möjlighet att ansluta till den hubben, vilket kan vara en eller flera klienter som Microsoft Teams, Slack och fler.

Olika kanaler har olika funktioner och begränsningar.

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

Kanaler innehåller specifik data som inte följer den generiska Activity nyttolasten över alla kanaler. Du kan komma åt dessa data från TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata)-egenskapen genom att konvertera dem till variabler för användning i din kod.

Följande avsnitt sammanfattar överväganden när man arbetar med vanliga kunder.

Microsoft Teams

• Stöder omfattande Adaptiva kort med avancerade funktioner.
• Stöder uppdateringar och radering av meddelanden.
• Har specifik kanaldata för Teams-funktioner, såsom omnämnanden och mötesinformation.
• Stöder anropa aktiviteter för uppgiftsmoduler.

Microsoft 365 Copilot

• Främst fokuserad på meddelandeaktiviteter.
• Stöder citat och referenser i svar.
• Kräver strömmande svar.
• Begränsat stöd för RTF-kort och adaptiva kort.

Web Chat/DirectLine

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

• Fullt stöd för alla aktivitetstyper.
• Stöder anpassad kanaldata.

Icke-Microsoft-kanaler

Dessa kanaler inkluderar Slack, Facebook och andra.

• Kan ha begränsat stöd för vissa aktivitetstyper.
• Kortrendering kan vara annorlunda eller inte stödd.
• Kontrollera alltid den specifika kanaldokumentationen.

Nästa steg

• Lär dig mer om AgentApplication