AgentApplication v sadě SDK pro agenty Microsoft 365

AgentApplication je ústředním stavebním blokem agenta vytvořeného pomocí Agents SDK. AgentApplication je vstupním bodem pro veškerou příchozí aktivitu, včetně zpráv od uživatelů, událostí životního cyklu konverzace, interakcí s adaptivními kartami a OAuth callbacků.

Agent je ve svém jádru AgentApplication. Konfigurujete ho pomocí obslužných rutin, které popisují, co váš agent dělá. SDK se stará o směrování, správu stavu a infrastrukturu potřebnou k provozu agenta.

Jak AgentApplication funguje

Každý agent má životní cyklus, který začíná tím, že kanál (Microsoft Teams, Bot Service nebo vlastní klient) doručí aktivitu na koncový bod vašeho agenta. AgentApplication je středobodem tohoto životního cyklu:

Channel → Hosting layer → AgentApplication → Your handlers

Vrstvy zpracování u agenta vytvořeného pomocí Agents SDK fungují následovně:

1. Hostingová vrstva přijímá požadavek HTTP a ověří ho.
2. AgentApplication zpracovává příchozí aktivitu prostřednictvím svého kanálu.
3. Vaše obslužné rutiny se volají na základě odpovídajících tras.

Agent načte stav tahu před spuštěním obslužných rutin. Potom agent uloží stav tahu.

Klíčové koncepty

Aktivity

Všechno v Sadě SDK pro agenty funguje jako aktivita. Aktivita je strukturovaná zpráva, která představuje něco, co se stalo. Aktivita má typ, například message, event, invoke, conversationUpdate a podobně. Nese datovou část relevantní pro tento typ. AgentApplication přijímá aktivity a směruje je ke správné obslužné rutině.

Trasy

Trasa spojuje selektor s obslužnou rutinou. Selektor určuje, zda trasa odpovídá aktuální aktivitě. Obslužná rutina spustí logiku, když se trasa shoduje.

Registrujte trasy při konfiguraci agenta. Mohou se shodovat:

• Zpráva obsahující specifický text nebo odpovídající regulárnímu výrazu
• Jakákoli aktivita daného typu
• Události životního cyklu konverzace (přidání člena, odebrání člena)
• Akce adaptivní karty
• Vlastní podmínky

Když aktivita dorazí, systém vyhodnocuje trasy v pořadí, dokud nenajde shodu. Ve výchozím nastavení běží pouze jedna trasa.

Stav obratu

AgentApplication spravuje stav tahu – strukturované úložiště rozdělené do oborů:

Typ oblasti	Popis
Konverzace	Sdílené mezi všemi uživateli v konverzaci, uchované mezi jednotlivými kroky dialogu.
Uživatelská	Vázáno na jednotlivého uživatele napříč všemi konverzacemi
Dočasné	Pouze aktuální tah – nikdy se neuchovávalo

Systém automaticky načte stav před spuštěním vašich obslužných rutin a po jejich ukončení jej automaticky uloží.

Kontext obratu

Když se obslužná rutina spustí, obdrží kontext tahu. Kontext tahu je snímek aktuální aktivity, připojení adaptéru a nástrojů pro odesílání odpovědí. Kontext tahu je vaše rozhraní pro aktuální interakci.

Middleware

AgentApplication podporuje kanál middlewaru. Middleware je řada komponent, které zpracovávají každou interakci před a po spuštění vašich obslužných rutin. Middleware může kontrolovat, transformovat nebo zkrátit tok aktivit. Mezi běžné způsoby využití patří protokolování, ověřování a normalizace požadavků.

Vytvořit agenta

C#

Vytvořte podtřídu AgentApplication a zaregistrujte obslužné rutiny v konstruktoru. Hostitelský framework automaticky injektuje 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);
    }
}

Zaregistrujte svého agenta v 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

Vytvořte instanci AgentApplication a zaregistrujte na této instanci obslužné rutiny pomocí fluentního API. Pro spuštění serveru volejte startServer z hostingového balíčku 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)

Pro ruční nastavení Expressu 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

Vytvořte instanci AgentApplication s typovým parametrem a zaregistrujte obslužné rutiny pomocí dekorátorů.

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)

Registrujte obslužné rutiny aktivit

Zpracování zpráv

Porovnávejte zprávy podle přesného textu (nerozlišuje se velká a malá písmena):

C#

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

Párujte zprávy pomocí regulárního výrazu:

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

Párujte zprávy pomocí regulárního výrazu:

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

Párujte zprávy pomocí regulárního výrazu:

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

Zpracování aktualizací konverzací

Registrujte obslužné rutiny pro události životního cyklu konverzace, jako je připojení nebo odchod členů.

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

Zpracujte jakýkoli typ aktivity

Porovná jakoukoli aktivitu podle řetězce typu pro úplnou kontrolu nad směrováním.

C#

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

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

Používejte konstanty ActivityTypes místo pevně zakódovaných řetězců.

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

Řízení pořadí vyhodnocování tras

Systém seřadí trasy do pevného pořadí vyhodnocení již při jejich registraci, nikoli až za běhu. Třídění používá dvě úrovně:

1. Typ trasy: Systém seskupuje trasy podle typu a vždy vyhodnocuje typy s vyšší prioritou před typy s nižší prioritou, bez ohledu na hodnocení:

   Priorita	Typ trasy
   1 (nejvyšší)	Trasy volání agentů
   2	Volání tras (akce adaptivní karty, zpětné volání OAuth a jiná volání citlivá na čas)
   3	Agentní trasy
   4 (nejnižší)	Všechny trasy

2. Pořadí: V rámci každé skupiny typů tras systém řadí trasy podle jejich hodnoty pořadí. Trasy s nižší číselnou hodnotou pořadí jsou vyhodnoceny jako první.

Při registraci obslužné rutiny použijte konstanty RouteRank k nastavení pořadí:

Konstanta	Hodnota	Význam
RouteRank.First	0	Vyhodnoceno před všemi ostatními trasami ve skupině
RouteRank.Unspecified	32767	Výchozí hodnota, pokud není pořadí specifikováno
RouteRank.Last	65535	Vyhodnoceno po všech ostatních trasách ve skupině

Ve výchozím nastavení se hodnocení zastaví na první shodné trase. Použijte RouteRank.Last pro univerzální záložní řešení, které zpracuje cokoli, co neodpovídá specifičtější trase.

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

Háčky životního cyklu tahu

Registrujte kód, který se spouští při každém kroku, před nebo po vyhodnocení trasy. Tyto háčky jsou užitečné pro protokolování, průřezové zájmy a zpracování chyb.

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

Když OnBeforeTurn vrátí false, tah se přeruší a nespustí se žádné trasy. Pokud OnAfterTurn vrátí false, stav tahu se neuloží.

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

Použít stav tahu

Agent automaticky načte stav tahu před spuštěním vašich obslužných rutin a po jejich ukončení jej uloží. Objekt stavu tahu, který se předává vašim obslužným rutinám, vám umožňuje přístup k různým oblastem, takže můžete číst a zapisovat data, která přetrvávají i mezi tahy, nebo která jsou dočasná a platí pouze pro aktuální tah:

• Rozsah konverzace: Pro data sdílená ve všech krocích konverzace
• Uživatelský rozsah: Pro data na uživatele
• Dočasný rozsah: Pro data, která musí existovat jen během aktuálního tahu

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

Poznámka

Použít MemoryStorage pro místní vývoj a testování. Pro produkční nasazení, zejména při nasazení na více instancích, použijte poskytovatele trvalého úložiště, například Azure Cosmos DB nebo Azure Blob Storage. Viz Použití poskytovatelů úložiště v agentovi.

Další kroky

• Správa stavu v sadě SDK pro agenty
• Použití poskytovatelů úložiště v agentovi