Azure Bot Framework SDK से Microsoft 365 Agents SDK में माइग्रेशन हेतु मार्गदर्शन, nodejs के लिए

यह आलेख वर्णन करता है कि Node.jsके लिए Bot Framework SDK से माइग्रेट करने के लिए आवश्यक परिवर्तन .

पूर्वावश्यकताएँ

• Node.js संस्करण 20 या उच्चतर
• मौजूदा बॉट फ्रेमवर्क एसडीके परियोजना
• Azure Bot Service संसाधन (माइग्रेशन के दौरान अपरिवर्तित रहता है)

NodeJS SDK कोड परिवर्तन

इस खंड में परिवर्तन Azure बॉट फ्रेमवर्क SDK और Microsoft 365 Agents SDK जावास्क्रिप्ट .

Azure संसाधन

आपके Azure संसाधन अपरिवर्तित रहते हैं. आपको अपनी appsettings गुणों को MicrosoftAppType, MicrosoftAppId, MicrosoftAppPassword, और MicrosoftAppTenantId के लिए संदर्भित करने की आवश्यकता है। हालाँकि, उन सेटिंग नामों का अब उपयोग नहीं किया जाता है और बाद में हटाया जा सकता है। परिवेश कॉन्फ़िगरेशन के बारे में अधिक जानें

प्रथम चरण

अधिकांश अंतरों को संबोधित करने के लिए पहले निम्नलिखित परिवर्तन लागू करें। इन परिवर्तनों को लागू करने के बाद भी आपको डीबग करना होगा और अन्य अंतरों की जांच करनी होगी।

पैकेज निर्भरताएँ अद्यतन करें

यह परिवर्तन सभी आवश्यक नामस्थानों को व्यवस्थित नहीं करता है, लेकिन यह उनमें से अधिकांश को कवर करता है।

टीमों का उपयोग करने वाले बॉट

यदि आपका बॉट टीमों का उपयोग करता है, तो इसके लिए पैकेज निर्भरता जोड़ें @microsoft/agents-hosting-extensions-teams

इम्पोर्ट्स/रिक्वायर अद्यतन करें

निम्न परिवर्तन करने के लिए ढूँढें और बदलें का उपयोग करें:

एजेंट SDK गतिविधि वर्ग

पैकेज में @microsoft/agents-activityzod के आधार पर पार्सिंग करने के लिए Activity class शामिल है। आप JSON से Activity.fromJson() या शाब्दिक JavaScript ऑब्जेक्ट से अपनी कस्टम गतिविधियों को पार्स और मान्य कर सकते हैं Activity.fromObject()।

इसके अतिरिक्त, Activity वर्ग गतिविधि पेलोड से संबंधित सभी कार्यों को केंद्रीकृत करता है, जैसे getConversationReference। निम्न तालिका में वर्णित विधियाँ TurnContext से स्थानांतरित की गई हैं और अब वर्तमान गतिविधि उदाहरण पर कार्य करती हैं:

स्टार्टअप और कॉन्फ़िगरेशन

एजेंट 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) प्राधिकरण टोकन शामिल होते हैं। एजेंट एसडीके कार्य नहीं करता है। एक्सप्रेस जैसे वेब सर्वर रनटाइम का उपयोग करते समय आपको JWT बियरर टोकन के आधार पर आने वाले अनुरोधों को अधिकृत करने के लिए JWT मिडलवेयर को कॉन्फ़िगर करना होगा, एजेंट SDK विधि प्रदान करता है 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 विधि
• मैनुअल एक्सप्रेस सेटअप

स्टार्टसर्वर विधि का उपयोग करें

नई परियोजनाओं के लिए इस सरलीकृत दृष्टिकोण का उपयोग करें जब आप न्यूनतम सेटअप चाहते हैं और कस्टम मिडलवेयर की आवश्यकता नहीं है।

अपना आरंभीकरण कोड यहां से 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());

मैनुअल एक्सप्रेस सेटअप

मौजूदा बॉट्स माइग्रेट करते समय इस दृष्टिकोण का उपयोग करें, कस्टम मिडलवेयर की आवश्यकता है, एक्सप्रेस कॉन्फ़िगरेशन पर पूर्ण नियंत्रण चाहते हैं

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 समर्थन

बॉट फ्रेमवर्क एसडीके के साथ बनाए गए अधिकांश बॉट बेस क्लास पर botbuilder-core.ActivityHandler आधारित होते हैं।

एजेंट एसडीके एक संगत agents-hosting.ActivityHandler प्रदान करता है जो आसान माइग्रेशन के लिए समान एपीआई सतह को बनाए रखता है।

मुख्य अंतर

बॉट फ्रेमवर्क एसडीके और एजेंट एसडीके के बीच कुछ प्रमुख अंतरों में शामिल हैं:

हैंडलर पैरामीटर:

एजेंट एसडीके में अतिरिक्त तरीके:

एजेंट 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();
        });
    }
}

माइग्रेशन ज्यादातर सीधा है, जिसमें मुख्य परिवर्तन आयात विवरण और हैंडलर प्रकार है। अधिकांश मौजूदा-आधारित ActivityHandlerबॉट्स को न्यूनतम संशोधनों के साथ काम करना चाहिए।

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 के मुख्य विशेषता अंतर का वर्णन करती है।

सामान्य प्रवासन पैटर्न

कुछ सामान्य माइग्रेशन पैटर्न हैं:

• सरल इको बॉट
• राज्य प्रबंधन
• AgentApplication से इनहेरिट करना

सरल इको बॉट

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 से Agents SDK माइग्रेशन के लिए मार्गदर्शन
• ऐज़ूर बोट फ्रेमवर्क SDK से माइक्रोसॉफ्ट 365 एजेंट्स SDK में .NET के लिए माइग्रेशन मार्गदर्शन
• Python के लिए Azure Bot Framework SDK से Microsoft 365 Agents SDK में माइग्रेशन मार्गदर्शन