Etkinlik Protokolünü Anlamak

Etkinlik Protokolü, Microsoft bünyesindeki birçok Microsoft SDK'sında, hizmetinde ve istemcisinde kullanılan standart bir iletişim protokolüdür. Etkinlik Protokolü, Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams ve Microsoft 365 Aracıları SDK'sı tarafından kullanılır. Etkinlik Protokolü, bir Activity yapısını ve mesajların, olayların ve etkileşimlerin bir kanaldan kodunuza ve aradaki her yere nasıl aktarıldığını tanımlar. Aracılar, kullanıcılarla etkileşim kurmak ve diğer aracılarla birlikte çalışmak için bir veya daha fazla kanala bağlanabilir. Activity Protocol, Microsoft ve Microsoft dışı istemciler dahil olmak üzere çalıştığınız tüm istemcilerle iletişim protokolünü standart hale getirir; böylece her kanal için özel bir mantık oluşturmanıza gerek kalmaz.

Etkinlik nedir?

Bir Activity, kullanıcı ile aracınız arasındaki herhangi bir etkileşimi temsil eden yapılandırılmış bir JSON nesnesidir. Etkinlikler sadece metin tabanlı mesajlarla sınırlı değildir. Bunlar, çoklu kullanıcı desteğine sahip uygulamalarda kullanıcının sisteme katılması veya sistemden ayrılması gibi olaylar, yazma göstergeleri, dosya yüklemeleri, kart eylemleri ve geliştiricilerin tasarladığı özel olaylar gibi çeşitli etkileşim türlerini içerebilir.

Her etkinlik, aşağıdakilerle ilgili meta veriler içerir:

Kim gönderdi (kimden)
Kim almalıdır (alıcı)
Konuşmanın bağlamı
Kaynağı olan kanal
Etkileşim türü
Yük verileri

Etkinlik şeması - temel özellikler

Bu şartname, Etkinlik Protokolünü tanımlamaktadır: Etkinlik Protokolü - Etkinlik. Activity Protocol'de tanımlanan temel özelliklerden bazıları şunlardır:

Özellik	Açıklama
`Id`	Bir kanaldan kaynaklanıyorsa, genellikle kanal tarafından oluşturulur
`Type`	Tür, bir etkinliğin anlamını belirler; örneğin, mesaj türü
`ChannelID`	`ChannelID`, etkinliğin kaynaklandığı kanalı belirtir. Örneğin: `msteams`.
`From`	Etkinliğin göndereni (bir kullanıcı veya aracı olabilir)
`Recipient`	Etkinliğin hedef kitlesi
`Text`	İletinin metin içeriği
`Attachment`	Kartlar, dosya resimleri gibi zengin içerikler

Etkinlik verilerine erişim

TurnContext nesnesinden eylemleri gerçekleştirmek için, geliştiricilerin etkinlik içindeki verilere erişmesi gerekir.

Microsoft 365 Aracıları SDK'sının her dil sürümünde bir TurnContext sınıfı bulabilirsiniz:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Not

Bu makaledeki kod parçacıkları C# dilinde yazılmıştır. JavaScript ve Python sürümlerinin sözdizimi ve API yapısı birbirine benzerdir.

TurnContext, Microsoft 365 Aracıları SDK'sı'da her konuşma turunda kullanılan önemli bir nesnedir. Gelen etkinliklere erişim, yanıt gönderme yöntemleri, konuşma durumu yönetimi ve tek bir konuşma turunu yönetmek için gerekli bağlamı sağlar. Bunu, bağlamı korumak, uygun yanıtlar göndermek ve kullanıcılarınızla onların istemcisinde veya kanalında etkili bir şekilde etkileşim kurmak için kullanın. Aracınız bir kanaldan her yeni etkinlik aldığında, Aracılar SDK'sı yeni bir TurnContext örneği oluşturur ve bunu kayıtlı işleyicilerinize veya yöntemlerinize iletir. Bu bağlam nesnesi, tek bir tur boyunca mevcuttur ve tur sona erdiğinde imha edilir.

Tur, istemciden gönderilen bir iletinin sizin kodunuza kadar olan gidiş dönüşü olarak tanımlanır. Kodunuz bu verileri işler ve isteğe bağlı olarak turu tamamlamak üzere bir yanıt gönderebilir. Bu gidiş-dönüş yolculuğu aşağıdaki adımlara ayrılabilir:

Gelen etkinlik: Kullanıcı, bir etkinlik oluşturan bir mesaj gönderir veya bir işlem gerçekleştirir.
Kodunuz etkinliği alır ve aracı bunu TurnContext kullanarak işler.
Aracınız bir veya daha fazla etkinlik bilgisi gönderir.
Tur sona erer ve TurnContext atılır.

TurnContext üzerinden aşağıdakiler gibi verilere erişin:

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

Bu kod parçacığı, tam bir dönüşün bir örneğini göstermektedir:

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

TurnContext sınıfının içinde yaygın olarak kullanılan temel bilgiler şunlardır:

Etkinlik: Etkinlikten bilgi almanın başlıca yolu
Adaptör: Etkinliği oluşturan kanal adaptörü
TurnState: Sıra durum

Etkinlik türleri

Bir faaliyetin türü, bu faaliyetin geri kalan kısmında müşteriler, kullanıcılar ve aracılar arasında nelerin gerekli olduğunu veya beklendiğini belirler.

Bunlar aşağıdakileri içerir:

İleti
ConversationUpdate
Etkinlik
Çağır
Yazım

İleti

Yaygın bir etkinlik türü ActivityMesaj türüdür. Bu Activity türü, metin, ekler ve önerilen eylemleri içerebilir.

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

Activity Sohbet Güncelleştirme türü, üyeler bir sohbete katıldığında veya sohbetten ayrıldığında aracınıza bildirim gönderir. Tüm istemciler bu bildirimi desteklemez, ancak Microsoft Teams destekler.

Aşağıdaki kod parçacığı, bir sohbette yeni üyelere hoş geldiniz mesajı gönderir:

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

Olaylar

Activity Olay türü, kanalların veya istemcilerin yapılandırılmış verileri aracınıza göndermek için kullandığı özel bir olaydır. Bu veriler, Activity yük yapısında önceden tanımlanmamıştır.

Belirtilen Event türü için bir yöntem veya rota işleyicisi oluşturmanız gerekir. Ardından, aşağıdakilere göre istenen mantığı yönetin:

Ad: İstemcinin olay adı veya tanımlayıcısı
Değer: Genellikle bir JSON nesnesi olan olay yükü

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

Çağır

Activity Invoke türü, bir istemcinin bir komutu veya işlemi gerçekleştirmek üzere bir aracıya gönderdiği belirli bir etkinlik türüdür. Bu sadece bir mesaj değil. Bu tür etkinliklere ilişkin örnekler, Microsoft Teams'de task/fetch ve task/submit için sıkça görülür. Bu tür etkinlikleri destekleyen kanallar her zaman değildir.

Yazım

Activity Yazma türü, bir kişinin sohbet sırasında yazmakta olduğunu belirtmek için kullanılan bir etkinlik sınıflandırmasıdır. Bu etkinlik, örneğin Microsoft Teams istemcisinde insanlar arasındaki sohbetlerde sıklıkla görülür. Yazma etkinlikleri her istemcide desteklenmemektedir. Özellikle belirtmek gerekirse, Microsoft 365 Copilot yazma faaliyetlerini desteklemiyor.

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

Etkinlikler oluşturma ve gönderme

Yanıtları göndermek için TurnContext, kullanıcıya yanıtları geri göndermek üzere çeşitli yöntemler sunar.

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
}

Eklerle çalışma

Aracılar genellikle kullanıcıların (hatta diğer aracıların) gönderdiği eklerle çalışır. İstemci, bir ek içeren bir Message etkinliği gönderir (bu, belirli bir etkinlik türü değildir). Kodunuz, ek içeren mesajı almayı, meta verileri okumayı ve istemcinin sağladığı URL'den dosyayı güvenli bir şekilde indirmeyi sağlamalıdır. Genellikle, dosyayı kendi depolama alanınıza taşırsınız.

Ek almak için

Aşağıdaki kod, bir ekin nasıl alınacağını göstermektedir.

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

Genellikle, ekteki belgeyi almak için istemci, asıl içeriği almak üzere kimlik doğrulamalı bir GET isteği gönderir. Her adaptörün bu verileri elde etmenin kendine özgü bir yöntemi vardır. Örneğin, Teams, OneDrive vb. Ayrıca, bu URL'lerin genellikle kısa süreli olduğunu bilmek önemlidir; bu nedenle, URL'lerin uzun süre geçerli kalacağını varsaymayın. Bu sınırlama nedeniyle, içeriğe daha sonra başvurmanız gerekiyorsa kendi depolama alanınıza taşıma işlemi önemlidir.

Alıntılar

Ek ve Alıntı'nın aynı nesne türü olmadığını bilmek önemlidir. Microsoft Teams gibi istemciler, alıntıları kendilerine özgü yöntemlerle işler. Activity Entities özelliğini kullanıyorlar. activity.Entities.Add ile alıntılar ekleyebilir ve müşterinize göre belirli Citation tanımına sahip yeni bir Entity nesnesi ekleyebilirsiniz. İstemcinin istemcide nasıl işlendiğini temel alarak seri durumdan çıkardığı bir JSON nesnesi olarak seri hâle getirilir. Temel olarak, Ekler mesajlardır ve Alıntılar eklere başvurabilir ve Activity yükünün Entities'inde gönderilen başka bir nesnedir.

Kanal özelinde dikkate alınması gereken hususlar

Microsoft 365 Aracıları SDK'sı, geliştiricilerin desteklediğimiz istemciler de dahil olmak üzere herhangi bir istemciyle çalışabilen aracılar oluşturmak için kullandıkları bir "Merkez" olarak tasarlanmıştır. Geliştiricilere, aynı çerçeveyi kullanarak kendi kanal adaptörlerini geliştirmeleri için gerekli araçları sunar. Bu mimari, geliştiricilere aracılar konusunda geniş bir yelpaze sunar ve istemcilerin bu merkezi ağa bağlanabilmesi için genişletilebilirlik sağlar; bu istemciler, Microsoft Teams, Slack ve benzeri bir veya daha fazla istemci olabilir.

Farklı kanalların farklı yetenekleri ve sınırlamaları vardır.

Etkinliği aldığınız kanalı, Activity içindeki channelId özelliğini inceleyerek denetleyebilirsiniz.

Kanallarda, tüm kanallarda geçerli olan genel Activity veri yüküne uymayan belirli veriler yer alır. Bu verilere, kodunuzda kullanmak üzere bunları değişkenlere dönüştürerek TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) özelliğinden erişebilirsiniz.

Aşağıdaki bölümlerde, yaygın olarak kullanılan istemcilerle çalışırken dikkate alınması gereken hususlar özetlenmiştir.

Microsoft Teams

Gelişmiş özelliklere sahip zengin Uyarlamalı Kartlar'ı destekler.
Mesajları güncelleştirmek ve silmek için destek sağlar.
Teams özelliklerine ilişkin belirli kanal verilerini içerir; örneğin, etiketlemeler ve toplantı bilgileri gibi.
Görev modülleri için etkinlik çağırma işlevini destekler.

Microsoft 365 Copilot

Öncelikle mesaj faaliyetlerine odaklanmıştır.
Yanıtlarda alıntı ve kaynak gösterimlerini destekler.
Yanıtların akış halinde gönderilmesi gerekir.
Zengin kartlar ve uyarlamalı kartlar için sınırlı destek.

Web Sohbeti/DirectLine

Web Sohbeti, aracıların HTTPS üzerinden iletişim kurmak için kullanabilecekleri bir HTTP protokolüdür.

Tüm etkinlik türleri için tam destek.
Özel kanal verilerini destekler.

Microsoft dışındaki kanallar

Bu kanallar arasında Slack, Facebook ve diğerleri yer almaktadır.

Belirli etkinlik türleri için sınırlı destek sunabilir.
Kartın görüntülenmesi farklı olabilir veya desteklenmeyebilir.
Her zaman ilgili kanalın belgelerine bakın.

Sonraki adımlar

AgentApplication hakkında bilgi edinin

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-30