AgentApplication i SDK til Microsoft 365-agenter

AgentApplication er den centrale kernekomponent i en agent bygget med Agents SDK. AgentApplication fungerer som indgangspunkt for al indkommende aktivitet, såsom beskeder fra brugere, begivenheder i samtalens livscyklus, interaktioner med adaptivt kort og OAuth-callbacks.

En agent er i sin kerne en AgentApplication. Du konfigurerer den med handlere, der beskriver, hvad din agent udfører. SDK'et sørger for routing, tilstandsstyring og den infrastruktur, der skal til for at agenten kan køre.

Sådan fungerer AgentApplication

Agentens livscyklus begynder, når en kanal (Microsoft Teams, en bot-tjeneste eller en brugerdefineret klient) leverer en aktivitet til agentens endpoint. AgentApplication er kernen i denne livscyklus:

Channel → Hosting layer → AgentApplication → Your handlers

Behandlingslagene i en agent bygget med Agents SDK fungerer som følger:

1. Hostinglaget modtager HTTP-forespørgslen og autentificerer den.
2. Den AgentApplication behandler den indkommende aktivitet gennem sin pipeline.
3. Dine handlere kaldes baseret på matchende ruter.

Din agent indlæser turntilstand, før dine handlere køres. Bagefter gemmer agenten turtilstanden.

Kernebegreber

Aktiviteter

Alt i Agents SDK håndteres som en aktivitet. En aktivitet er en struktureret besked, der repræsenterer noget, der er sket. En aktivitet har en type, såsom besked, begivenhed, invoke, samtaleopdatering og så videre. Den indeholder en nyttelast, der er relevant for den type. AgentApplication modtager aktiviteter og ruterer dem til den rette handler.

Ruter

En rute parrer en selector med en handler. Selektoren afgør, om en rute matcher den aktuelle aktivitet. Handleren kører din logik, når ruten matcher.

Registrer ruter, når du konfigurerer din agent. De kan matche:

• En besked, der indeholder specifik tekst eller matcher et regulært udtryk
• Enhver aktivitet af en bestemt type
• Begivenheder i samtalens livscyklus (medlem tilføjet, medlem fjernet)
• Adaptive korthandlinger
• Brugerdefinerede betingelser

Når en aktivitet ankommer, evaluerer systemet ruter i rækkefølge, indtil det finder et match. Som standard kører kun én rute.

Turn tilstand

AgentApplication administrerer _turn tilstand – struktureret lager, der er partitioneret i områder:

Områdetype	Beskrivelse
Samtale	Delt mellem alle brugere i en samtale, vedvarende mellem ture
Bruger	Afgrænset til en individuel bruger på tværs af alle samtaler
Temperatur	Kun aktuel tur – aldrig permanent

Systemet indlæser automatisk tilstand, før dine håndteringsfunktioner kører, og gemmer den automatisk bagefter.

Aktivér kontekst

Når en handler kører, modtager den en tur-kontekst. Turn context er et øjebliksbillede af den aktuelle aktivitet, adapterforbindelsen og funktioner til at sende svar. Turn context er dit interface til den aktuelle interaktion.

Middleware

AgentApplication understøtter en middlewarepipeline. Middleware er en kæde af komponenter, der behandler hver tur før og efter dine handlers kører. Middleware kan inspicere, transformere eller kortslutte aktivitetsflowet. Typiske anvendelser omfatter logning, autentificeringstjek og normalisering af forespørgsler.

Oprette en agent

C#

Subclass AgentApplication og registrer dine handlers i konstruktøren. Hosting-rammeværket injicerer automatisk 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);
    }
}

Registrer 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();

JavaScript

Instansier og registrer AgentApplication håndterere på instansen ved at bruge fluent API'en. For at starte serveren, kald startServer fra Express-hostingpakken.

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)

For manuel Express-opsætning uden 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

Instansier AgentApplication med en typeparameter og registrer håndterere ved hjælp af 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)

Registrer aktivitetshåndterere

Håndtering af beskeder

Matcher beskeder efter præcis tekst (ufølsom over for store og små bogstaver):

C#

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

Matcher beskeder med et regulært udtryk:

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

Matcher beskeder med et regulært udtryk:

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

Matcher beskeder med et regulært udtryk:

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

Håndter samtaleopdateringer

Registrer håndterere til samtalebegivenheder, såsom når medlemmer tilslutter sig eller forlader samtalen.

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

Håndter enhver aktivitetstype

Matche enhver aktivitet baseret på dens typebetegnelse for fuld kontrol over routing.

C#

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

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

Brug ActivityTypes konstanter i stedet for hardkodede strenge.

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

Kontrolruteevalueringsordre

Systemet sorterer ruter i en fast evalueringsrækkefølge, når du registrerer dem, ikke under kørsel. Sorteringen bruger to niveauer:

1. Rutetype: Systemet grupperer ruter efter type, og det evaluerer altid typer med højere prioritet før typer med lavere prioritet, uanset rang:

   Prioritet	Rutetype
   1 (højeste)	Agentbaseret aktiveringsruter
   2	Invoke-ruter (adaptivt kort-handlinger, OAuth-callbacks og andre tidssensitive invokeringer)
   3	Agentiske ruter
   4 (laveste)	Alle andre ruter

2. Rang: Inden for hver rutetypegruppe sorterer systemet ruterne efter deres rangværdi. Lavere numeriske værdier evalueres først.

Brug RouteRank konstanter til at angive rang ved registrering af en handler:

Konstant	Værdi	Betydning
RouteRank.First	0	Evalueres før alle andre ruter i sin gruppe
RouteRank.Unspecified	32767	Som standard, hvis der ikke er angivet nogen rang
RouteRank.Last	65535	Evalueret efter alle andre ruter i sin gruppe

Som standard stopper evalueringen ved den første matchende rute. Brug RouteRank.Last som en catch-all fallback, der håndterer alt, der ikke matches af en mere specifik rute.

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

Aktivér livscykluskroge

Registrer logik, der kører på hver tur, før eller efter rutematchning. Disse kroge er nyttige til logføring, tværgående anliggender og fejlhåndtering.

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

Når OnBeforeTurn returnerer false, afbrydes turen, og ingen ruter køres. Når OnAfterTurn returnerer false, bliver turtilstanden ikke gemt.

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

Brug turtilstand

Agenten indlæser automatisk turtilstand, før dine behandlere kører, og gemmer den bagefter. Turn state-objektet, som videresendes til dine handlere, giver dig adgang til de forskellige scopes, så du kan læse og skrive data, der bevares på tværs af ture eller kun er midlertidige for den aktuelle tur.

• Samtalescope: For data delt på tværs af alle ture i en samtale
• Brugerscope: For data pr. bruger
• Temp-omfang: For data, der kun skal findes under den aktuelle omgang

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

Bemærk!

Brug MemoryStorage til lokal udvikling og test. Til produktionsudrulninger, især udrulninger der kører på flere instanser, brug en lagringsudbyder med vedvarende lagring, såsom Azure Cosmos DB eller Azure Blob Storage. See Brug lagerudbydere i din agent.

Næste trin

• Administrer tilstand i Agents SDK
• Brug lagerudbydere i din agent