Zrozumienie Protokołu Aktywności

Protokół działania to standardowy protokół komunikacyjny używany w firmie Microsoft w wielu zestawach SDK, usługach i klientach. Protokół działania jest używany przez Microsoft 365 Copilot, Microsoft Copilot Studio i Zestaw SDK agentów usługi Microsoft 365. Protokół aktywności definiuje strukturę komponentu Activity, a także sposób, w jaki komunikaty, zdarzenia i interakcje przepływają z kanału do twojego kodu i wszędzie pomiędzy. Agenci mogą łączyć się z co najmniej jednym kanałem w celu interakcji z użytkownikami i pracy z innymi agentami. Protokół Activity Protocol standaryzuje protokół komunikacyjny z dowolnym klientem, z którym pracujesz, w tym klientów Microsoft i innych niż Microsoft, dzięki czemu nie musisz tworzyć niestandardowej logiki dla każdego kanału.

Co to jest działanie?

Obiekt Activity jest obiektem JSON ze strukturą, który reprezentuje dowolną interakcję między użytkownikiem a agentem. Działania nie są ograniczone do wiadomości tekstowych. Mogą one obejmować różne typy interakcji, takie jak 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, które deweloperzy projektują.

Każde działanie zawiera metadane dotyczące:

Kto go wysłał i skąd?
Kto powinien go otrzymać (adresat)
Kontekst konwersacji
Kanał, z którego pochodzi
Typ interakcji
Dane ładunku

Schemat działania — właściwości klucza

Ta specyfikacja definiuje protokół działania: Protokół aktywności — działanie. Niektóre z kluczowych właściwości zdefiniowanych w protokole działania to:

Właściwości	Description
`Id`	Zazwyczaj generowane przez kanał, jeśli pochodzi z kanału
`Type`	Typ kontroluje znaczenie działania, na przykład typ komunikatu
`ChannelID`	Kanał, z którego pochodzi działanie, to `ChannelID`. Na przykład: `msteams`.
`From`	Nadawca działania (który może być użytkownikiem lub agentem)
`Recipient`	Zamierzony odbiorca działania
`Text`	Zawartość tekstowa wiadomości
`Attachment`	Zawartość bogata, na przykład karty, obrazy plików

Uzyskiwanie dostępu do danych działań

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

Klasę TurnContext można znaleźć w każdej wersji językowej zestawu SDK agentów platformy Microsoft 365:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Uwaga / Notatka

Fragmenty kodu w tym artykule używają języka C#. Składnia i struktura interfejsu API dla języków JavaScript i Python są podobne.

TurnContext jest ważnym obiektem używanym w każdej turze rozmowy w SDK Microsoft 365 Agents. Zapewnia dostęp do działań przychodzących, metod wysyłania odpowiedzi, zarządzania stanem konwersacji i kontekstu potrzebnego do obsługi pojedynczego zwrotu konwersacji. Służy do obsługi kontekstu, wysyłania odpowiednich odpowiedzi i efektywnej interakcji z użytkownikami w kliencie lub kanale. Za każdym razem, gdy agent otrzymuje nowe działanie z kanału, Agents SDK tworzy nowe TurnContext wystąpienie i przekazuje je do zarejestrowanych obsług lub metod. Ten obiekt kontekstu istnieje podczas jednej tury, a następnie jest usuwany, gdy tura się kończy.

Cykl jest definiowany jako runda komunikatu wysyłanego z klienta i docierającego do twojego kodu. Kod obsługuje te dane i może opcjonalnie wysłać odpowiedź, aby ukończyć operację. Tę podróż w obie strony można podzielić na następujące kroki:

Działanie przychodzące: użytkownik wysyła komunikat lub wykonuje akcję, która tworzy działanie.
Kod odbiera działanie, a agent przetwarza go przy użyciu polecenia TurnContext.
Agent odsyła jedną lub więcej aktywności.
Zakręt kończy się i TurnContext jest usuwany.

Uzyskiwanie dostępu do danych z elementu TurnContext, na przykład:

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

Ten fragment kodu przedstawia przykład pełnego obrotu:

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 często używane kluczowe informacje obejmują:

Działanie: główny sposób uzyskiwania informacji z działania
Adapter: Adapter kanału, który utworzył aktywność
TurnState: stan tury

Typy działań

Typ działania określa, czego wymaga pozostałe działanie lub czego oczekuje między klientami, użytkownikami i agentami.

Są to:

Komunikat
AktualizacjaKonwersacji
Event
Wywołaj
Pisanie

Komunikat

Typowym działaniem jest Komunikat typu Activity. Ten Activity typ może zawierać tekst, załączniki i sugerowane akcje.

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

AktualizacjaKonwersacji

Typ ConversationUpdate powiadamia agenta Activity , gdy członkowie dołączają do konwersacji lub opuszczają konwersację. Nie wszyscy klienci obsługują to powiadomienie, ale Microsoft Teams to robi.

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

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 zdarzeniaActivity to niestandardowe zdarzenie, które kanały lub klienci używają do wysyłania danych ustrukturyzowanych do agenta. Te dane nie są z góry zdefiniowane w strukturze ładunku Activity.

Musisz utworzyć metodę lub procedurę obsługi tras dla określonego Event typu. Następnie zarządzaj żądaną logiką w oparciu o następujące elementy:

Nazwa: nazwa zdarzenia lub identyfikator klienta
Wartość: Ładunek zdarzenia, który jest zazwyczaj 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 Activity to określony typ działania, który klient wywołuje u agenta, aby wykonać polecenie lub operację. To nie tylko wiadomość. Przykłady tych typów działań są powszechne w Microsoft Teams dla task/fetch i task/submit. Nie wszystkie kanały obsługują te typy działań.

Pisanie

Typ PisanieActivity to klasyfikacja działań wskazująca, że ktoś wpisuje podczas konwersacji. To działanie jest często spotykane w rozmowach między ludźmi w kliencie Microsoft Teams, na przykład. Działania wpisywania nie są obsługiwane w każdym kliencie. Co istotne, Microsoft 365 Copilot nie obsługuje pisania.

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

Tworzenie i wysyłanie działań

Aby wysyłać odpowiedzi, TurnContext udostępnia wiele metod wysyłania odpowiedzi z powrotem 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

Agenci często pracują z załącznikami przesyłanymi przez użytkowników (a nawet innymi agentami). Klient wysyła Message działanie zawierające załącznik (nie jest to określony typ działania). Kod musi obsługiwać odbieranie komunikatu z załącznikiem, odczytywanie metadanych i bezpieczne pobieranie pliku z podanego adresu URL klienta. Zazwyczaj plik jest przenoszony do własnej pamięci.

Aby otrzymać załącznik

Poniższy kod przedstawia sposób odbierania załącznika.

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 w celu otrzymania dokumentu dla załącznika klient wysyła uwierzytelnione GET żądanie pobrania rzeczywistej zawartości. Każdy adapter ma własny sposób na uzyskanie tych danych. Na przykład usługa Teams, OneDrive itd. Ważne jest również, aby wiedzieć, że te adresy URL są zwykle krótkotrwałe, więc nie zakładaj, że adresy URL pozostają ważne 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 załącznik i cytat nie są tym samym typem obiektu. Klienci, tacy jak Microsoft Teams, obsługują cytaty na własny sposób. Używają właściwości Entities obiektu Activity. Możesz dodać cytaty za pomocą activity.Entities.Add i dodać nowy Entity obiekt, który ma konkretną Citation definicję w oparciu o potrzeby klienta. Jest serializowany jako obiekt JSON, który następnie klient deserializuje na podstawie sposobu renderowania w kliencie. Zasadniczo załączniki to komunikaty, a cytaty mogą odwoływać się do załączników i są innym obiektem wysyłanym w Entities ładunku Activity .

Zagadnienia dotyczące konkretnego kanału

Zestaw SDK agentów usługi Microsoft 365 zostało zbudowane jako "Centrum," z którego deweloperzy mogą korzystać do tworzenia agentów, którzy mogą pracować z każdym klientem, w tym z klientami, których obsługujemy. Udostępnia ona narzędzia dla deweloperów, umożliwiające tworzenie własnego adaptera kanału przy użyciu tego samego frameworka. Ta architektura zapewnia deweloperom szerokie możliwości, jeśli chodzi o wykorzystanie agentów, i umożliwia klientom rozszerzanie w celu nawiązania połączenia z tym centrum, którym może być jeden lub więcej klientów, takich jak Microsoft Teams, Slack i inne.

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

Możesz sprawdzić kanał, przez który odebrano działanie, sprawdzając właściwość channelId w obiekcie Activity.

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

W poniższych sekcjach podsumowano zagadnienia dotyczące pracy z typowymi klientami.

Microsoft Teams

Obsługuje zaawansowane funkcje Adaptive Cards.
Obsługuje aktualizacje i usuwanie komunikatów.
Zawiera szczegółowe dane kanału dotyczące funkcji Teams, takie jak wzmianki i informacje o spotkaniach.
Obsługuje działania wywoływania dla modułów zadań.

Microsoft 365 Copilot

Przede wszystkim koncentruje się na działaniach związanych z wiadomościami.
Obsługuje cytaty i odwołania w odpowiedziach.
Wymaga przesyłania odpowiedzi strumieniowo.
Ograniczona obsługa kart bogatych w treść i kart adaptacyjnych.

czat internetowy/DirectLine

czat internetowy to protokół HTTP, którego agenci mogą używać do komunikacji za pośrednictwem protokołu HTTPS.

Pełna obsługa wszystkich typów działań.
Obsługuje niestandardowe dane kanału.

Kanały inne niż Microsoft

Kanały obejmują Slack, Facebook i inne.

Może mieć ograniczoną obsługę niektórych typów działań.
Renderowanie kart może być inne lub nieobsługiwane.
Zawsze sprawdzaj dokumentację określonego kanału.

Dalsze kroki

Dowiedz się więcej o AgentApplication

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-29