Microsoft 365 Aracıları SDK'sı'de AgentApplication

AgentApplication Agents SDK ile oluşturulmuş bir ajanın merkezi yapı taşıdır. AgentApplication kullanıcılardan gelen iletiler, konuşma yaşam döngüsü olayları, uyarlamalı kart etkileşimleri, OAuth geri çağırmaları dahil olmak üzere tüm gelen etkinliklerin giriş noktasıdır.

Bir aracı özünde AgentApplication'dır. Aracınızın ne yaptığını açıklayan işleyicilerle yapılandırabilirsiniz. SDK yönlendirme, durum yönetimi ve bunu çalıştırmak için gereken altyapıyla ilgilenir.

AgentApplication nasıl çalışır?

Her aracının yaşam döngüsü, bir kanal (Microsoft Teams, bir bot hizmeti veya özel bir istemci) bir etkinliği aracın uç noktasına teslim ettiğinde başlar. AgentApplication o yaşam döngüsünün merkezinde yer alır.

Channel → Hosting layer → AgentApplication → Your handlers

Aracılar SDK'sı ile oluşturulan bir aracıda işleme katmanları aşağıdaki gibi çalışır:

1. Barındırma katmanı HTTP isteğini alır ve kimliğini doğrular.
2. AgentApplication, gelen etkinliği işlem hattı aracılığıyla işler.
3. İşleyicileriniz yolların eşleşmesine bağlı olarak çağrılır.

İşleyicileriniz çalışmadan önce aracınız işlem durumunu yükler. Daha sonra aracı tur durumunu kaydeder.

Temel kavramlar

Faaliyetler

Aracılar SDK'sı içindeki her şey bir etkinlik olarak akar. Etkinlik, gerçekleşen bir şeyi temsil eden yapılandırılmış bir iletidir. Etkinliğin ileti, olay, çağırma, konuşmaGüncelleştirme vb. gibi bir türü vardır. Bu türe uygun bir yük taşır. AgentApplication etkinlikleri alır ve doğru işleyiciye yönlendirir.

Routes

Bir yol, bir seçici ile bir işleyiciyi eşleştirir. Seçici, bir yolun geçerli etkinlikle eşleşip eşleşmediğini belirler. İşleyici, yol eşleştiğinde mantığınızı çalıştırır.

Temsilcinizi konfigüre ettiğinizde yönlendirmeleri kaydedin. Bunlar eşleşebilir:

• Belirli bir metin içeren veya normal ifadeyle eşleşen bir ileti
• Belirli bir türe ait herhangi bir etkinlik
• Konuşma yaşam döngüsü olayları (üye eklendi, üye kaldırıldı)
• Uyarlamalı kart eylemleri
• Özel koşullar

Bir etkinlik geldiğinde, sistem bir eşleşme bulana kadar yolları sırayla değerlendirir. Varsayılan olarak, yalnızca bir yol çalışır.

Dönüş durumu

AgentApplication _turn durumunu yönetir; yapılandırılmış depolama kapsamlara ayrılmıştır:

Kapsam türü	Açıklama
Konuşma	Konuşmadaki tüm kullanıcılar arasında paylaşılır ve diyalog adımları arasında kalıcılığını sürdürür
Kullanıcı	Tüm konuşmalar için bir kullanıcıya sınırlandırılmıştır
Şablon	Yalnızca geçerli tur - hiçbir zaman kalıcı değil

Sistem, işleyicileriniz çalışmadan önce durumu otomatik olarak yükler ve daha sonra otomatik olarak kaydeder.

Bağlamı değiştir

İşleyici çalıştığında bir dönüş bağlamı alır. Tur bağlamı, geçerli etkinlik, bağdaştırıcı bağlantısı ve yanıt gönderme araçlarının anlık görüntüsüdür. Tur bağlamı, geçerli etkileşime olan arabiriminizdir.

Middleware

AgentApplication bir ara yazılım hattını destekler. Ara yazılım, işleyicileriniz çalışmadan önce ve çalıştıktan sonra her işlem aşamasını işleyen bir bileşen zinciridir. Ara yazılım etkinlik akışını inceleyebilir, dönüştürebilir veya kısa devre yapabilir. Yaygın olarak kullanılan örnekler arasında log kaydı, kimlik doğrulama denetimleri ve istek normalleştirmesi bulunmaktadır.

Bir ajan oluştur

C#

Alt sınıf AgentApplication oluşturun ve oluşturucuda işleyicilerinizi kaydedin. Barındırma çerçevesi otomatik olarak ekler AgentApplicationOptions.

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeAsync);
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    private async Task WelcomeAsync(ITurnContext context, ITurnState state, CancellationToken ct)
    {
        foreach (var member in context.Activity.MembersAdded)
        {
            if (member.Id != context.Activity.Recipient.Id)
            {
                await context.SendActivityAsync("Hello! How can I help you?", cancellationToken: ct);
            }
        }
    }

    private async Task OnMessageAsync(ITurnContext context, ITurnState state, CancellationToken ct)
    {
        await context.SendActivityAsync($"You said: {context.Activity.Text}", cancellationToken: ct);
    }
}

Ajanınızı Program.cs içinde kaydedin:

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient();
builder.Services.AddSingleton<IStorage, MemoryStorage>();
builder.Services.AddAgent<MyAgent>();
builder.Services.AddAgentAspNetAuthentication(builder.Configuration);

WebApplication app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());

app.Run();

JavaScript

Fluent API'yi kullanarak AgentApplication örneğini yaratın ve işleyicileri bu örnek üzerine kaydedin. Sunucuyu başlatmak için Express barındırma paketinden arayın startServer .

import { AgentApplication, MemoryStorage, TurnContext, TurnState } from '@microsoft/agents-hosting'
import { startServer } from '@microsoft/agents-hosting-express'

const app = new AgentApplication<TurnState>({ storage: new MemoryStorage() })

app.onConversationUpdate('membersAdded', async (context: TurnContext) => {
    await context.sendActivity('Hello! How can I help you?')
})

app.onActivity('message', async (context: TurnContext, state: TurnState) => {
    await context.sendActivity(`You said: ${context.activity.text}`)
})

startServer(app)

startServer olmadan manuel Hızlı kurulum için:

import express from 'express'
import { CloudAdapter, authorizeJWT, AuthConfiguration } from '@microsoft/agents-hosting'

const authConfig: AuthConfiguration = loadAuthConfigFromEnv()
const adapter = new CloudAdapter(authConfig)
const expressApp = express()

expressApp.use(express.json())
expressApp.use(authorizeJWT(authConfig))

expressApp.post('/api/messages', async (req, res) => {
    await adapter.process(req, res, async (context) => {
        await app.run(context)
    })
})

Python

AgentApplication öğesini bir tür parametresiyle örnekleyin ve dekoratörleri kullanarak işleyicileri kaydedin.

from microsoft_agents.hosting.core import AgentApplication, TurnState, TurnContext, MemoryStorage
from microsoft_agents.hosting.aiohttp import CloudAdapter, start_agent_process
from aiohttp.web import Request, Response, Application, run_app

AGENT_APP = AgentApplication[TurnState](
    storage=MemoryStorage(),
    adapter=CloudAdapter()
)

@AGENT_APP.conversation_update("membersAdded")
async def on_members_added(context: TurnContext, state: TurnState):
    await context.send_activity("Hello! How can I help you?")

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    await context.send_activity(f"You said: {context.activity.text}")

if __name__ == "__main__":
    async def messages(req: Request) -> Response:
        return await start_agent_process(req, AGENT_APP, AGENT_APP.adapter)

    app = Application()
    app.router.add_post("/api/messages", messages)
    app["agent_app"] = AGENT_APP
    app["adapter"] = AGENT_APP.adapter
    run_app(app, host="localhost", port=3978)

Etkinlik işleyicilerini kaydetme

İletileri işleme

İletileri tam metne göre eşleştir (büyük/küçük harfe duyarsız):

C#

OnMessage("help", async (context, state, ct) =>
{
    await context.SendActivityAsync("Here's what I can do...", cancellationToken: ct);
});

Normal ifade kullanarak iletileri eşleştirme:

OnMessage(new Regex(@"^order\s+\d+$", RegexOptions.IgnoreCase), async (context, state, ct) =>
{
    await context.SendActivityAsync("Looking up your order...", cancellationToken: ct);
});

JavaScript

app.onMessage('help', async (context: TurnContext, state: TurnState) => {
    await context.sendActivity("Here's what I can do...")
})

Normal ifade kullanarak iletileri eşleştirme:

app.onMessage(/^order\s+\d+$/i, async (context: TurnContext, state: TurnState) => {
    await context.sendActivity('Looking up your order...')
})

Python

@AGENT_APP.message("/help")
async def on_help(context: TurnContext, state: TurnState):
    await context.send_activity("Here's what I can do...")

Normal ifade kullanarak iletileri eşleştirme:

import re

@AGENT_APP.message(re.compile(r"^order\s+\d+$", re.IGNORECASE))
async def on_order(context: TurnContext, state: TurnState):
    await context.send_activity("Looking up your order...")

Konuşma güncellemelerini yönetme

Üyelerin katılması veya ayrılması gibi konuşma yaşam döngüsü olayları için işleyicileri kaydedin.

C#

OnConversationUpdate(ConversationUpdateEvents.MembersAdded, async (context, state, ct) =>
{
    foreach (var member in context.Activity.MembersAdded)
    {
        if (member.Id != context.Activity.Recipient.Id)
        {
            await context.SendActivityAsync("Welcome!", cancellationToken: ct);
        }
    }
});

OnConversationUpdate(ConversationUpdateEvents.MembersRemoved, async (context, state, ct) =>
{
    // Called when participants leave the conversation
});

JavaScript

app.onConversationUpdate('membersAdded', async (context: TurnContext) => {
    for (const member of context.activity.membersAdded ?? []) {
        if (member.id !== context.activity.recipient.id) {
            await context.sendActivity('Welcome!')
        }
    }
})

app.onConversationUpdate('membersRemoved', async (context: TurnContext) => {
    // Called when participants leave the conversation
})

Python

@AGENT_APP.conversation_update("membersAdded")
async def on_members_added(context: TurnContext, state: TurnState):
    for member in context.activity.members_added or []:
        if member.id != context.activity.recipient.id:
            await context.send_activity("Welcome!")

@AGENT_APP.conversation_update("membersRemoved")
async def on_members_removed(context: TurnContext, state: TurnState):
    pass  # Called when participants leave the conversation

Herhangi bir etkinlik türünü işleme

Yönlendirme üzerinde tam denetim için herhangi bir etkinliği tür dizesine göre eşleştirin.

C#

OnActivity(ActivityTypes.Message, async (context, state, ct) =>
{
    // Handles all message activities
});

OnActivity(ActivityTypes.Event, async (context, state, ct) =>
{
    // Handles event activities
});

Sabit kodlanmış dizeler yerine sabitleri kullanın ActivityTypes .

JavaScript

app.onActivity('message', async (context: TurnContext, state: TurnState) => {
    // Handles all message activities
})

app.onActivity('event', async (context: TurnContext, state: TurnState) => {
    // Handles event activities
})

Python

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    pass  # Handles all message activities

@AGENT_APP.activity("event")
async def on_event(context: TurnContext, state: TurnState):
    pass  # Handles event activities

Rota değerlendirme sırasını denetleme

Sistem, yolları çalışma zamanında değil, kayıt sırasında belirli bir değerlendirme sırasına göre sıralar. Sıralamada iki düzey kullanılır:

1. Yol türü: Sistem yolları türe göre gruplandırır ve derecesine bakılmaksızın her zaman düşük öncelikli türlerden önce yüksek öncelikli türleri değerlendirir:

   Öncelik	Yol türü
   1 (en yüksek)	Ajan tabanlı çağırma yolları
   2	Rotaları çağırma (uyarlamalı kart eylemleri, OAuth geri çağırmaları ve zamana duyarlı diğer çağrılar)
   3	Aracı tabanlı rotalar
   4 (en düşük)	Diğer tüm yollar

2. Derece: Her yol türü grubunda sistem, rotaları sıralama değerlerine göre sıralar. Önce daha düşük sayısal değerler değerlendirilir.

İşleyici kaydederken dereceyi ayarlamak için sabitleri kullanın RouteRank :

Sabit	Değer	Anlamı
RouteRank.First	0	Grubundaki diğer tüm yollardan önce değerlendirildi
RouteRank.Unspecified	32767	Derece belirtilmediğinde varsayılan değer
RouteRank.Last	65535	Grubundaki diğer tüm yollardan sonra değerlendirildi

Varsayılan olarak, değerlendirme ilk eşleşen yolda durur. Daha belirli bir rotayla eşleşmeyen her şeyi işleyen genel bir geri dönüş için RouteRank.Last kullanın.

C#

// Specific handlers use the default rank
OnMessage("status", HandleStatusAsync);
OnMessage("help", HandleHelpAsync);

// Catch-all — handles anything not matched above
OnActivity(ActivityTypes.Message, HandleUnknownMessageAsync, rank: RouteRank.Last);

JavaScript

// Specific handlers use the default rank
app.onMessage('status', handleStatusAsync)
app.onMessage('help', handleHelpAsync)

// Catch-all — handles anything not matched above
app.onActivity('message', handleUnknownMessageAsync, RouteRank.Last)

Python

@AGENT_APP.message("/status")
async def on_status(context: TurnContext, state: TurnState):
    await context.send_activity("Status: OK")

@AGENT_APP.message("/help")
async def on_help(context: TurnContext, state: TurnState):
    await context.send_activity("Here's what I can do...")

# Catch-all — handles anything not matched above (registered last)
@AGENT_APP.activity("message")
async def on_unknown(context: TurnContext, state: TurnState):
    await context.send_activity("I didn't understand that. Type /help for options.")

Tur yaşam döngüsü kancaları

Yol eşleştirmeden önce veya sonra her dönüşte çalışan mantığı kaydedin. Bu bağlantılar günlük kaydı, çapraz ilgilendiren sorunlar ve hata işleme için kullanışlıdır.

C#

OnBeforeTurn(async (context, state, ct) =>
{
    logger.LogInformation("Turn started: {Type}", context.Activity.Type);
    return true; // Return false to abort the turn
});

OnAfterTurn(async (context, state, ct) =>
{
    logger.LogInformation("Turn completed");
    return true; // Return false to skip state saving
});

OnTurnError(async (context, state, exception, ct) =>
{
    logger.LogError(exception, "Turn error");
    await context.SendActivityAsync("Something went wrong. Please try again.", cancellationToken: ct);
});

OnBeforeTurn, false döndürdüğünde, tur iptal edilir ve hiçbir rota çalıştırılmaz. OnAfterTurn döndüğünde, false dönüş durumu kaydedilmez.

JavaScript

app.beforeTurn(async (context: TurnContext, state: TurnState) => {
    console.log(`Turn started: ${context.activity.type}`)
    return true // Return false to abort the turn
})

app.afterTurn(async (context: TurnContext, state: TurnState) => {
    console.log('Turn completed')
    return true // Return false to skip state saving
})

app.onError(async (context: TurnContext, error: Error) => {
    console.error('Turn error:', error)
    await context.sendActivity('Something went wrong. Please try again.')
})

Python

@AGENT_APP.before_turn
async def on_before_turn(context: TurnContext, state: TurnState) -> bool:
    print(f"Turn started: {context.activity.type}")
    return True  # Return False to abort the turn

@AGENT_APP.after_turn
async def on_after_turn(context: TurnContext, state: TurnState) -> bool:
    print("Turn completed")
    return True  # Return False to skip state saving

@AGENT_APP.turn_error
async def on_turn_error(context: TurnContext, state: TurnState, error: Exception):
    print(f"Turn error: {error}")
    await context.send_activity("Something went wrong. Please try again.")

Dönüş durumunu kullan

Aracı, işleyicileriniz çalışmadan önce tur durumunu otomatik olarak yükler ve daha sonra kaydeder. İşleyicilerinize geçirilen tur durumu nesnesi, farklı kapsamlara erişmenizi sağlar; böylece sırayla kalıcı olan veya geçerli tur için kısa ömürlü olan verileri okuyup yazabilirsiniz:

• Konuşma kapsamı: Bir konuşmadaki tüm turlarda paylaşılan veriler için
• Kullanıcı kapsamı: Kullanıcı başına veriler için
• Geçici kapsam: Yalnızca geçerli tur sırasında mevcut olması gereken veriler için

C#

OnActivity(ActivityTypes.Message, async (context, state, ct) =>
{
    // Conversation scope — persisted per conversation
    var count = state.Conversation.GetValue<int>("messageCount", () => 0);
    state.Conversation.SetValue("messageCount", count + 1);

    // User scope — persisted per user
    var name = state.User.GetValue<string>("displayName");

    // Temp scope — current turn only
    state.Temp.SetValue("parsedInput", context.Activity.Text?.Trim());

    await context.SendActivityAsync($"Message #{count + 1}: {context.Activity.Text}", cancellationToken: ct);
});

JavaScript

app.onActivity('message', async (context: TurnContext, state: TurnState) => {
    // Conversation scope — persisted per conversation
    let count: number = state.getValue('conversation.messageCount') ?? 0
    state.setValue('conversation.messageCount', count + 1)

    // User scope — persisted per user
    const name: string = state.getValue('user.displayName')

    await context.sendActivity(`Message #${count + 1}: ${context.activity.text}`)
})

Python

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    # Conversation scope — persisted per conversation
    count = state.get_value("conversation.message_count") or 0
    state.set_value("conversation.message_count", count + 1)

    # User scope — persisted per user
    name = state.get_value("user.display_name")

    await context.send_activity(f"Message #{count + 1}: {context.activity.text}")

Uyarı

Yerel geliştirme ve test için kullanın MemoryStorage . Üretim dağıtımları, özellikle birden çok örnekte çalışan dağıtımlar için Azure Cosmos DB veya Azure Blob Depolama gibi kalıcı bir depolama sağlayıcısı kullanın. Bkz Aracınızda depolama sağlayıcılarını kullanma.

Sonraki Adımlar

• Aracılar SDK'sında durumu yönetme
• Yazılım aracınızda depolama sağlayıcılarını kullanın