AgentApplication dalam Agen SDK Microsoft 365

AgentApplication adalah penyusun baris pusat dari agen yang dibangun dengan SDK Agen. AgentApplication adalah titik masuk untuk semua aktivitas masuk, termasuk pesan dari pengguna, peristiwa siklus hidup percakapan, interaksi kartu adaptif, dan callback OAuth.

Agen, pada intinya, sebuah AgentApplication. Anda mengonfigurasinya dengan handler yang menjelaskan apa yang dilakukan agen Anda. SDK mengurus perutean, manajemen status, dan infrastruktur yang diperlukan untuk menjalankannya.

Cara kerja AgentApplication

Setiap agen memiliki siklus hidup yang dimulai ketika sebuah saluran (Microsoft Teams, layanan bot, atau klien khusus) mengirimkan aktivitas ke titik akhir agen Anda. AgentApplication menjadi inti dari siklus hidup tersebut:

Channel → Hosting layer → AgentApplication → Your handlers

Lapisan pemrosesan dalam agen yang dibuat dengan Agents SDK berfungsi sebagai berikut:

1. Lapisan hosting menerima permintaan HTTP dan mengautentikasinya.
2. AgentApplication memproses aktivitas masuk melalui alurnya.
3. Handler Anda dipanggil berdasarkan rute yang cocok.

Agen Anda memuat status giliran sebelum handler Anda berjalan. Setelah itu, agen menyimpan status giliran.

Konsep inti

Aktivitas

Semua yang ada dalam SDK Agen mengalir sebagai aktivitas. Sebuah aktivitas adalah pesan terstruktur yang merepresentasikan suatu peristiwa. Sebuah aktivitas memiliki tipe, seperti message, event, invoke, conversationUpdate, dan sebagainya. Aktivitas membawa payload yang relevan dengan tipenya. AgentApplication menerima aktivitas dan merutekannya ke handler yang tepat.

Rute

Rute memasangkan pemilih dengan handler. Pemilih menentukan apakah rute cocok dengan aktivitas saat ini. Handler menjalankan logika Anda saat rute cocok.

Daftarkan rute saat Anda mengonfigurasi agen Anda. Mereka dapat mencocokkan:

• Pesan yang berisi teks tertentu atau cocok dengan ekspresi reguler
• Aktivitas apa pun dari jenis tertentu
• Peristiwa siklus percakapan (anggota ditambahkan, anggota dihapus)
• Tindakan kartu adaptif
• Kondisi kustom

Ketika sebuah aktivitas masuk, sistem mengevaluasi rute satu per satu hingga menemukan kecocokan. Secara bawaan, hanya satu rute yang dijalankan.

Status giliran

AgentApplication mengelola _turn state—penyimpanan terstruktur yang dipartisi menjadi beberapa cakupan:

Jenis cakupan	Deskripsi
Percakapan	Dibagikan kepada semua pengguna dalam percakapan, disimpan di antara giliran
Pengguna	Dikhususkan untuk satu pengguna di semua percakapan
Sementara	Giliran saat ini saja - tidak pernah bertahan

Sistem ini secara otomatis memuat status sebelum handler Anda berjalan dan menyimpannya secara otomatis setelahnya.

Konteks giliran

Saat handler berjalan, handler akan menerima konteks giliran. Konteks giliran adalah snapshot aktivitas saat ini, koneksi adaptor, dan utilitas untuk mengirim respons. Konteks giliran adalah antarmuka Anda untuk interaksi yang sedang berlangsung.

Middleware

AgentApplication mendukung pipeline middleware. Middleware adalah rantai komponen yang memproses setiap giliran sebelum dan sesudah handler Anda dijalankan. Middleware dapat memeriksa, mengubah, atau menghentikan alur aktivitas. Penggunaan umum termasuk pencatatan log, pemeriksaan autentikasi, dan normalisasi permintaan.

Buat agen

C#

Buat subkelas dari AgentApplication dan daftarkan handler Anda di konstruktor. Kerangka kerja hosting secara otomatis menyuntikkan 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);
    }
}

Daftarkan agen Anda di Program.cs:

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

Membuat instans AgentApplication dan mendaftarkan handler pada instans menggunakan API yang fasih. Untuk memulai server, panggil startServer dari paket hosting Express.

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)

Untuk pengaturan manual Express tanpa startServer:

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

Buat instans AgentApplication dengan parameter jenis dan daftarkan handler menggunakan dekorator.

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)

Daftarkan handler aktivitas

Tangani Pesan

Cocokkan pesan berdasarkan teks persis (tidak sensitif huruf besar/kecil):

C#

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

Mencocokkan pesan menggunakan ekspresi reguler:

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...")
})

Mencocokkan pesan menggunakan ekspresi reguler:

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...")

Mencocokkan pesan menggunakan ekspresi reguler:

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...")

Tangani pembaruan percakapan

Daftarkan handler untuk peristiwa siklus hidup percakapan seperti anggota bergabung atau keluar.

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

Tangani semua jenis aktivitas

Cocokkan aktivitas apa pun dengan string jenisnya untuk kontrol penuh atas perutean.

C#

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

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

Gunakan ActivityTypes konstanta alih-alih string yang dikodekan keras.

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

Urutan evaluasi rute kontrol

Sistem mengurutkan rute ke dalam urutan evaluasi tetap pada saat pendaftaran, bukan pada saat runtime. Pengurutan menggunakan dua tingkat:

1. Jenis rute: Sistem mengelompokkan rute berdasarkan jenis, dan selalu mengevaluasi jenis dengan prioritas lebih tinggi sebelum yang lebih rendah, terlepas dari peringkatnya.

   Prioritas	Jenis rute
   1 (tertinggi)	Rute pemanggilan agentik
   2	Memanggil rute (tindakan kartu adaptif, panggilan balik OAuth, dan pemanggilan sensitif waktu lainnya)
   3	Rute agentik
   4 (terendah)	Semua rute lainnya

2. Peringkat: Dalam setiap grup jenis rute, sistem mengurutkan rute berdasarkan nilai peringkatnya. Nilai numerik yang lebih rendah dievaluasi terlebih dahulu.

Gunakan konstanta RouteRank untuk menetapkan peringkat saat mendaftarkan handler:

Konstanta	Nilai	Makna
RouteRank.First	0	Dievaluasi sebelum semua rute lain dalam grupnya
RouteRank.Unspecified	32767	Digunakan sebagai default ketika peringkat tidak ditentukan
RouteRank.Last	65535	Dievaluasi setelah semua rute lain dalam grupnya

Secara default, evaluasi berhenti pada rute pertama yang cocok. Gunakan RouteRank.Last untuk fallback catch-all yang menangani apa pun yang tidak cocok dengan rute yang lebih spesifik.

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.")

Kait siklus hidup giliran

Registrasikan logika yang dijalankan pada setiap giliran, sebelum atau sesudah pencocokan rute. Kait ini berguna untuk pencatatan, lintas aspek, dan penanganan kesalahan.

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

Saat OnBeforeTurn mengembalikan false, gilirannya dibatalkan dan tidak ada rute yang dijalankan. Saat OnAfterTurn mengembalikan false, status giliran tidak disimpan.

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.")

Menggunakan status giliran

Agen secara otomatis memuat status giliran sebelum handler Anda berjalan dan menyimpannya setelahnya. Objek status giliran yang diteruskan ke handler memberi Anda akses ke cakupan yang berbeda sehingga Anda dapat membaca dan menulis data yang bertahan dari satu giliran ke giliran berikutnya atau bersifat sementara untuk giliran tersebut.

• Cakupan percakapan: Untuk data yang dibagikan di semua giliran dalam percakapan
• Cakupan pengguna: Untuk data per pengguna
• Cakupan sementara: Untuk data yang hanya perlu ada selama giliran saat ini

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

Catatan

Gunakan MemoryStorage untuk pengembangan dan pengujian lokal. Untuk penyebaran produksi, terutama yang dijalankan pada beberapa instance, gunakan penyedia penyimpanan persisten seperti Azure Cosmos DB atau Azure Blob Storage. Lihat Menggunakan penyedia penyimpanan di agen Anda.

Langkah berikutnya

• Mengelola status di Agen SDK
• Menggunakan penyedia penyimpanan di agen Anda