Opis protokołu działania

Protokół Activity to protokół komunikacyjny i standardowy protokół używany przez firmę Microsoft w wielu zestawach MICROSOFT SDK, usługach i klientach. Obejmuje to rozwiązanie Microsoft 365 Copilot, Microsoft Copilot Studio i zestaw SDK agentów platformy 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 co najmniej jednym kanałem w celu interakcji z użytkownikami i pracy z innymi agentami. Protokół Activity standaryzuje protokół komunikacyjny między dowolnym klientem, z którym pracujesz, w tym klientami Microsoft i innych firm, dzięki czemu nie trzeba tworzyć niestandardowej logiki dla każdego kanału, z którym pracujesz.

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ą tylko wiadomościami tekstowymi; mogą obejmować różne typy interakcji, w tym zdarzenia, takie jak dołączanie lub opuszczanie użytkowników w systemach obsługujących wielu użytkowników, wskaźniki pisania, przesyłanie plików, akcje związane z kartami i niestandardowe zdarzenia projektowane przez samych deweloperów.

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ół działania — Działanie. Niektóre właściwości klucza zdefiniowane w protokole Działania to:

Dane dotyczące działań programu Access

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

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

• .NET: TurnContext
• Python: TurnContext
• JavaScript: TurnContext

TurnContext to ważny obiekt używany w każdej turze rozmowy w zestawie SDK agentów Microsoft 365. 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 utrzymania kontekstu, wysyłania odpowiednich odpowiedzi i efektywnego interakcji z użytkownikami w kliencie/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 funkcji obsługi/metod. Ten obiekt kontekstu istnieje podczas pojedynczego ruchu, a następnie usuwany po zakończeniu ruchu.

Tura jest definiowana jako droga komunikatu wysyłanego przez klienta i docierającego do kodu, gdzie kod przetwarza te dane i może opcjonalnie wysłać odpowiedź z powrotem, aby zakończyć tę turę. Ta runda można podzielić na:

1. Działanie przychodzące: użytkownik wysyła komunikat lub wykonuje akcję, która tworzy działanie.
2. Kod odbiera działanie, a agent przetwarza go przy użyciu polecenia TurnContext.
3. Agent odsyła jedną lub więcej działań.
4. Tura kończy się i TurnContext jest usuwana.

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 jest ważny, ponieważ definiuje, co jest wymagane lub oczekiwane w pozostałej części działania między klientami, użytkownikami i agentami.

Message

Typowym typem działania jest typ komunikatuActivity, który może zawierać tekst, załączniki i sugerowane akcje, aby wymienić kilka typowych zastosowań dla tego typu.

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 to obsługują; godnym uwagi klientem, który to robi, jest Microsoft Teams.

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

Events

Typ ZdarzenieActivity to zdarzenia niestandardowe, które umożliwiają kanałom lub klientom wysyłanie danych strukturalnych do agenta, które nie są wstępnie zdefiniowane w strukturze ładunku Activity.

Należy utworzyć metodę/procedurę obsługi tras dla określonego Event typu, a następnie zarządzać żądaną logiką w oparciu o następujące elementy:

Nazwa — nazwa zdarzenia lub identyfikator z 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)
}

Invoke

Typ WywołajActivity jest określonym typem działania, które klient wywołuje do agenta w celu wykonania polecenia lub operacji, a nie tylko komunikatu. Przykłady tych typów działań są powszechne w Microsoft Teams dla task/fetch i task/submit. Nie wszystkie kanały obsługują tego typu działania.

Pisanie

Typ PisanieActivity to klasyfikacja działań wskazująca, że ktoś wpisuje podczas konwersacji. Jest to 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, a w szczególności Microsoft 365 Copilot nie obsługuje czynności wpisywania.

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, funkcja "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 przesł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), a kod musi obsługiwać odbieranie komunikatu z załącznikiem, odczytywanie metadanych i bezpieczne pobieranie pliku z podanego adresu URL. Zazwyczaj plik jest przenoszony do własnej pamięci masowej.

Aby otrzymać załącznik

Poniższy kod pokazuje, jak odbierać i dołączać

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 w załączniku, klient wysyła uwierzytelnione GET żądanie w celu pobrania rzeczywistej zawartości — każdy adapter ma własny sposób pozyskiwania tych danych, na przykład Teams, OneDrive itp. Ważne jest również, aby wiedzieć, że te adresy URL są zwykle krótkotrwałe, więc nie należy zakładać, że pozostaną tam, dlatego przejście do własnego magazynu jest ważne, jeśli trzeba się do nich później odwołać.

Cytaty

Ważne jest, aby wiedzieć, że załącznik i cytat nie są tym samym typem obiektu. Cytaty są obsługiwane przez klientów, takich jak Microsoft Teams, na różne sposoby, i wykorzystują właściwość Entities obiektu Activity. Można je dodać używając elementu activity.Entities.Add oraz dodać nowy obiekt Entity, który zawiera specyficzną definicję Citation w oparciu o danego klienta. Zostanie ona serializowana jako obiekt JSON, który następnie klient deserializuje w oparciu o sposób renderowania go 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 platformy Microsoft 365 jest tworzony jako "Hub", który umożliwia deweloperom tworzenie agentów, mogących współpracować z dowolnym klientem, w tym z klientami, których obsługujemy, oraz dostarcza deweloperom narzędzia do budowania własnego adaptera kanału przy użyciu tej samej platformy. To 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, a poniżej przedstawiono podsumowanie zagadnień dotyczących pracy z typowymi klientami.

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 Activity ładunkiem we wszystkich kanałach, a dostęp do nich można uzyskać z TurnContext.Activity.ChannelData, a następnie dokonać ich rzutowania do zmiennych używanych w kodzie.

Microsoft Teams

• Obsługuje zaawansowane karty adaptacyjne z zaawansowanymi funkcjami
• Obsługuje aktualizacje i usuwanie komunikatów
• Zawiera określone dane kanału dla funkcji Teams (wzmianki, informacje o spotkaniu itd.)
• Obsługuje działania wywoływania dla modułów zadań

Microsoft 365 Copilot

• Przede wszystkim koncentruje się na działaniach związanych z komunikatami
• Obsługuje cytaty i odwołania w odpowiedziach
• Wymaga odpowiedzi strumieniowych
• Ograniczona obsługa zaawansowanych kart/kart dynamicznych

WebChat/DirectLine

Czat internetowy to protokół HTTP używany przez agentów 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 innych firm

Należą do nich 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