AgentApplication in Microsoft 365 Agents SDK

AgentApplication ist die zentrale Komponente eines mit dem Agents SDK entwickelten Agents. AgentApplication ist der Einstiegspunkt für alle eingehenden Aktivitäten, einschließlich Nachrichten von Benutzern, Unterhaltungslebenszyklusereignisse, Interaktionen mit adaptiven Karten, OAuth-Rückrufe.

Ein Agent ist im Kern ein AgentApplication. Sie konfigurieren ihn mit Handlern, die beschreiben, was Ihr Agent tut. Das SDK kümmert sich um Routing, Zustandsmanagement und die Infrastruktur, die für den Betrieb erforderlich ist.

Funktionsweise von AgentApplication

Der Lebenszyklus eines jeden Agents beginnt, sobald ein Kanal (Microsoft Teams, ein Bot Service oder ein benutzerdefinierter Client) eine Aktivität an den Endpunkt Ihres Agents übermittelt. AgentApplication steht im Zentrum dieses Lebenszyklus:

Channel → Hosting layer → AgentApplication → Your handlers

Die Verarbeitungsschichten in einem Agent, der mit dem Agents SDK gebaut wurde, funktionieren wie folgt:

1. Die Hosting-Schicht empfängt die HTTP-Anforderung und authentifiziert sie.
2. Die AgentApplication verarbeitet die eingehende Aktivität durch ihre Pipeline.
3. Ihre Handler werden basierend auf übereinstimmenden Routen aufgerufen.

Ihr Agent lädt den Zustand, bevor Ihre Handler laufen. Anschließend speichert der Agent den Dialogschrittstatus.

Wichtige Konzepte

Aktivitäten

Alles im Agents SDK fließt als eine Aktivität. Eine Aktivität ist eine strukturierte Nachricht, die etwas darstellt, das geschehen ist. Eine Aktivität hat einen Typ, zum Beispiel Message, Event, Aufruf, conversationUpdate und so weiter. Es trägt eine für diesen Typ relevante Nutzlast. AgentApplication nimmt Aktivitäten entgegen und leitet sie an den passenden Handler weiter.

Arbeitspläne

Eine Route verbindet einen Selektor mit einem Handler. Der Selektor bestimmt, ob eine Route mit der aktuellen Aktivität übereinstimmt. Der Handler führt Ihre Logik aus, wenn die Route übereinstimmt.

Registrieren Sie Routen, wenn Sie Ihren Agent konfigurieren. Folgendes kann abgeglichen werden:

• Eine Nachricht, die einen bestimmten Text enthält oder mit einem regulären Ausdruck übereinstimmt
• Jede Aktivität eines bestimmten Typs
• Unterhaltungslebenszyklus-Ereignisse (Mitglied hinzugefügt, Mitglied entfernt)
• Aktionen für adaptive Karten
• Benutzerdefinierte Bedingungen

Wenn eine Aktivität empfangen wird, prüft das System die Routen der Reihe nach, bis es eine Übereinstimmung findet. Standardmäßig wird nur eine Route ausgeführt.

Turn-Zustand

AgentApplication verwaltet den Turn-Zustand—ein strukturierter Speicher, der in Umfänge aufgeteilt ist:

Bereichstyp	Beschreibung des Dataflows
Unterhaltung	Geteilt von allen Nutzern in einer Unterhaltung, über mehrere Runden hinweg gespeichert
Benutzer	Gültig für einen einzelnen Nutzer über alle Unterhaltungen hinweg
Temp.	Nur aktueller Dialogschritt – wird nie beibehalten

Das System lädt den Status automatisch, bevor Ihre Handler ausgeführt werden, und speichert ihn danach automatisch.

Durchlaufkontext

Wenn ein Handler ausführt, erhält er einen Zug-Kontext. Der Dialogschrittkontext ist eine Momentaufnahme der aktuellen Aktivität, der Adapterverbindung und der Hilfsprogramme zum Senden von Antworten. Der Dialogschrittkontext ist Ihre Schnittstelle zur aktuellen Interaktion.

Middleware

AgentApplication unterstützt eine Middleware-Pipeline. Middleware ist eine Kette von Komponenten, die jeden Dialogschritt vor und nach der Ausführung der Handler verarbeiten. Middleware kann den Aktivitätsfluss inspizieren, transformieren oder kurzschließen. Häufige Anwendungen sind Protokollierung, Authentifizierungsprüfungen und Normalisierung von Anfragen.

Einen Agent erstellen

C#

Leiten Sie AgentApplication ab und registrieren Sie Ihre Handler im Konstruktor. Das Hosting-Framework injiziert AgentApplicationOptions automatisch.

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

Registrieren Sie Ihren Agent in 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

Instanziieren Sie AgentApplication, und registrieren Sie Handler für die Instanz mithilfe der Fluent-API. Um den Server zu starten, rufen Sie startServer aus dem Express-Hosting-Paket auf.

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)

Für manuelle Express-Einrichtung ohne 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

Instanziieren Sie AgentApplication mit einem Typparameter, und registrieren Sie Handler mithilfe von Decorators.

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)

Aktivitätshandler registrieren

Nachrichten verarbeiten

Nachrichten anhand des exakten Texts (groß-/kleinschreibungsunabhängig) abgleichen:

C#

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

Abgleichen von Nachrichten mithilfe eines regulären Ausdrucks:

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

Abgleichen von Nachrichten mithilfe eines regulären Ausdrucks:

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

Abgleichen von Nachrichten mithilfe eines regulären Ausdrucks:

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

Unterhaltungsaktualisierungen handhaben

Registrieren Sie Handler für Unterhaltungslebenszyklus-Ereignisse wie das Ein- oder Austreten von Mitgliedern.

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

Jede Aktivitätsart behandeln

Aktivitäten anhand ihrer Typ-Zeichenfolge abgleichen, um vollständige Kontrolle über das Routing zu erhalten.

C#

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

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

Verwenden Sie ActivityTypes-Konstanten statt fest kodierter Zeichenfolgen.

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

Bewertungsreihenfolge der Steuerrouten

Das System sortiert die Routen bei der Registrierung in eine feste Auswertungsreihenfolge, nicht zur Laufzeit. Die Sortierung verwendet zwei Ebenen:

1. Routentyp: Das System gruppiert Routen nach Typ und wertet immer höher priorisierte Typen vor niedriger priorisierten Typen aus, unabhängig vom Rang:

   Priorität	Routentyp
   1 (höchste)	Agentische Aufrufrouten
   2	Aufrufrouten (adaptive Kartenaktionen, OAuth-Rückrufe und andere zeitabhängige Aufrufe)
   3	Agentische Routen
   4 (niedrigste)	Alle anderen Routen

2. Rang: Innerhalb jeder Routentypgruppe ordnet das System die Routen nach ihrem Rangwert. Niedrigere numerische Werte werden zuerst geprüft.

Verwenden Sie RouteRank-Konstanten, um den Rang beim Registrieren eines Handlers festzulegen:

Konstante	Wert	Bedeutung
RouteRank.First	0	Ausgewertet vor allen anderen Routen in seiner Gruppe
RouteRank.Unspecified	32767	Standard, wenn kein Rang angegeben ist
RouteRank.Last	65535	Ausgewertet nach allen anderen Routen in der Gruppe

Standardmäßig endet die Verarbeitung bei der ersten passenden Route. Verwenden Sie RouteRank.Last als Auffangroute, die alles übernimmt, was nicht von einer spezifischeren Route abgedeckt wird.

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

Dialogschrittlebenszyklus-Hooks

Logik registrieren, die bei jedem Zug ausgeführt wird, vor oder nach dem Routenabgleich. Diese Hooks sind nützlich zur Protokollierung, Querschnittsthemen und Fehlerbehandlung.

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

Wenn OnBeforeTurn das Ergebnis false zurückgibt, wird der Dialogschritt abgebrochen, und es werden keine Routen ausgeführt. Wenn OnAfterTurnfalse zurückgibt, wird der Zug-Zustand nicht gespeichert.

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

Turn-Zustand verwenden

Der Agent lädt den Dialogschrittstatus automatisch, bevor die Handler ausgeführt werden, und speichert ihn danach. Das Turn State-Objekt, das an Ihre Handler übergeben wird, ermöglicht Ihnen den Zugriff auf die verschiedenen Umfänge, sodass Sie Daten lesen und schreiben können, die entweder über mehrere Turns hinweg bestehen bleiben oder nur für den aktuellen Turn verfügbar sind.

• Unterhaltungsbereich: Für Daten, die über alle Dialogschritte einer Unterhaltung verfügbar sind
• Benutzerumfang: Für Daten pro Benutzer
• Temp. Bereich: Für Daten, die nur während des aktuellen Dialogschritts existieren müssen

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

Anmerkung

Verwenden Sie MemoryStorage zur lokalen Entwicklung und Tests Für den Produktivbetrieb, insbesondere bei Bereitstellungen mit mehreren Instanzen, verwenden Sie einen persistenten Speicheranbieter wie Azure Cosmos DB oder Azure Blob Storage. Siehe Speicheranbieter in Ihrem Agent verwenden.

Nächste Schritte,

• Status im Agents-SDK verwalten
• Speicheranbieter in Ihrem Agent verwenden