Bir olay ve etkinlik gönderme

Copilot Studio, ileti olmayan etkinlikler için kullanabileceğiniz bir düğüm kümesi sağlar: Olay etkinliği düğümü, Invoke etkinlik düğümü ve etkinlik protokolünün desteklediği etkinlikle ilgili diğer düğümler.

Etkinlik protokolü nedir?

Etkinlik protokolü, Copilot Studio'daki temel aktarım konseptidir. Etkinlik protokolü, kullanıcılar ve aracılar arasında sorunsuz iletişim sağlar. Tüm etkileşimler için standartlaştırılmış bir yapı tanımlar ve bunları çeşitli aktivite türlerine göre sınıflandırır.

Olay etkinlikleri ve ileti etkinlikleri, etkinlik protokolü içinde her biri iletişim iş akışlarında benzersiz amaçlara hizmet eden iki ayrı türdedir.

İleti etkinlikleri öncelikle metinsel, medya veya uyarlamalı kart içeriği taşıyan kullanıcılar ve aracılar arasındaki temel iletişim birimlerini temsil eder. Bunlar, kullanıcının sorgu veya deyim yaptığı ve aracının buna göre yanıt verdiği doğrudan etkileşimler için tasarlanmıştır.

Buna karşılık, etkinlikler genellikle sözsüz eylemleri veya sistem tarafından oluşturulan güncellemeleri belirtmek için kullanılır. Doğrudan kullanıcı etkileşimi gerektirmeden belirli işlevleri veya iş akışlarını tetikleyerek zaman uyumsuz iletişime izin verirler. Örneğin, bir olay etkinliği, bir kullanıcının konuşmaya katılması veya çevresindeki bağlamdaki değişiklikler hakkında bir aracıya bilgilendirebilir.

Etkinlik gönderimi

Olay etkinliği düğümü, olay etkinliklerini göndermek için tasarlanmıştır. Etkinlik etkinlikleri aracı öğesinden gönderilir ve etkinliklerin kullanılıp kullanılmayacağına ve nasıl kullanılacağına karar veren kanal tarafından durdurulabilir ve kullanılabilir. Bir olay gönderdiğinizde, ona bir ad verirsiniz ve ardından olay için bir değer ayarlayabilirsiniz. Bu değer herhangi bir biçimde olabilir:

  • İlkel bir değişmez değer
  • Değişken başvuru
  • Power Fx formülü.

Değer, JSON literal olarak serileştirilir ve giden aktiviteye eklenir.

Bu düğümün kullanımları aşağıdakileri içerir:

  • Aracıdan gönderilen olayları işlemek için özel bir Web Sohbet denetimi yapılandırın. Örneğin, aracıdan tekrar gelen bir etkinlik arayabilir ve sayfada bir eylem gerçekleştirebilirsiniz. GitHub'daki 04.api/c.incoming-activity-event örneği, olay işlemenin nasıl çalışabileceğini gösterir.
  • AudioCodes kayıt hizmetlerini denetlemek için olay etkinliklerini kullanın; örneğin, arama kaydını başlatmak veya durdurmak için. Daha fazla bilgi için Kayıt çağrılarına bakın.

İstemci araçlarını kullanma

Düzenleme sırasında dil modeline bir dizi araç sağlarız. Çoğu insan araçları dış sistemlere çağırma olarak düşünür.

API aracılığıyla sunucu tarafı araçları.

Ancak, olay etkinliklerini istemciden gelen araçları çalıştırmak için de kullanabiliriz.

Olay etkinlikleri aracılığıyla istemci tarafı araçları.

Orkestratör bir istemci aracını yürütmeye karar verdiğinde, ajan araçta tanımlanan girdiler de dahil olmak üzere istemciye bir etkinlik gönderir.

Aracı etkinliği gönderir, ardından istemcinin eylemi gerçekleştirmesini ve bir sonuç döndürmesini bekler. İstemci işini tamamladığında, yanıtı içeren bir etkinlik bildirimi aracıya gönderir. Ajan bu yanıtı araç yanıtı olarak kabul eder ve orkestrasyona devam eder.

İstemci araçları için örnek veri yükleri

PowerPoint slaydındaki metni alan bir istemci aracımız olduğunu varsayalım.

Girişler sayfa numarasıdır ve çıktı slayttaki metindir.

Aracı aşağıdaki gibi bir yük gönderebilir:

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

İşlem tamamlandıktan sonra, istemci aracıya aşağıdaki gibi bir yük benzeri bir şey gönderir:

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

İstemci araçlarını ayarlama

İstemci araçlarını kaydetmenin iki yolu vardır.

Aracı konu içeriğinizin bir parçası olarak, kod düzenleyicisini kullanarak temsilcinizde özel bir istemci görevi eylemi kaydedebilirsiniz.

Örneğin:

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

Bazen, kullanılabilir araçlar barındırma istemcisinin bağlamını temel alarak dinamik olur. Daha fazla esneklik sağlamak için oluşturucular, bu oturum için kullanılabilecek diğer istemci araçlarını dinamik olarak ayarlamak için bir sistem değişkeni ayarlayabilir.

- 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" 
            } 
          } 
        ] 
      } 
    ]

Diğer etkinlik türlerini gönderme

Olay etkinliklerine ek olarak, Etkinliği çağır düğümünü kullanarak diğer türlerdeki etkinlikleri de gönderebilirsiniz. Gönderebileceğiniz etkinlik türleri, Bot Framework Şeması - ActivityTypes Sınıfında sunulanların bir alt kümesidir. Bu düğümü kullanırken etkinliğin türünü seçersiniz ve ardından isteğe bağlı olarak bir ad veya değer ayarlarsınız.

Yaygın türler şunlardır:

  • Yazma, kanalın almayı seçebileceği ve istemcide bir yazma göstergesi gösterebileceği bir yazma etkinliği gönderir.
  • Çağırma ve Çağırma yanıtı Microsoft Teams için kullanılır. Teams'den gelen bir Invoke'u engellemek için bir invoke tetikleyicisi içeren bir konu oluşturun ve Teams'e uygun bir yanıt göndermek için bir Invoke yanıt etkinliği düğümü kullanın.
  • Devir, değer üzerinde açık denetime sahip bir devir etkinliği gönderir. Devir, AudioCodes gibi harici kanallar için kullanılır.

İlgili içerik

  • Last updated on