AgentApplication ב- Microsoft 365 Agents SDK

AgentApplication הוא אבן הבניין המרכזית של סוכן שנבנה עם ערכת הפיתוח של הסוכנים (Agents SDK). AgentApplication היא נקודת הכניסה עבור כל הפעילות הנכנסת, כולל הודעות ממשתמשים, אירועי מחזור חיי שיחה, אינטראקציות כרטיס מסתגלות, התקשרויות חזרה של OAuth.

סוכן הוא, בליבתו, AgentApplication. קבע את תצורתו עם מטפלים שמתארים מה הסוכן שלך עושה. ה- SDK דואג לניתוב, לניהול מצבים ולתשתית הנדרשת להפעלתו.

כיצד פועל AgentApplication

לכל סוכן יש מחזור חיים המתחילה כאשר ערוץ (Microsoft Teams, שירות Bot או לקוח מותאם אישית) מספק פעילות לנקודות הקצה של הסוכן שלך. AgentApplication נמצא במרכז מחזור חיים זה:

Channel → Hosting layer → AgentApplication → Your handlers

שכבות העיבוד בסוכן שנבנה באמצעות ה- SDK Agents פועלות באופן הבא:

1. שכבת האירוח מקבלת את בקשת ה- HTTP ו מאמתת אותה.
2. AgentApplication מעבד את הפעילות הנכנסת דרך הצינור שלו.
3. המטפלים שלכם נקראים על סמך נתיבים תואמים.

הסוכן שלך טוען מצב הפעלה לפני שהמטפלים שלך פועלים. לאחר מכן, הסוכן שומר את מצב ההפעלה.

מושגים עיקריים

פעילויות

הכול בערכת ה-SDK של סוכנים זורם כפעילות. פעילות היא הודעה מובנית המייצגת משהו שקרה. לפעילות יש סוג, כגון הודעה, אירוע, הפעלה, conversationUpdate וכן הלאה. היא נושאת מטען הרלוונטי לסוג זה. AgentApplication מקבל פעילויות ומנתב אותן למטפל הנכון.

נתיבי

נתיב מצמיד בורר למטפל. בורר קובע אם נתיב תואם לפעילות הנוכחית. המטפל מפעיל את הלוגיקה שלך כאשר הנתיב תואם.

רשום נתיבים בעת קביעת התצורה של הסוכן שלך. הם יכולים לבצע התאמה

• הודעה המכילה טקסט ספציפי או תואמת לביטוי רגיל
• כל פעילות מסוג נתון
• אירועי מחזור חיי שיחה (חבר נוסף, חבר הוסר)
• פעולות כרטיס מסתגל
• תנאים מותאמים אישית

כאשר מגיעה פעילות, המערכת מעריכה מסלולים לפי הסדר עד שהיא מוצאת התאמה. כברירת מחדל, רק נתיב אחד פועל.

מצב סיבוב

AgentApplication מנהלת את מצב _turn - אחסון מובנה המחולק לטווחים:

סוג היקף	תיאור
שיחה	משותף לכל המשתמשים בשיחה, נשמר בין פניות
משתמש	מותאם למשתמש יחיד בכל השיחות
Temp	הפנייה הנוכחית בלבד - לא נשמרת לעולם

המערכת טוענת באופן אוטומטי את המצב לפני שההידרים שלך פועלים ושומרת אותו באופן אוטומטי לאחר מכן.

הקשר פנייה

כאשר מטפל פועל, הוא מקבל הקשר פנייה. הקשר פנייה הוא תמונת מצב של הפעילות הנוכחית, חיבור המתאם וכלי שירות לשליחת תגובות. הקשר הפנייה הוא הממשק שלכם לאינטראקציה הנוכחית.

תוכנת ביניים

AgentApplication תומך בצינור middleware. תוכנת ביניים היא שרשרת של רכיבים שמעבדים כל סיבוב לפני ואחרי שהמטפלים שלך פועלים. תוכנת ביניים יכולה לבדוק, להמיר או לקצר את זרימת הפעילות. שימושים נפוצים כוללים רישום, בדיקת אימות ורגילת בקשות.

יצירת סוכן

C#‎

תת-מחלקה AgentApplication ורשום את המטפלים שלך בקונסטרקטור. מסגרת האירוח מזריקה באופן אוטומטי 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);
    }
}

רשום את הסוכן שלך ב: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

יצירת מופעים AgentApplication ורישום של מטפלים במופע באמצעות ה- API Fluent. כדי להפעיל את השרת, התקשר מחבילה startServer האירוח של 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)

להגדרה ידנית של Express ללא 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)
    })
})

פיתון

יצירת מופע של AgentApplication עם פרמטר סוג ורישום מטפלים באמצעות דקורטורים.

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)

רשום מטפלים בפעילות

טיפול בהודעות

התאם הודעות לפי טקסט מדויק (לא תלוי רישיות):

C#‎

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

התאם הודעות באמצעות ביטוי רגיל:

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

התאם הודעות באמצעות ביטוי רגיל:

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

התאם הודעות באמצעות ביטוי רגיל:

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

טיפול בעדכונים בשיחות

רשום מטפלים עבור אירועי מחזור חיים של שיחות כגון חברים מצטרפים או עוזבים.

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

פיתון

@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

טיפול בכל סוג פעילות

התאם פעילות כלשהי לפי מחרוזת הסוג שלה כדי לשלוט באופן מלא בניתוב.

C#‎

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

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

השתמש ActivityTypes בקבועים במקום במחרוזות מקודדות.

JavaScript

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

שליטה בסדר הערכת נתיב

המערכת ממיין נתיבים לתוך סדר הערכה קבועה בעת רישום שלהם, לא בזמן ריצה. המיון משתמש בשתי רמות:

1. סוג ניתוב: המערכת מנתבת לפי סוג, והיא תמיד מעריכה סוגי עדיפות גבוהה יותר לפני סוגי עדיפות נמוכה יותר, ללא קשר לדרגות:

   עדיפות	סוג נתיב
   1 (הגבוה ביותר)	נתיבי קריאה של סוכן
   2	נתיבי קריאה (פעולות כרטיסים מסתגלים, קריאות חוזרות של OAuth וקריאות קריאה רגישות זמן אחרות)
   3	נתיבי סוכן
   4 (הנמוך ביותר)	כל הנתיבים האחרים

2. דירוג: בתוך כל קבוצת סוגי ניתוב, הזמנות המערכת מנותב לפי ערך הדירוג שלהן. ערכים מספריים נמוכים נבדקים תחילה.

השתמש RouteRank בקבועים כדי להגדיר דירוג בעת רישום מטפל:

קבוע	ערך:	משמעות
RouteRank.First	0	הערכה לפני כל הנתיבים האחרים בקבוצה
RouteRank.Unspecified	32767	ברירת מחדל כאשר לא צוין דירוג
RouteRank.Last	65535	מוערכים לאחר כל הנתיבים האחרים בקבוצה שלהם

כברירת מחדל, ההערכה נעצרת בנתיב הראשון שמתאים. השתמש RouteRank.Last לחזרה כוללת שמטפלת בכל הפריטים שאינם תואמים לתוואי ספציפי יותר.

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)

פיתון

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

נקודות חיבור של מחזור חיי פנייה

רשום לוגיקה הפועלת בכל סיבוב, לפני או אחרי התאמת נתיב. נקודות חיבור אלה שימושיות לרישום ביומן, לטיפול בהיבטים רוחביים ולטיפול בשגיאות.

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

כאשר OnBeforeTurn מחזיר false, הפנייה מבוטלת ולא מופעלים נתיבים. כאשר OnAfterTurn מחזירה false, מצב turn אינו נשמר.

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

פיתון

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

השתמש במצב 'סיבוב'

הסוכן טוען אוטומטית מצב הפעלה לפני שהמטפלים שלך פועלים ושומר אותו לאחר מכן. אובייקט מצב התור שהועבר למטפלים מעניק לך גישה לטווחים השונים כדי שתוכל לקרוא ולכתוב נתונים המתמשכים לאורך תורים או זמניים עבור התור הנוכחי:

• טווח שיחה: עבור נתונים שמועברים בכל הפעמים בשיחה
• טווח משתמש: עבור נתונים לפי משתמש
• טווח זמני: עבור נתונים קיימים רק במהלך הפעולה הנוכחית

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

פיתון

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

הערה

השתמש MemoryStorage לפיתוח ולבדיקות מקומיות. עבור פריסות ייצור, במיוחד פריסות הפועלות במופעים מרובים, השתמש ספק אחסון מתמיד כגון Azure Cosmos DB או Azure Blob Storage. ראה שימוש בספקי אחסון בסוכן שלך.

השלבים הבאים

• ניהול מצב ב- Agents SDK
• שימוש בספקי אחסון בסוכן שלך