Zrozumienie protokołu aktywności

Protokół Aktywności to standardowy protokół komunikacyjny używany w całym Microsoft w wielu SDK, usługach i klientach Microsoftu. Protokół aktywności jest używany przez Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams oraz Zestaw SDK agentów usługi Microsoft 365. Protokół aktywności definiuje kształt Activity, a także sposób, w jaki komunikaty, zdarzenia i interakcje przepływają z kanału do kodu i wszędzie pomiędzy nimi. Agenci mogą łączyć się z jednym lub wieloma kanałami, aby wchodzić w interakcje z użytkownikami oraz współpracować z innymi agentami. Protokół działania standaryzuje protokół komunikacji z każdym klientem, z którym pracujesz, w tym z klientami Microsoft i spoza Microsoftu, dzięki czemu nie musisz tworzyć własnej logiki dla każdego kanału.

Co to jest działanie?

An Activity to ustrukturyzowany obiekt JSON, który reprezentuje każdą interakcję pomiędzy użytkownikiem a agentem. Aktywności nie ograniczają się do wiadomości tekstowych. Mogą one obejmować różne typy interakcji, np. zdarzenia, takie jak dołączanie użytkownika lub opuszczanie klientów obsługujących wielu użytkowników, wpisywanie wskaźników, przekazywanie plików, akcje kart i zdarzenia niestandardowe projektowane przez deweloperów.

Każda aktywność zawiera metadane dotyczące:

Kto to wysłał (od)
Kto powinien ją otrzymać (odbiorca)
Bieżący kontekst rozmowy
Kanał, z którego pochodziła
Typ interakcji
Dane ładunku

Schemat aktywności – kluczowe właściwości

Niniejsza specyfikacja definiuje Protokół działania: Protokół działania - Activity. Oto niektóre z kluczowych właściwości zdefiniowanych w Protokół działania:

Właściwość	Podpis
`Id`	Zazwyczaj generowane przez kanał, jeśli pochodzi z kanału
`Type`	Typ kontroluje znaczenie aktywności, na przykład typ wiadomości
`ChannelID`	`ChannelID` wskazuje na kanał, z którego pochodzi ta aktywność. Na przykład: `msteams`.
`From`	Nadawca aktywności (którym może być użytkownik lub agent)
`Recipient`	Docelowy odbiorca tej działalności
`Text`	Zawartość tekstowa wiadomości
`Attachment`	Bogate treści, takie jak karty, obrazy plików

Dostęp do danych aktywności

Aby wykonać działania z obiektu TurnContext , deweloperzy muszą uzyskać dostęp do danych w ramach aktywności.

Możesz znaleźć klasę TurnContext w każdej wersji językowej Zestaw SDK agentów usługi Microsoft 365:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Notatka

Fragmenty kodu przedstawione w tym artykule zostały napisane w języku C#. Składnia i struktura API w wersjach JavaScript i Python są podobne.

TurnContext jest ważnym obiektem używanym w każdej turze rozmowy w Zestaw SDK agentów usługi Microsoft 365. Zapewnia dostęp do przychodzącej aktywności, metod wysyłania odpowiedzi, zarządzania stanem rozmów oraz kontekstu potrzebnego do obsługi jednej tury rozmowy. Używaj go do utrzymania kontekstu, wysyłania odpowiednich odpowiedzi oraz efektywnej interakcji z użytkownikami w ich kliencie lub kanale. Za każdym razem, gdy agent otrzymuje nowe działanie z kanału, zestaw SDK agentów tworzy nowe TurnContext wystąpienie i przekazuje je do zarejestrowanych procedur obsługi lub metod. Ten obiekt kontekstowy istnieje podczas pojedynczej tury i jest zwalniany po jej zakończeniu.

Tura jest definiowany jako runda komunikatu wysyłanego z klienta i docierającego do Twojego kodu. Twój kod obsługuje te dane i może opcjonalnie odesłać odpowiedź, by dokończyć turę. Ten pełny cykl można podzielić na następujące kroki:

Aktywność przychodząca: Użytkownik wysyła wiadomość lub wykonuje akcję, która tworzy aktywność.
Twój kod odbiera aktywność, a agent przetwarza ją za pomocą TurnContext.
Agent odsyła jedną lub więcej działań.
Tura kończy się i TurnContext jest usuwana.

Dostęp do danych z TurnContext, takich jak:

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

Ten fragment kodu pokazuje przykład pełnej tury:

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

W klasie TurnContext, najczęściej wykorzystywane kluczowe informacje obejmują:

Aktywność: Główny sposób pozyskiwania informacji z aktywności
Adapter: Adapter kanału, który stworzył aktywność
TurnState: stan tury

Typy działań

Typ aktywności określa, czego wymaga lub oczekuje pozostała część aktywności między klientami, użytkownikami i agentami.

Są to:

Wiadomość
ConversationUpdate
Wydarzenie
Wywołaj
Wpisywanie

Wiadomość

Powszechnym typem aktywności jest typ WiadomośćActivity. Ten Activity typ może obejmować tekst, załączniki oraz sugerowane działania.

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 typActivity powiadamia agenta, gdy członkowie dołączają lub opuszczają rozmowę. Nie wszyscy klienci obsługują to powiadomienie, ale Microsoft Teams tak.

Poniższy fragment kodu wita nowych członków w rozmowie:

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

Zdarzenia

Typ zdarzenia o nazwie Activity to niestandardowe zdarzenie, którego kanały lub klienci używają do wysyłania danych ustrukturyzowanych do agenta. Te dane nie są predefiniowane w strukturze Activity ładunku.

Musisz stworzyć metodę lub handle trasy dla konkretnego Event typu. Następnie zarządzaj pożądaną logiką na podstawie:

Nazwa: nazwa zdarzenia lub identyfikator od klienta
Wartość: Dane zdarzenia, które zazwyczaj są obiektem 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)
});

Wywołaj

Typ działania przywołajActivity rodzaj aktywności, podczas której klient zwraca się do agenta w celu wykonania polecenia lub operacji. To nie tylko wiadomość. Przykłady takich aktywności są powszechne w Microsoft Teams podczas task/fetch i task/submit. Nie wszystkie kanały obsługują tego typu aktywności.

Wpisywanie

Typ Pisanie to Activity klasyfikacja działań wskazująca, że ktoś wpisuje podczas konwersacji. Ta aktywność jest często spotykana w rozmowach między użytkownikami w kliencie Microsoft Teams, na przykład. Aktywności pisania nie są obsługiwane przez każdego klienta. Co istotne, Microsoft 365 Copilot nie obsługuje aktywności typu pisanie.

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

Tworzenie rekordów i działań

Aby wysłać odpowiedzi TurnContext zapewnia wiele metod odsyłania wiadomości do użytkownika.

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
}

Praca z załącznikami

Agentom często zdarza się pracować z załącznikami przesyłanymi przez użytkowników (lub nawet innych agentów). Klient wysyła działanie Message zawierające załącznik (nie jest to określony typ działania). Twój kod musi obsłużyć odbiór wiadomości z załącznikiem, odczytać metadane i bezpiecznie pobrać plik z adresu URL podanego przez klienta. Zazwyczaj przenosisz plik do własnej przestrzeni dyskowej.

Odbieranie załącznika

Poniższy kod pokazuje, jak otrzymać załącznik.

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

Zazwyczaj, aby otrzymać dokument do załącznika, klient wysyła GET uwierzytelnione żądanie pobrania rzeczywistej treści. Każdy adapter ma swój sposób na uzyskanie tych danych. Na przykład Teams, OneDrive i tak dalej. Warto też wiedzieć, że te adresy URL są zazwyczaj tymczasowe, więc nie zakładaj, że pozostaną aktywne przez długi czas. To ograniczenie polega na tym, że przejście do własnego magazynu jest ważne, jeśli chcesz później odwołać się do zawartości.

Cytaty

Ważne jest, aby wiedzieć, że Attachment oraz Citation to różne typy obiektów. Klienci, tacy jak Microsoft Teams, obsługują cytowania na swój sposób. Wykorzystują własność Encji .Activity Możesz dodawać cytowania za pomocą activity.Entities.Add oraz dodać nowy obiekt Entity z definicją Citation zależną od klienta. Obiekt ten jest serializowany jako obiekt JSON, który następnie klient deserializuje, aby wyświetlić go zgodnie ze swoją metodą renderowania. W istocie załączniki to wiadomości, a cytowania mogą odnosić się do załączników i są kolejnym obiektem wysyłanym Entities z Activity ładunku.

Uwagi specyficzne dla kanałów

Zestaw SDK agentów usługi Microsoft 365 został stworzony jako "Hub", którego deweloperzy wykorzystują do tworzenia agentów współpracujących z każdym klientem, w tym z klientami, których wspieramy. Zapewnia narzędzia umożliwiające deweloperom budowanie własnego adaptera kanału z wykorzystaniem tej samej struktury. Ta architektura daje deweloperom szerokie możliwości, jeśli chodzi o agentów, oraz zapewnia rozbudowę dla klientów, aby łączyć się z tym centrum, które może obsługiwać jednego lub wielu klientów, takich jak Microsoft Teams, Slack i innych.

Różne kanały mają różne możliwości i ograniczenia.

Możesz sprawdzić kanał, z którego odebrano działanie, przez sprawdzenie właściwości channelId w obiekcie Activity.

Kanały zawierają określone dane, które nie są zgodne z ogólnym ładunkiem Activity we wszystkich kanałach. Możesz uzyskać dostęp do tych danych z właściwości TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata), rzutując je do zmiennych do użycia w swoim kodzie.

Poniższe sekcje podsumowują kwestie związane z pracą z typowymi klientami.

Microsoft Teams

Obsługuje rozbudowane karty adaptacyjne z funkcjami zaawansowanymi.
Obsługuje aktualizacje i usuwanie wiadomości.
Zawiera określone dane kanału dla funkcji Teams, takie jak wzmianki i informacje o spotkaniu.
Obsługuje działania wywoływania dla modułów zadań.

Microsoft 365 Copilot

Głównie skupiam się na działaniach informacyjnych.
Wspiera cytowania i odniesienia w odpowiedziach.
Wymaga strumieniowania odpowiedzi.
Ograniczona obsługa kart bogatych i kart adaptacyjnych.

czat internetowy/DirectLine

Czat internetowy to protokół HTTP, którego agenci mogą używać do komunikacji przez HTTPS.

Pełna obsługa wszystkich typów aktywności.
Obsługuje własne dane kanału.

Kanały inne niż firmy Microsoft

Do tych kanałów należą Slack, Facebook i inne.

Mogą mieć ograniczone wsparcie dla niektórych typów aktywności.
Renderowanie kart może odbywać się inaczej lub być nieobsługiwane.
Zawsze sprawdzaj dokumentację poszczególnych kanałów.

Następne kroki

Dowiedz się więcej AgentApplication

Opinia

Czy ta strona była pomocna?

Last updated on 2026-07-30