AgentApplication i SDK för Microsoft 365-agenter

AgentApplication är den centrala byggblocket i en agent byggd med Agents SDK. AgentApplication är startpunkten för all inkommande aktivitet, inklusive meddelanden från användare, livscykelhändelser i konversationer, interaktioner med adaptiva kort, OAuth-callbacks.

En agent är i sin kärna en AgentApplication. Du konfigurerar det med hanterare som beskriver vad din agent gör. SDK:n hanterar routing, tillståndshantering och den infrastruktur som krävs för att driva agenten.

Hur AgentApplication fungerar

Varje agent har en livscykel som börjar när en kanal (Microsoft Teams, en bot service eller en anpassad klient) levererar en aktivitet till agentens slutpunkt. AgentApplication utgör kärnan i den livscykeln:

Channel → Hosting layer → AgentApplication → Your handlers

Bearbetningslagren i en agent som byggs med Agents SDK fungerar enligt följande:

Hostinglagret tar emot HTTP-förfrågan och autentiserar den.
AgentApplication bearbetar den inkommande aktiviteten genom sin pipeline.
Dina hanterare anropas baserat på matchande rutter.

Din agent läser in omgångstillstånd innan dina hanterare körs. Därefter sparar agenten omgångstillstånd.

Huvudkoncept

Aktiviteter

Allt i Agents SDK flyter som en aktivitet. En aktivitet är ett strukturerat meddelande som representerar en händelse. En aktivitet har en typ, till exempel meddelande, händelse, anrop, conversationUpdate och så vidare. Den bär en nyttolast som är relevant för den typen. AgentApplication tar emot aktiviteter och vidarebefordrar dem till rätt hanterare.

Flöden

En rutt parar ihop en selector med en handler. Väljare avgör om en route matchar den aktuella aktiviteten. Väljaren kör din logik när rutten stämmer.

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

Ett meddelande som innehåller specifik text eller matchar ett reguljärt uttryck
Vilken aktivitet som helst av en viss typ
Konversationslivscykelhändelser (medlem tillagd, medlem borttagen)
Åtgärder för adaptivt kort
Anpassade villkor

När en aktivitet anländer utvärderar systemet routes i ordning tills det hittar en match. Som standard körs endast en route.

Omgångstillstånd

AgentApplication hanterar _turn state—strukturerad lagring uppdelad i omfattningar:

Typer av omfattning	beskrivning
Konversation	Delas mellan alla användare i en konversation, sparas över turer
Användare	Associerat med en enskild användare över alla konversationer
Tillfällig	Endast aktuell omgång – sparas inte

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

Omgångskontext

När en hanterare körs får den en omgångskontext. Omgångskontext är en ögonblicksbild över den pågående aktiviteten, adapteranslutningen och verktyg för att skicka svar. Omgångskontexten är ditt gränssnitt till den aktuella interaktionen.

Mellanprogram

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

Skapa en agent

Skapa en underklass av AgentApplication och registrera dina hanterare i konstruktor. Värdramverket injicerar AgentApplicationOptions automatiskt.

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 agenten 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. För att starta servern, anropa startServer från Express-hostingpaketet.

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-konfiguration 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 dekoratorer.

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änslig):

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 livscykelhändelser i konversationer, såsom när medlemmar går med 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 typer av aktiviteter

Matcha vilken aktivitet som helst efter dess typsträng för fullständig kontroll över routing.

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

Hantera utvärderingsordning för rutter

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

Cirkuleringstyp: Systemet grupperar rutter efter typ och utvärderar alltid typer med högre prioritet före typer med lägre prioritet, oavsett rang:

Prioritet	Cirkuleringstyp
1 (högsta)	Agentiska anropsvägar
2	Anropa rutter (adaptiva kortåtgärder, OAuth-motringningar och andra tidskänsliga anrop)
3	Agentrutter
4 (lägst)	Alla andra rutter

Rang: Inom varje rutt-typgrupp ordnar systemet rutter efter deras rangvärde. Lägre numeriska värden utvärderas först.

Använd RouteRank konstanter för att ange rang när du registrerar en handler:

Konstant	Value	Betydelse
`RouteRank.First`	`0`	Utvärderas före alla andra rutter i sin grupp
`RouteRank.Unspecified`	`32767`	Förvalt när ingen rang anges
`RouteRank.Last`	`65535`	Utvärderas efter alla andra rutter i sin grupp

Som standardläge avbryts utvärderingen vid den första matchande rutten. Använd RouteRank.Last för en catch-all fallback 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.")

Omgångens livscykelkrokar

Registerlogik som körs på varje omgång, före eller efter ruttmatchning. 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 omgången och inga rutter körs. När OnAfterTurn återvänder falsesparas inte omgångstillstå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änd omgångstillstånd

Agenten läser automatiskt in omgångstillstånd innan dina hanterare körs och sparar det efteråt. Omgångstillståndsobjektet som skickas till dina hanterare ger dig tillgång till de olika omfången så att du kan läsa och skriva data som består över omgångar eller är tillfällig för den aktuella omgången:

Konversationsomfång: För data som delas över alla turer i en konversation
Användaromfång: För data per användare
Tillfälligt omfång: För data som bara behöver finnas under den aktuella omgå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}")

Kommentar

Använd MemoryStorage för lokal utveckling och testning. För produktionsinstallationer, särskilt sådana som körs på flera instanser, använd en persistent lagringsleverantör som Azure Cosmos DB eller Azure Blob Storage. Se Använda lagringsleverantörer i din agent.

Nästa steg

Feedback

Var den här sidan till hjälp?

Last updated on 2026-07-31

AgentApplication i SDK för Microsoft 365-agenter

Hur AgentApplication fungerar

Huvudkoncept

Aktiviteter

Flöden

Omgångstillstånd

Omgångskontext

Mellanprogram

Skapa en agent

Registrera aktivitetshanterare

Hantera meddelanden

Hantera konversationsuppdateringar

Hantera alla typer av aktiviteter

Hantera utvärderingsordning för rutter

Omgångens livscykelkrokar

Använd omgångstillstånd

Nästa steg

Feedback

Ytterligare resurser