Porozumění protokolu Activity Protocol

Activity Protocol je standardní komunikační protokol používaný napříč Microsoftem v mnoha SDK, službách a klientech Microsoft. Activity Protocol používají Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams a Sada SDK pro agenty Microsoft 365. Activity Protocol definuje strukturu Activity a způsob, jak zprávy, události a interakce proudí z kanálu do vašeho kódu a všude mezi tím. Agenti se mohou připojit k jednomu nebo více kanálům, aby komunikovali s uživateli a spolupracovali s ostatními agenty. Activity Protocol standardizuje komunikační protokol s jakýmkoli klientem, se kterým pracujete, včetně klientů Microsoft nebo třetích stran, takže nemusíte vytvářet vlastní logiku pro každý kanál.

Co je Activity?

Activity je strukturovaný objekt JSON, který reprezentuje jakoukoli interakci mezi uživatelem a vaším agentem. Aktivity nejsou omezeny jen na textové zprávy. Mohou zahrnovat různé typy interakcí, například události jako připojení nebo odhlášení uživatele u klientů, které podporují více uživatelů, indikátory psaní, nahrávání souborů, akce karet a vlastní události navržené vývojáři.

Každá aktivita obsahuje metadata s následujícími informacemi:

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

Schéma aktivit – klíčové vlastnosti

Tato specifikace definuje Activity Protocol: Activity Protocol - Activity. Mezi klíčové vlastnosti definované v Activity Protocol patří například:

Vlastnost	Popis
`Id`	Obvykle generováno kanálem v případě, že aktivita pochází z kanálu.
`Type`	Typ určuje význam aktivity, například typ zprávy
`ChannelID`	`ChannelID` odkazuje na kanál, odkud aktivita pochází. Například: `msteams`.
`From`	Odesílatel aktivity (kterým může být uživatel nebo agent)
`Recipient`	Zamýšlený příjemce aktivity
`Text`	Textový obsah zprávy
`Attachment`	Bohatý obsah jako karty nebo obrázky souborů

Přístup k datům aktivity

Aby mohli vývojáři dokončit akce z objektu TurnContext, musí získat přístup k datům uvnitř aktivity.

V každé jazykové verzi Sady SDK pro agenty Microsoft 365 najdete třídu TurnContext:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Poznámka:

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

TurnContext je důležitý objekt, který se používá při každém kroku 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 pro zpracování jednoho cyklu konverzace. Použijte ho k udržení kontextu, zasílání vhodných odpovědí a efektivní interakci s uživateli v klientovi nebo kanálu. Pokaždé, když váš agent přijme novou aktivitu z kanálu, Sada SDK pro agenty vytvoří novou instanci TurnContext a předá ji registrovaným obslužným funkcím nebo metodám. Tento kontextový objekt existuje během jednoho kroku a po jeho skončení je odstraněn.

Tah je definován jako cesta zprávy odeslané z klienta, která se vrací zpět do vašeho kódu. Váš kód tato data zpracovává a může volitelně poslat odpověď zpět k dokončení kroku konverzace. Tuto zpáteční cestu lze rozdělit do následujících kroků:

Příchozí aktivita: Uživatel odešle zprávu nebo provede akci, která aktivitu vytvoří.
Váš kód přijme tuto 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řístup k datům z TurnContext, například:

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

Tento fragment kódu ukazuje příklad úplného kroku konverzace:

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 jsou běžně používané klíčové informace:

Aktivita: Hlavní způsob získání informací z aktivity
Adaptér: Kanálový adaptér, který vytvořil aktivitu
TurnState: Stav pro konverzační krok

Typy aktivit

Typ aktivity určuje, co zbytek aktivity vyžaduje nebo očekává mezi klienty, uživateli a agenty.

Mezi ně patří:

Zpráva
ConversationUpdate
Událost
Vyvolat
Typing

Zpráva

Běžným typem aktivity je typ Message pro Activity. Tento typ Activity může obsahovat text, přílohy i navrhované akce.

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

Typ ConversationUpdate pro Activity informuje vašeho agenta, když se členové připojí ke konverzaci nebo ji opustí. Ne všichni klienti toto oznámení podporují, ale Microsoft Teams jej podporuje.

Následující fragment kódu vítá 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.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Události

Typ UdálostiActivity je vlastní událost, kterou kanály nebo klienti používají k odesílání strukturovaných dat vašemu agentovi. Tato data nejsou předdefinovaná ve struktuře datové části Activity.

Potřebujete vytvořit metodu nebo obslužnou rutinu trasy pro konkrétní typ Event. Poté spravujte požadovanou logiku na následujícím základě:

Name: Název události nebo identifikátor z klienta
Value: Datový obsah 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)
});

Vyvolat

Typ VyvoláníActivity je specifický typ aktivity, kterou klient volá u agenta za účelem provedení příkazu nebo operace. Nejde pouze o zprávu. Příklady těchto typů aktivit jsou běžné v Microsoft Teams pro task/fetch a task/submit. Ne všechny kanály podporují tyto typy aktivit.

Typing

Typ Psaní u Activity je klasifikace aktivity, která označuje, že někdo píše v konverzaci. Tato aktivita se běžně projevuje mezi lidmi při lidských konverzacích v aplikaci Microsoft Teams. Aktivity Typing nejsou podporovány ve všech klientech. Zvláště Microsoft 365 Copilot nepodporuje aktivity psaní.

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

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 často pracují s přílohami, které odesílají uživatelé (nebo dokonce jiní agenti). Klient odešle aktivitu Message, která obsahuje přílohu (nejedná se o specifický typ aktivity). Váš kód musí zpracovat příchozí zprávu s přílohou, přečíst metadata a bezpečně stáhnout soubor z adresy URL poskytnuté klientem. Obvykle soubor přesunete do svého vlastního úložiště.

Přijetí přílohy

Následující kód ukazuje, jak přijmout 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
        };
    }
}

Obvykle klient za účelem získání dokumentu přílohy odešle ověřený požadavek GET na získání skutečného obsahu. Každý adaptér má svůj vlastní způsob, jak tato data získat. Například Teams, OneDrive a podobně. Je také důležité vědět, že adresy URL jsou obvykle krátkodobé, a proto nepředpokládejte, že zůstanou dlouho funkční. Tato omezení jsou důvodem, proč je důležité přesunout obsah do vlastního úložiště, pokud se k němu budete potřebovat později odkazovat.

Citace

Je důležité vědět, že Příloha a Citace nejsou stejným typem objektu. Klienti, jako Microsoft Teams, zpracovávají citace svým vlastním způsobem. Používají vlastnost Entities pro Activity. Citace můžete přidat pomocí activity.Entities.Add a přidat nový objekt Entity, který má specifickou definici Citation podle klienta. Serializuje se jako objekt JSON, který pak klient deserializuje na základě toho, jak se v klientovi vykresluje. V zásadě jsou přílohy zprávy a citace mohou odkazovat na přílohy a jsou dalším objektem zasílaným v Entities z datové části Activity.

Specifika jednotlivých kanálů

Sada SDK pro agenty Microsoft 365 je navržen jako „Hub“, který vývojáři používají k vytváření agentů, kteří mohou pracovat s libovolným klientem, včetně těch, které podporujeme. Poskytuje nástroje, aby vývojáři mohli vytvořit vlastní kanálový adaptér pomocí stejného frameworku. Tato architektura poskytuje vývojářům větší flexibilitu při práci s agenty a umožňuje klientům připojit se k tomuto hubu, který může zahrnovat jednoho nebo více klientů, jako jsou Microsoft Teams, Slack a další.

Různé kanály mají různé možnosti a omezení.

Můžete ověřit, ze kterého kanálu byla aktivita přijata, kontrolou vlastnosti channelId v Activity.

Kanály zahrnují konkrétní data, která nevyhovují obecné datové části Activity napříč všemi kanály. K těmto datům můžete přistupovat z vlastnosti TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) tím, že je přetypujete na proměnné pro použití ve vašem kódu.

Následující sekce shrnují aspekty práce s běžnými klienty.

Microsoft Teams

Podporuje bohaté adaptivní karty s pokročilými funkcemi.
Podporuje aktualizace a odstraňování zpráv.
Podporuje specifická data kanálu pro funkce Teams, jako jsou zmínky a informace o schůzkách.
Podporuje aktivity vyvolání pro moduly úloh.

Microsoft 365 Copilot

Primárně se zaměřuje na aktivity zpráv.
Podporuje citace a odkazy v odpovědích.
Vyžaduje vysílání datového proudu odpovědí.
Omezená podpora pro bohaté a adaptivní karty.

Webový chat / DirectLine

Webový chat je protokol HTTP, který mohou agenti použít ke komunikaci přes HTTPS.

Plná podpora všech typů aktivit.
Podporuje vlastní data kanálu.

Kanály třetích stran

Mezi tyto kanály patří Slack, Facebook a další.

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

Další kroky

Zjistěte více o AgentApplication

Váš názor

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

Last updated on 2026-07-30