AgentApplication Microsoft 365 -agenttien SDK:ssa

AgentApplication on agentin keskeinen rakenneosa, joka on luotu agenttien SDK:lla. AgentApplication toimii kaikkien saapuvien toimintojen aloituskohtana, mukaan lukien viestit käyttäjiltä, keskustelun elinkaaren tapahtumat, mukautuvan kortin vuorovaikutukset ja OAuth-takaisinsoitot.

Agentti on pohjimmiltaan AgentApplication. Se määritetään käsittelijöillä, jotka kuvailevat agentin toiminnan. SDK huolehtii reitityksestä, tilanhallinnasta ja suorituksessa tarvittavasta infrastruktuurista.

AgentApplicationin toiminta

Jokaisella agentilla on elinkaari, joka alkaa, kun kanava (Microsoft Teams, bottipalvelu tai mukautettu asiakasohjelma) toimittaa aktiviteetin agentin päätepisteelle. AgentApplication sijaitsee tämän elinkaaren ytimessä:

Channel → Hosting layer → AgentApplication → Your handlers

Agenttien SDK:lla luodun agentin käsittelykerrokset toimivat seuraavasti:

1. Isännöintikerros vastaanottaa HTTP-pyynnön ja todentaa sen.
2. AgentApplication käsittelee saapuvan aktiviteetin putkensa kautta.
3. Käsittelijät kutsutaan reittien perusteella.

Agentti lataa tilan ennen käsittelijöiden suoritusta. Tämän jälkeen agentti tallentaa vuorotilan.

Keskeiset konseptit

Toiminnat

Agenttien SDK:ssa kaikki tapahtuu aktiviteettina. Aktiviteetti on jäsennelty viesti, joka edustaa jotain tapahtunutta. Aktiviteetilla on tyyppi, kuten viesti, tapahtuma, kutsu tai conversationUpdate. Se sisältää kyseiselle tyypille olennaiset tiedot. AgentApplication vastaanottaa aktiviteetteja ja ohjaa ne oikealle käsittelijälle.

Reititykset

Reitti yhdistää valitsimen ja käsittelijän. Valitsija määrittää, vastaako reitti nykyistä aktiviteettia. Käsittelijä suorittaa logiikan, kun vastaava reitti löytyy.

Rekisteröi reitit, kun määrität agentin. Ne voivat vastata

• viestiä, joka sisältää tietyn tekstin tai säännöllistä lauseketta
• mitä tahansa tietyn tyyppistä aktiviteettia
• keskustelun elinkaaritapahtumia (jäsen lisätty, jäsen poistettu)
• mukautuvan kortin toimintoja
• Mukautetut ehdot

Kun aktiviteetti saapuu, järjestelmä arvioi reitit järjestyksessä, kunnes se löytää sopivan reitin. Oletuksena suoritetaan vain yksi reitti.

Vuorotila

AgentApplication hallitsee vuorotilaa, joka on rakenteellinen tallennus, joka on jaettu laajuuksiin seuraavasti:

Laajuustyypit	Description
Keskustelu	Jaettu kaikille käyttäjille keskustelussa, tallennetaan vuorojen välillä
User	Rajattu yksittäiselle käyttäjälle kaikissa keskusteluissa
Lämpötila	Vain nykyinen vuoro – ei koskaan jatkuva

Järjestelmä lataa tilan automaattisesti ennen kuin käsittelijät suoritetaan ja tallentaa sen automaattisesti niiden jälkeen.

Vuorokonteksti

Kun käsittelijä suoritetaan, se saa vuoron kontekstin. Vuorokonteksti on nykyisen aktiviteetin, sovitinyhteyden ja vastausten lähettämiseen käytettävien työkalujen tilannekuva. Vuorokonteksti on liittymä nykyiseen vuorovaikutukseen.

Väliohjelmistot

AgentApplication tukee väliohjelmiston putkea. Väliohjelmisto on komponenttiketju, joka käsittelee jokaisen vuoron ennen ja jälkeen käsittelijöiden suorittamista. Väliohjelmisto voi tarkastaa, muuntaa tai katkaista aktiviteettityönkulun. Yleisiä käyttötarkoituksia ovat lokiinkirjaus, todennustarkistukset ja pyyntöjen normalisointi.

Agentin luominen

C#

Periytä AgentApplication ja rekisteröi käsittelijät konstruktorissa. Isännöintikehys lisää kohteen AgentApplicationOptions automaattisesti.

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

Rekisteröi agentti kohteessa 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

Alusta AgentApplication ja rekisteröi esiintymän käsittelijät käyttämällä sujuvaa ohjelmointirajapintaa. Käynnistä palvelin kutsumalla kohdetta startServer Express-isännöintipaketin avulla.

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)

Manuaalinen Express-asennukseen ilman kohdetta 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

Luo ilmentymä kohteesta AgentApplication tyyppiparametrilla ja rekisteröi käsittelijät koristimen avulla.

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)

Aktiviteetin käsittelijöiden rekisteröiminen

Viestien käsitteleminen

Määritä viestien vastaavuus tarkalla tekstillä (kirjainkoolla ei ole merkitystä):

C#

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

Määritä viestien vastaavuus säännöllisellä lausekkeella:

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

Määritä viestien vastaavuus säännöllisellä lausekkeella:

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

Määritä viestien vastaavuus säännöllisellä lausekkeella:

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

Keskustelupäivitysten käsitteleminen

Rekisteröi käsittelijät keskustelun elinkaaren tapahtumiin, kuten jäsenten liittyminen tai poistuminen.

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

Minkä tahansa aktiviteettityypin käsitteleminen

Voit määrittää minkä tahansa aktiviteetin vastaavuuden sen tyypin merkkijonon perusteella saadaksesi täydellisen hallinnan reitityksestä.

C#

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

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

Käytä ActivityTypes-vakioita pysyväiskoodattujen merkkijonojen sijaan.

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

Reittien arviointijärjestyksen hallinta

Järjestelmä järjestää reitit kiinteään arviointijärjestykseen rekisteröinnin yhteydessä, ei suorituspalvelun aikana. Lajittelussa käytetään kahta seuraavaa tasoa:

1. Reittityyppi: Järjestelmä ryhmittelee reitit tyypin mukaan ja arvioi aina korkeamman prioriteetin tyypit ennen matalamman prioriteetin tyyppejä seuraavasti arvosta riippumatta:

   Prioriteetti	Reittityyppi
   1 (korkein)	Agentin käynnistämät reitit
   2	Käynnistä reitit (mukautuvan kortin toiminnot, OAuthin takaisinkutsut ja muut aikakriittiset kutsut)
   3	Agenttien reitit
   4 (pienin)	Kaikki muut reitit

2. Luokitus: Kussakin reittityyppiryhmässä järjestelmä järjestää reitit niiden luokitusarvon perusteella. Alemmat numeeriset arvot arvioidaan ensin.

Käytä RouteRank-vakioita määrittääksesi luokittelun käsittelijän rekisteröimisen yhteydessä seuraavasti:

Vakio	Arvo	Merkitys
RouteRank.First	0	Arvioitu ennen kaikkia muita ryhmän reittejä
RouteRank.Unspecified	32767	Oletusarvo, kun luokitusta ei ole määritelty
RouteRank.Last	65535	Arvioitu kaikkien muiden ryhmän reittien jälkeen

Oletusarvoisesti arviointi pysähtyy ensimmäiselle yhteensopivalle reitille. Käytä kohdetta RouteRank.Last kaikkien varatoimintona, joka käsittelee kaikki tapaukset, jotka eivät vastanneet tarkempaa reittiä.

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

Vuoron elinkaaren koukut

Rekisteröi logiikka, joka suoritetaan jokaisella vuorolla ennen tai jälkeen reittien täsmäytyksen. Näistä koukuista on hyötyä lokiinkirjaamisessa sekä ongelmien ja virheiden käsittelyssä.

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

Kun OnBeforeTurn palauttaa arvon false, vuoro keskeytetään eikä reittejä käsitellä. Kun OnAfterTurn palauttaa arvon false, vuorotilaa ei tallenneta.

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

Vuorotilan käyttäminen

Agentti lataa vuorotilan automaattisesti. ennen kuin käsittelijät suoritetaan ja tallentaa sen niiden jälkeen. Vuorotila-objekti, joka välitetään käsittelijöille, mahdollistaa eri laajuuksien käyttöoikeuden. Voit lukea ja kirjoittaa tietoja, jotka säilyvät vuorojen välillä tai ovat tilapäisiä vain kyseisen vuoron ajan.

• Keskustelun laajuus: Tiedot, joka jaetaan kaikissa keskustelun vuoroissa
• Käyttäjän laajuus: Käyttäjäkohtaiset tiedot
• Väliaikainen laajuus: Tiedot, jotka tarvitaan vain nykyisen vuoron aikana

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

Muistiinpano

Käytä kohdetta MemoryStorage paikalliseen kehitykseen ja testaukseen. Tuotantoympäristöissä, erityisesti käyttöönotoissa, jotka suoritetaan useassa esiintymässä, käytetään pysyvää tallennuspalvelua, kuten Azure Cosmos DB tai Azure Blob -säilö. Katso Tallennuspalveluiden käyttö agentissa.

Seuraavat vaiheet

• Tilan hallinta agenttien SDK:ssa
• Tallennuspalveluiden käyttö agentissa