AgentApplication v sadě SDK pro agenty Microsoft 365

AgentApplication je centrální stavební blok agenta sestaveného pomocí sady Agents SDK. AgentApplication je vstupním bodem pro všechny příchozí aktivity, včetně zpráv od uživatelů, událostí životního cyklu konverzace, interakcí adaptivních karet a callbacků OAuth.

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

Jak funguje AgentApplication

Každý agent má životní cyklus, který se spustí, když kanál (Microsoft Teams, služba robota nebo vlastní klient) doručí aktivitu do koncového bodu vašeho agenta. AgentApplication se nachází uprostřed tohoto životního cyklu:

Channel → Hosting layer → AgentApplication → Your handlers

Vrstvy zpracování v agentu vytvořeném pomocí sady Agents SDK fungují takto:

1. Vrstva hostování obdrží 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 představující něco, co se stalo. Aktivita má typ, například zprávu, událost, vyvolání, conversationUpdate atd. Nese užitečné zatížení, které je pro daný typ relevantní. AgentApplication přijímá aktivity a směruje je do správné obslužné rutiny.

Postupy

Směrovač spáruje selektor s handlerem. Selektor určuje, jestli trasa odpovídá aktuální aktivitě. Obslužná rutina spustí logiku, když se trasa shoduje.

Při konfiguraci agenta zaregistrujte trasy. Můžou se shodovat:

• Zpráva obsahující konkrétní 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.

Změnit stav

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

Typ oboru	Description
Konverzace	Sdílené mezi všemi uživateli v konverzaci, uchované mezi jednotlivými kroky dialogu.
Uživatel	Vymezený na jednotlivého uživatele ve všech konverzacích
Dočasné	Pouze aktuální tah – nikdy se neuchovávalo

Systém automaticky načte stav před spuštěním obslužných rutin a automaticky ho uloží.

Otočení kontextu

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 řetězec komponent, které zpracovávají každou akci před a po spuštění obslužných rutin. Middleware může zkontrolovat, transformovat nebo zkratovat tok aktivity. Mezi běžné použití patří protokolování, kontroly ověřování a normalizace požadavků.

Vytvořit agenta

C#

Vytvořte podtřídu AgentApplication a zaregistrujte obslužné rutiny v konstruktoru. Hostitelská architektura automaticky vloží 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 obslužné rutiny na této instanci za použití rozhraní fluent API. Pokud chcete spustit server, zavolejte startServer z hostitelské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í expresní instalaci 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

Vyřizování zpráv

Porovná zprávy přesným textem (nerozlišuje velká a malá písmena):

C#

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

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

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

Porovná 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í

Zaregistrujte obslužné rutiny pro události životního cyklu konverzace, jako jsou například členové, kteří se připojují nebo odcházejí.

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

Zvládnutí jakéhokoliv typu 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
});

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

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

Ovládání pořadí vyhodnocení trasy

Systém seřadí trasy do pevného pořadí vyhodnocení, když je zaregistrujete, ne za běhu. Řazení 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 pořadí:

   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 ostatní trasy

2. Pořadí: V rámci každé skupiny typů tras systém objednává trasy podle jejich hodnoty pořadí. Nižší číselné hodnoty se vyhodnocují jako první.

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

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

Ve výchozím nastavení se vyhodnocení zastaví na první odpovídající 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

Zaregistrujte logiku, která se spouští při každém průběhu, před nebo po porovnávání tras. 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žij stav otočení

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 obratu předaný vašim handlerům poskytuje přístup k různým oborům, abyste mohli číst a zapisovat data, která se zachovají napříč obraty nebo jsou dočasná pro aktuální obrat:

• Rozsah konverzace: Pro data sdílená napříč všemi částmi konverzace.
• Obor uživatele: Pro uživatelská data
• Dočasný rozsah: Pro data, která musí existovat pouze během aktuálního turnu

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žívá se MemoryStorage pro místní vývoj a testování. Pro produkční nasazení, zejména nasazení spuštěná na více instancích, použijte trvalého poskytovatele úložiště, jako je Azure Cosmos DB nebo Azure Blob Storage. Viz Použití poskytovatelů úložiště ve vašem agentu.

Další kroky

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