Udostępnij za pośrednictwem

Wysyłanie zdarzenia lub działania

Copilot Studio udostępnia zestaw węzłów, których można użyć do działań, które nie są komunikatami: węzeł działania zdarzenia , węzeł Wywołaj działanie i inne węzły związane z działaniami obsługiwane przez protokół działania .

Co to jest protokół działania?

Protokół działania to podstawowa koncepcja transportu w Copilot Studio. Protokół działania umożliwia bezproblemową komunikację między użytkownikami i agentami. Definiuje ustandaryzowaną strukturę dla wszystkich interakcji, kategoryzując je na różne typy działań.

Działania związane ze zdarzeniami i działania związane z komunikatami są dwoma odrębnymi typami w protokole działań, z których każdy służy unikalnym celom w procesach komunikacyjnych.

Działania komunikatów reprezentują podstawowe jednostki komunikacji między użytkownikami i agentami, głównie przenoszące zawartość tekstową, multimedialną lub karty adaptacyjnej. Są one przeznaczone do bezpośrednich interakcji, w których użytkownik wykonuje zapytanie lub instrukcję, a agent odpowiednio odpowiada.

Z drugiej strony działania związane z zdarzeniami są zwykle używane do oznaczania niewerbalnych akcji lub aktualizacji generowanych przez system. Umożliwiają one komunikację asynchroniczną, wyzwalanie określonych funkcji lub przepływów pracy bez konieczności bezpośredniej interakcji z użytkownikiem. Na przykład działanie związane ze zdarzeniem może powiadomić agenta o dołączeniu użytkownika do konwersacji lub zmianach w otaczającym kontekście.

Wysyłanie zdarzeń

Węzeł Aktywność zdarzenia jest przeznaczony do wysyłania aktywności zdarzenia. Działania dotyczące zdarzeń są wysyłane z pomocnika i mogą być przechwytywane i używane przez kanał, co decyduje o tym, czy i jak korzystać z tych działań. Po wysłaniu zdarzenia nadasz mu nazwę, a następnie możesz ustawić wartość zdarzenia. Ta wartość może mieć dowolny format:

  • Prymitywna wartość literału
  • Zmienna referencyjna
  • Formuła Power Fx.

Wartość jest serializowana jako literał JSON i dodawana do wychodzącej aktywności.

Zastosowania tego węzła to:

  • Skonfiguruj niestandardową kontrolkę czatu sieciowego do obsługi zdarzeń wysyłanych z agenta. Na przykład można szukać zdarzenia wracającego z agenta i wykonywać akcję na stronie. Przykład 04.api/c.incoming-activity-event w repozytorium przykładów czatu internetowego Microsoft Bot Framework zademonstruje, jak może działać obsługa zdarzeń.
  • Użyj aktywności zdarzeń, aby kontrolować usługi nagrywania AudioCodes — na przykład do uruchamiania lub zatrzymywania nagrywania połączeń. Aby uzyskać więcej informacji, zobacz Rejestrowanie wywołań.

Korzystanie z narzędzi klienckich

Podczas orkiestracji udostępniamy model językowy z zestawem narzędzi. Większość ludzi myśli o narzędziach jako o wywołujących systemy zewnętrzne.

Narzędzia po stronie serwera za pośrednictwem interfejsu API.

Możemy jednak również używać działań zdarzeń do wykonywania narzędzi z poziomu klienta.

Narzędzia po stronie klienta poprzez działania związane z wydarzeniami.

Kiedy koordynator decyduje się wykonać narzędzie klienta, agent wysyła do klienta aktywność zdarzenia, zawierającą dane wejściowe zdefiniowane w narzędziu.

Agent wysyła działanie, a następnie czeka, aż klient wykona akcję i zwróci wynik. Gdy klient zakończy operację, wysyła do agenta zdarzenie zawierające odpowiedź. Agent przyjmuje tę odpowiedź jako odpowiedź narzędzia i kontynuuje aranżację.

Przykładowe ładunki dla narzędzi klienckich

Załóżmy, że mamy narzędzie klienckie, które pobiera tekst na slajdzie programu PowerPoint.

Dane wejściowe to numer strony, a dane wyjściowe są tekstem na slajdzie.

Agent może wysłać ładunek, taki jak:

{ 
    "type": "event", 
    "timestamp": 1738709828, 
    "from": { 
        "id": "d9c0dcf9-4045-8062-535b-73fb4dfee954", 
        "role": 0 
    }, 
    "name": "getSlideContent", 
    "replyToId": "f617c120-7b36-496a-a096-ac692efdad04", 
    "value": { 
        "page": 5      
    } 
}

Po zakończeniu operacji klient wysyła agentowi ładunek, taki jak:

{ 
    "type": "event", 
    "timestamp": 1738709828, 
    "name": "getSlideContent", 
    "replyToId": "f617c120-7b36-496a-a096-ac692efdad04", 
    "value": { 
        "content": "QA slide. Next steps"      
    } 
}

Konfigurowanie narzędzi klienckich

Istnieją dwa sposoby rejestrowania narzędzi klienckich.

W ramach zawartości tematu agenta możesz zarejestrować dedykowaną akcję zadania klienta na agencie przy użyciu edytora kodu.

Przykład:

description: this tool retrieves the content of a powerpoint slide 
schemaName: GetSlideContent 
    dialog: 
      kind: TaskDialog 
      action: 
        kind: InvokeClientTaskAction 
        clientActionInputSchema: 
          kind: Record 
          properties: 
            page: 
            displayName: Page Number 
            description: The number of the slide 
            isRequired: true 
              type: Number 
        clientActionResponseSchema: 
          kind: Record 
          properties: 
            content: 
            displayName: Slide Content 
            description: The content of the slide 
              type: String

Czasami dostępne narzędzia są dynamiczne na podstawie kontekstu klienta hostingu. Aby zapewnić większą elastyczność, twórcy mogą ustawić zmienną systemową w celu dynamicznego ustawiania innych narzędzi klienckich, które mogą być używane na potrzeby tej sesji.

- kind: SetVariable 
  id: setVariable_76NZWK 
  variable: System.ClientPluginActions 
  value: |- 
    =[ 
      { 
        Description: "this tool retrieves the content of a powerpoint slide", 
        Identifier: "GetSlideContent", 
        Name: "GetSlideContent", 
        Response: {mode: "Generated"}, 
        Inputs: [ 
          { 
            Description: "The name of the menu for the form to launch", 
            IsAutomatic: true, 
            IsRequired: true, 
            Name: "Page Number", 
            PropertyName: "page", 
            Type: { 
              '$kind': "Number" 
            } 
          } 
        ], 
        Outputs: [ 
          { 
            Description: "The content of the slide", 
            Name: "Slide Content", 
            PropertyName: "content", 
            Type: { 
              '$kind': "String" 
            } 
          } 
        ] 
      } 
    ]

Wysyłanie innych typów działań

Oprócz aktywności związanych z wydarzeniami można wysyłać aktywności innych typów przy użyciu węzła Wywołaj aktywność. Typy działań, które można wysłać, są podzbiorem działań oferowanych w Schemacie Bot Framework — klasa typów działań. Podczas używania tego węzła należy wybrać typ działania, a następnie opcjonalnie ustawić nazwę lub wartość.

Typowe są następujące typy:

  • Wpisanie — wysyła działanie wpisywania, które kanał może odebrać i wyświetlić wskaźniki wpisywania na kliencie.
  • Wywołanie i odpowiedź wywołania są używane w Microsoft Teams. Tworzysz temat z wyzwalaczem wywołania, aby przechwycić przychodzące wywołanie z Teams, a następnie używasz węzła Wywołaj aktywność odpowiedzi, aby wysłać odpowiednią odpowiedź z powrotem do Teams.
  • Przekazywanie wysyła działanie przekazania z jawną kontrolą nad wartością. Przekazywanie połączeń jest używane dla kanałów zewnętrznych, takich jak AudioCodes.

Powiązana zawartość