Porozumění protokolu aktivit

Protokol aktivity je standardní komunikační protokol používaný napříč Microsoft v mnoha sadách SDK, službách a klientech Microsoft. Protokol aktivit používá Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams a Sada SDK pro agenty Microsoft 365. Protokol aktivit definuje strukturu Activity a způsob toku zpráv, událostí a interakcí z kanálu do kódu a všude jinde. 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 se všemi klienty, se kterými pracujete, včetně Microsoft a klientů, kteří nejsou Microsoft, takže pro každý kanál nemusíte vytvářet vlastní logiku.

Co je aktivita?

Je Activity strukturovaný objekt JSON, který představuje jakoukoli interakci mezi uživatelem a vaším agentem. Aktivity se neomezují jenom na textové zprávy. Můžou zahrnovat různé typy interakce, jako jsou události, jako je připojení uživatele nebo opuštění pro klienty, kteří podporují více uživatelů, psaní indikátorů, nahrávání souborů, akce karet a vlastní události, které vývojáři 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 aktivit patří:

Property	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

K dokončení akcí z objektu TurnContext potřebují vývojáři přístup k datům v rámci aktivity.

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

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Note

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ým objektem, který se používá v každém jednotlivém kroku konverzace v rámci Sada 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žívejte ho 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 registrovaným obslužným rutinám nebo metodám. Tento kontextový objekt existuje během jedné iterace a pak se odstraní, jakmile tato iterace skončí.

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

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.
Kolo 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 definuje, co zbytek aktivity vyžaduje nebo očekává mezi klienty, uživateli a agenty.

Tady jsou některé z nich:

Message
Aktualizace konverzace
Událost
Vyvolat
Psání

Message

Běžným typem aktivity je typ zprávyActivity. Tento Activity typ může obsahovat text, přílohy a 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);
});

Aktualizace konverzace

Typ Activity upozorní vašeho agenta, když se členové připojí nebo opustí konverzaci. Toto oznámení nepodporují všichni klienti, ale Microsoft Teams ano.

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

Events

Typ událostiActivity, jako je tato, představuje uživatelskou 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 Activity struktuře datové části.

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

Název: Název nebo identifikátor události z 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)
});

Vyvolat

Typ Activity je konkrétní typ aktivity, kterou klient volá do agenta k provedení příkazu nebo operace. Není to jen zpráva. Příklady těchto typů aktivit jsou v Microsoft Teams pro task/fetch a task/submit. Tyto typy aktivit nepodporují všechny kanály.

Psání

Typ 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 psaní nejsou podporovány v každém klientu. 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

K odesílání odpovědí TurnContext poskytuje několik 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é uživatelé (nebo dokonce i jiní agenti) odesílali. Klient odešle Message aktivitu, která obsahuje přílohu (nejedná se o konkrétní typ aktivity). Váš kód musí zpracovat příjem zprávy s přílohou, číst metadata a bezpečně načíst soubor z adresy URL, kterou poskytl klient. Soubor obvykle přesunete do vlastního úložiště.

Přijmout přílohu

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

Klient obvykle odešle ověřený GET požadavek pro načtení skutečného obsahu dokumentu pro přílohu. 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 adresy URL zůstanou platné dlouho. Toto omezení je důvod, proč je přesun do vlastního úložiště důležitý, pokud budete později potřebovat odkazovat na obsah.

Citace

Je důležité vědět, že příloha a citace nejsou stejného typu objektu. Klienti, jako je Microsoft Teams, zpracovávají citace svými vlastními způsoby. Používají vlastnost Entities objektu Activity. Můžete přidat citace pomocí activity.Entities.Add a přidat nový Entity objekt, který má konkrétní Citation definici podle potřeb vašeho klienta. Serializuje se jako objekt JSON, který pak klient deserializuje na základě toho, jak se vykresluje v klientovi. Přílohy jsou zprávy, citace mohou odkazovat na přílohy a jsou dalším objektem odeslaným v EntitiesActivity datové části.

Aspekty specifické pro kanály

Sada SDK pro agenty Microsoft 365 je sestavená jako centrum, které vývojáři používají k vytváření agentů, kteří můžou pracovat s klienty any včetně klientů, které podporujeme. Poskytuje vývojářům nástroje pro sestavení vlastního adaptéru kanálu pomocí stejné architektury. Tato architektura poskytuje vývojářům šířku, pokud jde o agenty, a poskytuje rozšiřitelnost klientům pro připojení k tomuto centru, což může být jeden nebo více klientů, jako jsou Microsoft Teams, Slack a další.

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

Kanál, od kterého jste obdrželi aktivitu, můžete zjistit prozkoumáním vlastnosti channelId v objektu Activity.

Kanály zahrnují konkrétní data, která nevyhovují obecnému úseku dat Activity napříč všemi kanály. K tomuto datu TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) můžete přistupovat z vlastnosti tak, že je přetypujete do proměnných pro použití v kódu.

Následující části shrnují důležité informace při práci s běžnými klienty.

Microsoft Teams

Podporuje komplexní Adaptivní karty s pokročilými funkcemi.
Podporuje aktualizace a odstranění zpráv.
Obsahuje konkrétní 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 činnosti týkající se zpráv.
Podporuje citace a odkazy v odpovědích.
Vyžaduje streamované odpovědi.
Omezená podpora pro bohaté karty a adaptivní karty.

Webový chat/DirectLine

Webový chat je protokol HTTP, který můžou agenti používat ke komunikaci přes PROTOKOL HTTPS.

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

Kanály, které nejsou Microsoft

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

Můžou 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.

Další kroky

Další informace o AgentApplication

Váš názor

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

Last updated on 2026-05-13