AgentApplication w Zestawie SDK agentów usługi Microsoft 365

AgentApplication jest centralnym modułem konstrukcyjnym agenta zbudowanego przy użyciu Agents SDK. AgentApplication to punkt wejścia dla wszystkich działań przychodzących, w tym wiadomości od użytkowników, zdarzeń cyklu życia konwersacji, interakcji z kartami adaptacyjnymi i wywołań zwrotnych protokołu OAuth.

Agent jest w swojej istocie elementem typu AgentApplication. Konfigurujesz go za pomocą programów obsługujących, które opisują, co robi agent. SDK zajmuje się routingiem, zarządzaniem stanem oraz infrastrukturą niezbędną do uruchomienia agenta.

Jak działa AgentApplication

Każdy agent ma cykl życia, który rozpoczyna się, gdy kanał (Microsoft Teams, Bot Service lub niestandardowy klient) dostarcza aktywność do punktu końcowego agenta. AgentApplication znajduje się w centrum tego cyklu życia:

Channel → Hosting layer → AgentApplication → Your handlers

Warstwy przetwarzania w agencie zbudowanym za pomocą Agents SDK działają następująco:

1. Warstwa hostingowa odbiera żądanie HTTP i uwierzytelnia je.
2. Element AgentApplication przetwarza przychodzące działanie za pośrednictwem swojego potoku.
3. Procedury obsługi są wywoływane na podstawie pasujących tras.

Agent ładuje stan tury przed uruchomieniem procedur obsługi. Następnie agent zapisuje stan tury.

Podstawowe pojęcia

Działania

Wszystkie elementy w zestawach SDK agentów przepływają jako działanie. Aktywność to uporządkowana wiadomość reprezentująca coś, co się wydarzyło. Aktywność ma typ, taki jak wiadomość, zdarzenie, wywołanie, conversationUpdate itd. Zawiera ładunek odpowiedni dla tego typu. AgentApplication odbiera aktywności i kieruje je do właściwej procedury obsługi.

Trasy

Trasa łączy selektor z procedurą obsługi. Selektor określa, czy trasa pasuje do aktualnej aktywności. Procedura obsługi uruchamia logikę, gdy trasa jest zgodna.

Rejestruj trasy podczas konfiguracji agenta. Mogą one być zgodne:

• Wiadomość zawierająca konkretny tekst lub pasująca do wyrażenia regularnego
• Dowolna aktywność danego typu
• Zdarzenia cyklu życia rozmowy (dodanie członka, usunięcie członka)
• Działania związane z kartami adaptacyjnymi
• Warunki niestandardowe

Po nadejściu działania system ocenia trasy w kolejności do momentu znalezienia dopasowania. Domyślnie uruchomiona jest tylko jedna trasa.

Stan tury

AgentApplication zarządza stanem elementu _turn — magazyn strukturalny podzielony na partycje na podstawie zakresów:

Typ zakresu	Podpis
Konwersacja	Współdzielone przez wszystkich użytkowników rozmowy, przechowywane między turami
Użytkownika	Przypisane do zakresu obejmującego pojedynczego użytkownika we wszystkich konwersacjach
Tymczasowe	Tylko bieżąca kolejka — nigdy nieutrwalana

System automatycznie ładuje stan przed uruchomieniem procedur obsługi i zapisuje go automatycznie później.

Kontekst tury

Po uruchomieniu procedury obsługi otrzymuje kontekst sesji. Kontekst tury jest migawką bieżącego działania, połączenia z adapterem oraz narzędzi do wysyłania odpowiedzi. Kontekst tury to twój interfejs do bieżącej interakcji.

Oprogramowanie pośredniczące

AgentApplication obsługuje potok oprogramowania pośredniczącego. Oprogramowanie pośredniczące to łańcuch składników, które przetwarzają każdą turę przed i po uruchomieniu procedur obsługi. Oprogramowanie pośredniczące może analizować, transformować lub przerywać przepływ aktywności. Do typowych zastosowań należą logowanie, kontrola uwierzytelniania oraz normalizacja żądań.

Utwórz agenta

C#

Rozszerz klasę AgentApplication i zarejestruj programy obsługujące w konstruktorze. Struktura hostingowa automatycznie wstrzykuje 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);
    }
}

Zarejestruj agenta w 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

Utwórz wystąpienie AgentApplication i zarejestruj procedury obsługi w wystąpieniu, używając płynnego interfejsu API. Aby uruchomić serwer, wywołaj startServer z pakietu 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)

W przypadku ręcznej konfiguracji Express bez 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

Utwórz wystąpienie AgentApplication za pomocą parametru typu i zarejestruj procedury obsługi przy użyciu dekoratorów.

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)

Rejestrowanie procedur obsługi działań

Obsługa wiadomości

Dopasuj wiadomości po dokładnym tekście (niezależnie od wielkości liter):

C#

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

Dopasuj wiadomości za pomocą wyrażenia regularnego:

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

Dopasuj wiadomości za pomocą wyrażenia regularnego:

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

Dopasuj wiadomości za pomocą wyrażenia regularnego:

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

Obsługa aktualizacji rozmów

Zarejestruj procedury obsługi dla zdarzeń cyklu życia konwersacji, takich jak dołączanie członków lub opuszczanie przez członków.

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

Obsługa dowolnego typu aktywności

Dopasowywanie dowolnej aktywności według jej ciągu znaków typu dla pełnej kontroli nad routingiem.

C#

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

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

Używaj ActivityTypes stałych zamiast zakodowanych na stałe ciągów znaków.

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

Kontroluj kolejność oceny tras

System ustala ustaloną kolejność oceny tras podczas ich rejestracji, a nie w czasie działania programu. Sortowanie wykorzystuje dwa poziomy:

1. Typ trasy: System grupuje trasy według typu i zawsze rozpatruje typy o wyższym priorytecie przed typami o niższym priorytecie, niezależnie od rangi:

   Priorytet	Typ trasy
   1 (najwyższy)	Trasy wywołania agentów
   2	Trasy wywoływania (akcje kart adaptacyjnych, wywołania zwrotne protokołu OAuth i inne wywołania zależne od czasu)
   3	Trasy agentów
   4 (najniższy)	Wszystkie inne trasy

2. Rank: W każdej grupie typu trasy system porządkuje trasy według wartości ich rangi. Najpierw oceniane są niższe wartości liczbowe.

Użyj RouteRank stałych do ustawiania rangi przy rejestracji procedury obsługi:

Stała	Value	Znaczenie
RouteRank.First	0	Oceniane przed wszystkimi innymi trasami w swojej grupie
RouteRank.Unspecified	32767	Domyślnie, gdy ranga nie jest określona
RouteRank.Last	65535	Oceniane po wszystkich innych trasach w swojej grupie

Domyślnie przetwarzanie zatrzymuje się na pierwszej pasującej trasie. Użyj RouteRank.Last jako ogólnego mechanizmu rezerwowego, który obsługuje wszystko, co nie pasuje do bardziej szczegółowej trasy.

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

Elementy zaczepienia cyklu życia tury

Zarejestruj logikę, która działa przy każdej turze, przed lub po dopasowaniu tras. Te elementy zaczepienia są przydatne w przypadku rejestrowania, zagadnień przekrojowych i obsługi błędów.

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

Gdy OnBeforeTurn zwraca wartość false, tura jest przerywana i nie są uruchamiane żadne trasy. Gdy OnAfterTurn zwraca false, stan tury nie jest zapisywany.

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

Korzystanie ze stanu tury

Agent automatycznie ładuje stan tury przed uruchomieniem procedur obsługi i zapisuje go później. Obiekt stanu tury przekazany do procedur obsługi zapewnia dostęp do różnych zakresów, dzięki czemu można odczytywać i zapisywać dane, które są utrwalane między turami lub są tymczasowe dla bieżącej tury.

• Zakres rozmowy: Dla danych współdzielonych na wszystkich turach rozmowy
• Zakres użytkownika: Dla danych indywidualnych użytkownika
• Zakres tymczasowy: dla danych, które muszą istnieć tylko podczas bieżącej tury

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

Notatka

Użyj MemoryStorage do lokalnego tworzenia i testowania. W przypadku wdrożeń produkcyjnych, zwłaszcza wdrożeń działających na wielu wystąpieniach, należy użyć dostawcy trwałej pamięci masowej, takiego jak Azure Cosmos DB lub Azure Blob Storage. Zobacz Używanie dostawców magazynu w agencie.

Następne kroki

• Zarządzanie stanem w Zestawie SDK agentów
• Używanie dostawców magazynu w agencie