AgentApplication i SDK för Microsoft 365-agenter

AgentApplication är det centrala byggblocket för en agent som skapats med Agents SDK. AgentApplication är startpunkten för all inkommande aktivitet, inklusive meddelanden från användare, konversationslivscykelhändelser, adaptiva kortinteraktioner, OAuth-återanrop.

En agent är i grunden en AgentApplication. Du konfigurerar den med hanterare som beskriver vad din agent gör. SDK:et tar hand om routning, tillståndshantering och den infrastruktur som krävs för att köra den.

Så här fungerar AgentApplication

Varje agent har en livscykel som startar när en kanal (Microsoft Teams, en robottjänst eller en anpassad klient) levererar en aktivitet till agentens slutpunkt. AgentApplication sitter i mitten av livscykeln:

Channel → Hosting layer → AgentApplication → Your handlers

Skikten för bearbetning i en agent som skapats med Agents SDK fungerar på följande sätt:

Värdlagret tar emot HTTP-begäran och autentiserar den.
AgentApplication bearbetar den inkommande aktiviteten via sin pipelina.
Dina hanterare anropas baserat på matchande rutter.

Din agent läser in utförelsetillstånd innan dina hanterare körs. Därefter sparar agenten turtillståndet.

Grundläggande begrepp

Aktiviteter

Allt i Agents SDK flödar som en aktivitet. En aktivitet är ett strukturerat meddelande som representerar något som har hänt. En aktivitet har en typ, till exempel meddelande, händelse, invoke, conversationUpdate och så vidare. Den har en nyttolast som är relevant för denna typ. AgentApplication tar emot aktiviteter och dirigerar dem till rätt hanterare.

Routes

En rutt parkopplar en väljare med en hanterare. Väljaren avgör om en väg matchar den aktuella aktiviteten. Hanteraren kör din logik vid matchning av rutten.

Registrera vägar när du konfigurerar din agent. De kan matcha:

Ett meddelande som innehåller specifik text eller matchar ett reguljärt uttryck
Alla aktiviteter av en viss typ
Konversationslivscykelhändelser (medlem tillagd, medlem borttagen)
Anpassningsbara kortåtgärder
Anpassade villkor

När en aktivitet anländer utvärderar systemet rutter i ordning tills det hittar en matchning. Standardmässigt körs bara en rutt.

Svängtillstånd

AgentApplication hanterar _turn state—strukturerad lagring som är uppdelad i områden:

Omfattningstyp	beskrivning
Konversation	Delas mellan alla användare i en konversation, lagras mellan omgångar
Användare	Begränsad till en enskild användare i alla konversationer
Temp	Endast aktuell omgång – sparas inte

Systemet läser automatiskt in tillstånd innan dina hanterare körs och sparar det automatiskt efteråt.

Slå på kontext

När en hanterare körs får den en turkontext. Turn-kontext är en ögonblicksbild över den pågående aktiviteten, adapteranslutningen och verktyg för att skicka svar. Turkontexten är ditt gränssnitt till den aktuella interaktionen.

Middleware

AgentApplication stöder en pipeline för mellanprogram. Mellanprogram är en kedja av komponenter som bearbetar varje tur före och efter att dina hanterare har körts. Mellanprogram kan inspektera, transformera eller kortsluta aktivitetsflödet. Vanliga användningsområden är loggning, autentiseringskontroller och normalisering av begäranden.

Skapa en handläggare

Skapa en underklass och registrera dina hanterare i konstruktorn. Värdramverket infogar automatiskt 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);
    }
}

Registrera din agent i 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();

Instansiera AgentApplication och registrera hanterare på instansen med hjälp av fluent-API:et. Starta servern genom att anropa startServer från Express-värdpaketet.

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 manuell Express-installation utan 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)
    })
})

Instansiera AgentApplication med en typparameter och registrera hanterare med hjälp av dekoratörer.

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)

Registrera aktivitetshanterare

Hantera meddelanden

Matcha meddelanden med exakt text (skiftlägesokänsligt):

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

Matcha meddelanden med ett reguljärt uttryck:

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

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

Matcha meddelanden med ett reguljärt uttryck:

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

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

Matcha meddelanden med ett reguljärt uttryck:

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

Hantera konversationsuppdateringar

Registrera hanterare för konversationslivscykelhändelser, till exempel medlemmar som ansluter till eller lämnar.

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

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

@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

Hantera alla aktivitetstyper

Matcha alla aktiviteter med dess typsträng för fullständig kontroll över routning.

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

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

Använd ActivityTypes konstanter i stället för hårdkodade strängar.

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

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

@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

Kontrollera utvärderingsordningen för rutter

Systemet sorterar vägar i en fast utvärderingsordning när du registrerar dem, inte vid körning. Sorteringen använder två nivåer:

Vägtyp: Systemet grupperar vägar efter typ och utvärderar alltid typer med högre prioritet före typer med lägre prioritet, oavsett rangordning:

Prioritet	Routningstyp
1 (högsta)	Agentiska anropar vägar
2	Anropa rutter (anpassningsbara kortåtgärder, OAuth-återanrop och andra tidskänsliga anrop)
3	Agentiska vägar
4 (lägst)	Alla andra vägar

Rangordning: Inom varje vägtypsgrupp beställer systemet vägar efter deras rankningsvärde. Lägre numeriska värden utvärderas först.

Använd RouteRank konstanter för att ange rangordning när du registrerar en hanterare:

Konstant	Value	Betydelse
`RouteRank.First`	`0`	Utvärderas före alla andra vägar i gruppen
`RouteRank.Unspecified`	`32767`	Standard när ingen rangordning har angetts
`RouteRank.Last`	`65535`	Utvärderas efter alla andra rutter i gruppen

Som standardläge avbryts utvärderingen vid den första matchande rutan. Använd RouteRank.Last som en "catch-all"-reserv som hanterar allt som inte matchas av en mer specifik rutt.

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

// 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)

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

Aktivera livscykelkrokar

Registrera logik som körs på varje tur, före eller efter vägmatchning. Dessa krokar är användbara för loggning, övergripande problem och felhantering.

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

När OnBeforeTurn returnerar false, avbryts svängen och inga rutter körs. När OnAfterTurn returnerar false, sparas inte svängtillståndet.

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

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

Använda rotationstillstånd

Agenten läser automatiskt in växlingsstatus före dina hanterare körs och sparar det efteråt. Turtillståndsobjektet som skickas till dina hanterare ger dig åtkomst till de olika omfången så att du kan läsa och skriva data som bevaras över svängar eller är tillfälliga för den aktuella svängen:

Konversationsomfång: För data som delas över alla rundor i en konversation
Användaromfång: För data per användare
Temp-omfång: För data som bara behöver finnas under den aktuella svängen

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

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

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

Anmärkning

Använd MemoryStorage för lokal utveckling och testning. För produktionsdistributioner, särskilt distributioner som körs på flera instanser, använder du en beständig lagringsprovider, till exempel Azure Cosmos DB eller Azure Blob Storage. Se Använd lagringsproviders i din agent.

Nästa steg

Hantera tillstånd i Agents SDK
Använd lagringsproviders i din agent

Feedback

Var den här sidan till hjälp?

Last updated on 2026-04-29

AgentApplication i SDK för Microsoft 365-agenter

Så här fungerar AgentApplication

Grundläggande begrepp

Aktiviteter

Routes

Svängtillstånd

Slå på kontext

Middleware

Skapa en handläggare

Registrera aktivitetshanterare

Hantera meddelanden

Hantera konversationsuppdateringar

Hantera alla aktivitetstyper

Kontrollera utvärderingsordningen för rutter

Aktivera livscykelkrokar

Använda rotationstillstånd

Nästa steg

Feedback

Ytterligare resurser