Pochopení protokolu aktivit

Protokol aktivity je komunikační protokol a standardní protokol používaný microsoftem v mnoha sadách MICROSOFT SDK, službách a klientech. To zahrnuje Microsoft 365 Copilot, Microsoft Copilot Studio a sadu Microsoft 365 Agents SDK. Protokol aktivity definuje strukturu Activity a způsob, jakým zprávy, události a interakce proudí z kanálu do vašeho kódu a dále všude kolem. Agenti se můžou připojit k jednomu nebo několika kanálům, aby mohli komunikovat s uživateli a pracovat s jinými agenty. Protokol aktivity standardizuje komunikační protokol mezi libovolným klientem, se kterým pracujete, včetně klientů Microsoftu a třetích stran, takže nemusíte vytvářet vlastní logiku pro každý kanál, se kterým pracujete.

Co je aktivita?

Je Activity strukturovaný objekt JSON, který představuje jakoukoli interakci mezi uživatelem a vaším agentem. Aktivity nejsou jen textové zprávy, mohou zahrnovat různé typy interakcí, včetně událostí, jako je připojení nebo opuštění uživatele u klientů, kteří podporují více uživatelů, indikátory psaní, nahrávání souborů, akce karet a vlastní události, které si vývojáři sami navrhují.

Každá aktivita zahrnuje metadata o:

Kdo to poslal
Kdo by ho měl obdržet (příjemce)
Kontext konverzace
Kanál, ze který pochází
Typ interakce
Data datové části

Schéma aktivity – klíčové vlastnosti

Tato specifikace definuje protokol aktivity: Protokol aktivity – Aktivita. Mezi klíčové vlastnosti definované v protokolu aktivity patří:

Vlastnictví	Description
`Id`	Obvykle se generuje kanálem, pokud tento kanál byl původním zdrojem.
`Type`	Typ řídí význam aktivity, například typ zprávy.
`ChannelID`	`ChannelID` Odkazuje na kanál, ze kterého aktivita pochází. Například: `msteams`.
`From`	Odesílatel aktivity (což může být uživatel nebo agent)
`Recipient`	Zamýšlený příjemce aktivity
`Text`	Textový obsah zprávy
`Attachment`	Bohatý obsah, jako jsou karty, obrázky souborů

Přístup k datům aktivit

Vývojáři potřebují přístup k datům v rámci aktivity, aby mohli provádět akce z objektu TurnContext .

Třídu TurnContext můžete najít v každé jazykové verzi Microsoft 365 Agents SDK.

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Poznámka:

Fragmenty kódu v tomto článku používají jazyk C#. Syntaxe a struktura rozhraní API pro verze JavaScriptu a Pythonu jsou podobné.

TurnContext je důležitý objekt, který se používá při každém otočení konverzace v sadě SDK pro agenty Microsoft 365. Poskytuje přístup k příchozí aktivitě, metodám pro odesílání odpovědí, správě stavu konverzace a kontextu potřebnému ke zpracování jediného otočení konverzace. Používá se k udržování kontextu, odesílání vhodných odpovědí a efektivní interakci s uživateli v jejich klientovi nebo kanálu. Pokaždé, když agent obdrží novou aktivitu z kanálu, vytvoří sada Agents SDK novou TurnContext instanci a předá ji zaregistrovaným obslužným rutinám nebo metodám. Tento kontextový objekt existuje během jediného turnu a po skončení turnu se vyhodí.

Otočení je definován jako okružní cesta zprávy odeslané z klienta, která putuje do vašeho kódu, kde je zpracována, a kód může volitelně odeslat odpověď zpět, čímž se cyklus uzavře. Tato zpáteční cesta se dá rozdělit na:

Příchozí aktivita: Uživatel odešle zprávu nebo provede akci, která vytvoří aktivitu.
Váš kód obdrží aktivitu a agent ji zpracuje pomocí TurnContext.
Váš agent pošle jednu nebo více činností zpět.
Otočení končí a TurnContext je odstraněno.

Přistupujte k datům z TurnContext, jako například:

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

Tento fragment kódu ukazuje příklad úplného otočení:

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

Uvnitř třídy TurnContext běžně používané informace o klíči zahrnují:

Aktivita: Hlavní způsob, jak získat informace z aktivity
Adaptér: Adaptér kanálu, který aktivitu vytvořil
TurnState: Stav pro otáčení

Typy aktivit

Typ aktivity je důležitý, protože definuje, co se vyžaduje nebo očekává ve zbytku aktivity mezi klienty, uživateli a agenty.

Message

Běžným typem aktivity je typ Activity, který může obsahovat text, přílohy a navrhované akce s názvem několika běžných použití pro tento typ.

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

Aktualizace konverzace

Typ Activity upozorní vašeho agenta, když se členové připojí nebo opustí konverzaci. Ne všichni klienti to podporují, jeden významný klient, který to podporuje, je Microsoft Teams.

Následující fragment kódu pozdraví nové členy v konverzaci:

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

Events

Typ Událost u Activity jsou vlastní událostí, která umožňuje kanálům nebo klientům odesílat strukturovaná data do vašeho agenta, která nejsou předdefinována ve struktuře datové části Activity.

Pro konkrétní Event typ byste museli vytvořit obslužnou rutinu metody nebo trasy a pak spravovat požadovanou logiku na základě:

Název – název nebo identifikátor události od klienta Hodnota – datová část události, která je obvykle objektem JSON

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

Typ Activity je konkrétní typ aktivity, kterou klient volá do agenta k provedení příkazu nebo operace, a ne pouze zprávy. Příklady těchto typů aktivit jsou v Microsoft Teams pro task/fetch a task/submit. Ne všechny kanály podporují tento typ aktivit.

Psání

Typ Psaní u Activity je klasifikace aktivity, která označuje, že někdo píše v konverzaci. To se běžně vyskytuje u konverzací mezi lidmi například v klientu Microsoft Teams. Aktivity psaní nejsou podporovány v každém klientovi, a zejména Microsoft 365 Copilot nepodporuje psaní aktivit.

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

Vytváření a odesílání aktivit

Pokud chcete odesílat odpovědi, "TurnContext" poskytuje více metod pro odesílání odpovědí zpět uživateli.

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
}

Práce s přílohami

Agenti obvykle pracují s přílohami odesílanými uživateli (nebo dokonce s jinými agenty). Klient odešle Message aktivitu, která obsahuje přílohu (není to konkrétní typ aktivity) a váš kód potřebuje zpracovat příjem zprávy s přílohou, číst metadata a bezpečně načíst soubor z adresy URL, kterou poskytl klient. Typické by bylo přesunout soubor do vlastního úložiště.

Přijetí přílohy

Následující kód ukazuje, jak přijmout a připojit přílohu.

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

Pokud chcete získat dokument v příloze, klient obvykle odešle ověřený GET požadavek na načtení skutečného obsahu – každý adaptér má svůj vlastní způsob, jak tato data získat, například Teams, OneDrive atd. Je také důležité vědět, že tyto adresy URL jsou obvykle krátkodobé, a proto nepředpokládáte, že tam zůstanou, což je důvod, proč je přesun do vlastního úložiště důležitý, pokud na to budete později potřebovat odkazovat.

Citace

Je důležité vědět, že příloha a citace nejsou stejného typu objektu. Citace jsou zpracovávány klienty, jako je Microsoft Teams, vlastními způsoby a používají vlastnost Entities objektu Activity a dají se přidat s novým activity.Entities.Add objektem Entity, který má konkrétní definici Citation založenou na vašem klientovi. Serializuje se jako objekt JSON, který pak klient deserializuje na základě toho, jak se v klientovi vykresluje. Základně jsou přílohy zprávy a citace mohou odkazovat na přílohy a představují další objekt odeslaný v EntitiesActivity datové části.

Aspekty specifické pro kanály

Sada Microsoft 365 Agents SDK je vytvořená jako centrum, které vývojářům umožňuje vytvářet agenty, kteří můžou pracovat s libovolným klientem, včetně klientů, které podporujeme, a poskytují vývojářům nástroje pro sestavení vlastního adaptéru kanálu pomocí stejné architektury. To vývojářům poskytuje šířku, pokud jde o agenty, a poskytuje klientům rozšiřitelnost pro připojení k tomuto centru, což může být jeden nebo více klientů, jako je Microsoft Teams, Slack a další.

Různé kanály mají různé možnosti a omezení a následující informace jsou souhrnem aspektů při práci s běžnými klienty.

Kanál, od kterého jste obdrželi aktivitu, můžete zkontrolovat prostřednictvím vlastnosti channelId v objektu Activity.

Kanály obsahují specifická data, která nevyhovují obecné Activity datové části napříč všemi kanály, a lze k nim získat přístup z TurnContext.Activity.ChannelData a konkrétně je přetypovat na proměnné pro použití v kódu.

Microsoft Teams

Podporuje bohaté adaptivní karty s pokročilými funkcemi.
Podporuje aktualizace a odstranění zpráv.
Obsahuje konkrétní data kanálu pro funkce Teams (zmínky, informace o schůzkách atd.)
Podporuje vyvolávací aktivity pro úkolové moduly.

Microsoft 365 Copilot

Primárně zaměřené na aktivity související se zprávami
Podporuje citace a odkazy v odpovědích.
Vyžaduje streamování odpovědí.
Omezená podpora pro bohaté karty nebo adaptivní karty

WebChat/DirectLine

Webový chat je protokol HTTP používaný pro agenty pro komunikaci přes HTTPS.

Úplná podpora pro všechny typy aktivit
Podporuje data vlastních kanálů.

Kanály třetích stran

Patří mezi ně Slack, Facebook a další.

Může mít omezenou podporu pro určité typy aktivit.
Vykreslování karet může být jiné nebo nepodporované.
Vždy zkontrolujte konkrétní dokumentaci ke kanálu.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-11-19