Azure Bot Framework SDK Microsoft 365 Agents SDK הדרכה להעברה עבור nodejs

מאמר זה מתאר את השינויים הדרושים להעברה מ- Bot Framework SDK עבור Node.js.

‏‫דרישות מוקדמות‬

• Node.jsגירסה 20 ואילך
• פרוייקט SDK קיים של Bot Framework
• Azure Bot Service (נותר ללא שינוי במהלך ההעברה)

שינויים בקוד SDK של NodeJS

השינויים בסעיף זה נובעים מהבדלים בין Azure Bot Framework SDK לבין Microsoft 365 Agents SDK JavaScript .

משאבים של Azure

המשאבים Azure נותרים ללא שינוי. עליך להפנות אל המאפיינים שלך ב-appsettings עבור MicrosoftAppType, MicrosoftAppId, MicrosoftAppPasswordו- MicrosoftAppTenantId. עם זאת, לא נעשה עוד שימוש בשמות הגדרות אלה ובאפשרותך למחוק אותם במועד מאוחר יותר. קבל מידע נוסף אודות תצורת סביבה

השלבים הראשונים

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

עדכון יחסי תלות של חבילה

שינוי זה אינו מיישב את כל מרחבי השמות הדרושים, אך הוא מכסה את כל מרחבי השמות.

תוכניות Bot המשתמשות ב- Teams

אם הבוט שלך משתמש ב- Teams, הוסף תלות בחבילה עבור @microsoft/agents-hosting-extensions-teams

עדכון ייבוא/דרישה

השתמש בחיפוש והחלפה כדי לבצע את השינויים הבאים:

מחלקת Activity של Agents‏ SDK

@microsoft/agents-activity החבילה כוללת את מחלקת הפעילות לביצוע ניתוח בהתבסס על zod. באפשרותך לנתח ולאמת את הפעילויות המותאמות אישית שלך מ- JSON עם Activity.fromJson() או מתוך אובייקטי JavaScript ליטרליים עם Activity.fromObject().

בנוסף, המחלקה Activity מרכזת את כל הפעולות הקשורות למנה של פעילות, כגון getConversationReference. השיטות בטבלה הבאה הועברו ממופע TurnContext הפעילות הנוכחי ופועלים כעת:

הפעלה ותצורה

מערכת התצורה של Agents SDK מחליפה את ConfigurationBotFrameworkAuthentication המחלקה בממשק AuthConfiguration .

כדי לטעון את התצורה מקובץ ברירת .env המחדל, נעשה שימוש ב- loadAuthConfigFromEnv.

תצורת סביבה

צור קובץ .env עם המשתנים הבאים:

# Required for Azure Bot Service
clientId=your-app-id
clientSecret=your-app-secret  
tenantId=your-tenant-id

# Optional - for local debugging
PORT=3978
DEBUG=true

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

אימות ואבטחה

כאשר Bot Framework SDK מאשר בקשות נכנסות, הוא כולל אסימוני הרשאה של אסימון אינטרנט JSON (JWT) בערימה. הסוכנים SDK לא. בעת שימוש בזמן ריצה של שרת אינטרנט, כגון express, עליך לקבוע את התצורה של תוכנת ביניים של JWT כדי לאשר בקשות נכנסות בהתבסס על אסימון של נושא JWT, ערכת ה- SDK של Agents מספקת את authorizeJWT(AuthConfiguration) השיטה.

תוכנת ביניים של JWT (נדרשת לייצור):

import { authorizeJWT, loadAuthConfigFromEnv } from '@microsoft/agents-hosting'

const authConfig = loadAuthConfigFromEnv()
server.use(authorizeJWT(authConfig))

פיתוח מקומי:

לאיתור באגים מקומי, ניתן להפוך אימות JWT ללא זמין:

// Only for local development - NEVER in production
if (process.env.NODE_ENV === 'development') {
    // JWT validation disabled for local testing
} else {
    server.use(authorizeJWT(authConfig))
}

אפשרויות הגדרת שרת

ה- SDK של הסוכנים מספק שתי גישות להגדרת השרת שלך:

• פעולת שירות של startServer
• הגדרה ידנית מהירה

השתמש בפעולת השירות startServer

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

עדכן את קוד האתחול שלך מ:botbuilder

const { EchoBot } = require('./bot');
const {
    CloudAdapter,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');
const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);
const adapter = new CloudAdapter(botFrameworkAuthentication);
const myBot = new EchoBot();
const server = express();
server.use(express.json());
server.post('/api/messages', async (req, res) => 
    await adapter.process(req, res, (context) => 
      myBot.run(context));
);

לסוכנים מארחים באמצעות startServer():

const { EchoBot } = require('./bot');
const { startServer } = require('@microsoft/agents-hosting-express')
startServer(new EchoBot());

הגדרה ידנית מהירה

השתמש בגישה זו בעת העברת בוטים קיימים, נדרשת תוכנת ביניים מותאמת אישית, רוצה שליטה מלאה על תצורת Express

const { EchoBot } = require('./bot');
const {
    CloudAdapter,
    loadAuthConfigFromEnv, // Update
    authorizeJWT // Update
} = require('@microsoft/agents-hosting'); // Update
const authConfig = loadAuthConfigFromEnv(); // Update
const adapter = new CloudAdapter(authConfig); // Update
const myBot = new EchoBot();
const server = express();
server.use(express.json());
server.use(authorizeJWT(authConfig)); // Update
server.post('/api/messages', async (req, res) => 
    await adapter.process(req, res, (context) => 
      myBot.run(context));
);

const port = process.env.PORT || 3978;
server.listen(port, () => {
    console.log(`Server listening on port ${port}`);
}).on('error', (err) => {
    console.error('Server failed to start:', err);
    process.exit(1);
});

תמיכה עבור ActivityHandler

רוב בוטים שנוצרו באמצעות ה- SDK של Bot Framework מבוססים על מחלקת botbuilder-core.ActivityHandler הבסיס.

ה- SDK של Agents מספק תואם agents-hosting.ActivityHandler ששומרת על אותו משטח API להעברה קלה יותר.

הבדלים עיקריים

להלן כמה הבדלים עיקריים בין ה- SDK של Bot Framework לבין ה- SDK Agents:

פרמטרים של מטפל:

שיטות נוספות ב- Agents SDK:

מתודות חסרות ב-SDK של סוכנים:

שינויים בחתימת שיטה:

כל פעולות השירות של המטפל מחזירות ActivityHandler במקום this עבור שרשרת פעולות שירות. פונקציות המטפל משתמשות בסוג AgentHandler , בעל אותה חתימה כמו BotHandler

דוגמה להעברה:

const { ActivityHandler } = require('botbuilder');

class MyBot extends ActivityHandler {
    constructor() {
        super();
        this.onMessage(async (context, next) => {
            await context.sendActivity('Hello!');
            await next();
        });
    }
}

const { ActivityHandler } = require('@microsoft/agents-hosting');

class MyBot extends ActivityHandler {
    constructor() {
        super();
        this.onMessage(async (context, next) => {
            await context.sendActivity('Hello!');
            await next();
        });
    }
}

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

מיגרציה מActivityHandler לAgentApplication

למרות ActivityHandler שהגישה המומלצת נתמכת לצורך תאימות לאחור, היא להשתמש ב- AgentApplication:

import { ActivityHandler } from '@microsoft/agents-hosting'

class MyBot extends ActivityHandler {
    constructor() {
        super()
        this.onMessage(async (context, next) => {
            await context.sendActivity('Hello!')
            await next()
        })
        
        this.onMembersAdded(async (context, next) => {
            await context.sendActivity('Welcome!')
            await next()
        })
    }
}

import { AgentApplication, MemoryStorage } from '@microsoft/agents-hosting'

const agent = new AgentApplication({
    storage: new MemoryStorage()
})

agent.onMessage(async (context, state) => {
    await context.sendActivity('Hello!')
})

agent.onConversationUpdate('membersAdded', async (context, state) => {
    await context.sendActivity('Welcome!')
})

// Additional capabilities
agent.onMessage('/reset', async (context, state) => {
    state.deleteConversationState()
    await context.sendActivity('State cleared!')
})

הבדלים עיקריים

הטבלה הבאה מתארת הבדלי תכונות עיקריים בין ActivityHandler :AgentApplication

תבניות העברה נפוצות

להלן כמה תבניות העברה נפוצות:

• Simple Echo Bot
• ניהול מדינה
• ירושה מ- AgentApplication

Simple Echo Bot

const { ActivityHandler } = require('botbuilder')

class EchoBot extends ActivityHandler {
    constructor() {
        super()
        this.onMessage(async (context, next) => {
            await context.sendActivity(`You said: ${context.activity.text}`)
            await next()
        })
    }
}

import { AgentApplication, MessageFactory } from '@microsoft/agents-hosting'

const agent = new AgentApplication()

agent.onMessage(async (context) => {
    const replyText = `Echo: ${context.activity.text}`
    await context.sendActivity(MessageFactory.text(replyText))
})

ניהול מצבים

באמצעות AgentApplication:

import { AgentApplication, MemoryStorage } from '@microsoft/agents-hosting'

const agent = new AgentApplication({
    storage: new MemoryStorage()
})

agent.onMessage('/count', async (context, state) => {
    const count = state.conversation.count ?? 0
    state.conversation.count = count + 1
    await context.sendActivity(`Count: ${state.conversation.count}`)
})

ירושה מ-AgentApplication

עבור תרחישים מורכבים יותר, באפשרותך ליצור מחלקה היורשת מ:AgentApplication

import { AgentApplication, MemoryStorage, MessageFactory } from '@microsoft/agents-hosting'

class MyAgent extends AgentApplication {
    constructor() {
        super({
            storage: new MemoryStorage()
        })
        this.setupRoutes()
    }
    
    setupRoutes() {
        this.onMessage('/help', this.handleHelp)
        this.onMessage('/status', this.handleStatus)
        this.onMessage('/reset', this.handleReset)
        
        this.onActivity('message', this.handleDefault)
        this.onConversationUpdate('membersAdded', this.handleWelcome)
    }
    
    handleHelp = async (context, state) => {
        const helpText = `
                Available commands:
                - /help - Show this help message
                - /status - Show current status
                - /reset - Reset conversation state
        `
        await context.sendActivity(MessageFactory.text(helpText))
    }
    
    handleStatus = async (context, state) => {
        const messageCount = state.conversation.messageCount ?? 0
        await context.sendActivity(`Messages processed: ${messageCount}`)
    }
    
    handleReset = async (context, state) => {
        state.deleteConversationState()
        await context.sendActivity('Conversation state has been reset.')
    }
    
    handleWelcome = async (context, state) => {
        const welcomeText = 'Welcome! Type /help to see available commands.'
        await context.sendActivity(MessageFactory.text(welcomeText))
    }
    
    handleDefault = async (context, state) => {
        // Increment message counter
        const messageCount = (state.conversation.messageCount ?? 0) + 1
        state.conversation.messageCount = messageCount
        
        const replyText = `Echo: ${context.activity.text} (Message #${messageCount})`
        await context.sendActivity(MessageFactory.text(replyText))
    }
}

export default new MyAgent()

היתרונות של תבנית זו

תוכן קשור

• Azure Bot Framework SDK להנחיות העברת SDK לסוכנים
• Azure Bot Framework SDK Microsoft 365 Agents SDK הדרכה להעברה עבור .NET
• Azure Bot Framework SDK Microsoft 365 Agents SDK הדרכה להעברה עבור Python