Azure Bot Framework SDK से Microsoft 365 Agents SDK तक माइग्रेशन मार्गदर्शन Python के लिए

यह लेख Python के लिए Bot Framework SDK से Microsoft 365 Agents SDK में माइग्रेशन के लिए आवश्यक परिवर्तनों का वर्णन करता है।

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

• Python संस्करण 3.10 या उच्चतर (3.11+ अनुशंसित, 3.14 तक का समर्थन करता है)
• मौजूदा बॉट फ्रेमवर्क एसडीके परियोजना
• Azure Bot Service संसाधन

Azure संसाधन

इस माइग्रेशन के दौरान आपके मौजूदा Azure संसाधन अपरिवर्तित रहते हैं. अपने वर्तमान Azure Bot पंजीकरण (ऐप आईडी और गुप्त) का उपयोग जारी रखें। आप उन मानों को बाद में वर्णित नई कॉन्फ़िगरेशन संरचना में संदर्भित करते हैं। कई समाधानों में लीगेसी ऐप सेटिंग्स भी शामिल हैं जैसे , APP_ID, APP_PASSWORDऔर APP_TENANT_ID. ये प्रविष्टियाँ माइग्रेशन के दौरान हानिरहित हैं, लेकिन Microsoft 365 एजेंट SDK अब उनका उपयोग नहीं करता है। नए कॉन्फ़िगरेशन को सत्यापित करने के बाद आप इन सेटिंग्स को निकाल सकते हैं.

प्रथम चरण

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

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

यदि आपका बॉट Microsoft Teams के साथ एकीकृत होता है, तो मुख्य Teams सुविधाओं के लिए Teams एक्सटेंशन पैकेज microsoft-agents-hosting-teams शामिल करें।

प्रमाणीकरण के लिए, MSAL-आधारित प्रमाणीकरण को हैंडल करने के लिए जोड़ें microsoft-agents-authentication-msal ।

Bot Framework पैकेज को उनके Agents SDK जैसे पैकेज से बदलने के लिए अपनी requirements.txt या उसके बराबर की डिपेंडेंसी फ़ाइल को अपडेट करें. नई निर्भरताओं को स्थापित करने के लिए अपने पसंदीदा पैकेज प्रबंधक का उपयोग करें pip install -r requirements.txt ।

एजेंट SDK कोड गुणवत्ता मानकों को लागू करने के लिए स्वरूपण black और लिंटिंग flake8 का उपयोग करता है। इन उपकरणों को अपनी विकास निर्भरता में जोड़ने पर विचार करें।

आयात अपडेट करें

इसके बाद, आयात अपडेट करें। सबसे आसान तरीका सटीक पाठ का एक परियोजना-व्यापी खोज-और-प्रतिस्थापन है।

प्रकार और वर्ग नाम बदलें

एजेंट SDK में कुछ प्रकारों और वर्गों के अलग-अलग नाम हैं। अपने परिवर्तनों का मार्गदर्शन करने के लिए निम्नलिखित मैपिंग का उपयोग करें।

गतिविधि वर्ग में परिवर्तन

एजेंट SDK में वर्ग में ActivityPydantic का उपयोग करके अंतर्निहित सत्यापन शामिल है। आप Activity.model_validate() का उपयोग करके JSON या डिक्शनरी से गतिविधियों को पार्स और मान्य कर सकते हैं।

इसके अतिरिक्त, Activity वर्ग गतिविधि पेलोड से संबंधित संचालन को केंद्रीकृत करता है। वे विधियाँ जो पहले स्थिर विधियाँ TurnContext थीं, अब इंस्टेंस विधियाँ हैं Activity:

सामान्य turn_state संदर्भों का अद्यतन करें. तदनुसार निम्नलिखित उपयोगों को बदलें।

कॉन्फ़िगरेशन

एजेंट SDK कॉन्फ़िगरेशन के लिए एक पदानुक्रमित नामकरण सम्मेलन के साथ पर्यावरण चर का उपयोग करता है।

परिवेश चर

निम्न संरचना के साथ अपनी .env फ़ाइल बनाएँ या अद्यतन करें:

# Required for Azure Bot Service
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=your-app-id
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=your-app-secret
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=your-tenant-id

# Optional - for local debugging
PORT=3978

माइग्रेशन नोट: अपने परिवेश चर नामों का अद्यतन करें जैसा कि निम्न तालिका में दिखाया गया है:

एजेंट SDK कॉन्फ़िगरेशन नेस्टेड कॉन्फ़िगरेशन पदानुक्रम का प्रतिनिधित्व करने के लिए डबल अंडरस्कोर ()__ का उपयोग करता है। यह पैटर्न विभिन्न परिनियोजन वातावरणों में लचीले कॉन्फ़िगरेशन प्रबंधन की अनुमति देता है।

स्टार्टअप और आरंभीकरण

आरंभीकरण एजेंट SDK में भिन्न होता है। बॉट फ्रेमवर्क एसडीके आमतौर पर मैनुअल एडाप्टर कॉन्फ़िगरेशन के साथ उपयोग किया जाता aiohttp है। एजेंट SDK का उपयोग करके, आप सरलीकृत सेटअप के लिए अंतर्निहित सर्वर उपयोगिताओं का उपयोग कर सकते हैं।

सर्वर सेटअप

बॉट फ्रेमवर्क एसडीके दृष्टिकोण

from aiohttp import web
from botbuilder.core import BotFrameworkAdapter, BotFrameworkAdapterSettings
from botbuilder.schema import Activity

# Configure adapter
SETTINGS = BotFrameworkAdapterSettings(
    app_id=os.environ.get("APP_ID", ""),
    app_password=os.environ.get("APP_PASSWORD", "")
)
ADAPTER = BotFrameworkAdapter(SETTINGS)

# Bot instance
BOT = MyBot()

async def messages(req: web.Request) -> web.Response:
    if "application/json" in req.headers["Content-Type"]:
        body = await req.json()
    else:
        return web.Response(status=415)

    activity = Activity().deserialize(body)
    auth_header = req.headers["Authorization"] if "Authorization" in req.headers else ""

    response = await ADAPTER.process_activity(activity, auth_header, BOT.on_turn)
    if response:
        return web.json_response(data=response.body, status=response.status)
    return web.Response(status=201)

APP = web.Application()
APP.router.add_post("/api/messages", messages)

if __name__ == "__main__":
    web.run_app(APP, host="localhost", port=3978)

एजेंट एसडीके दृष्टिकोण (डेकोरेटर पैटर्न)

अनुशंसित दृष्टिकोण अधिक आधुनिक, घोषणात्मक शैली के लिए AgentApplication का सज्जाकारों के साथ उपयोग करता है।

import re
from os import environ
from dotenv import load_dotenv

from microsoft_agents.hosting.aiohttp import CloudAdapter
from microsoft_agents.hosting.core import (
    Authorization,
    AgentApplication,
    TurnState,
    TurnContext,
    MemoryStorage,
)
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.activity import load_configuration_from_env

# Load environment variables
load_dotenv()
agents_sdk_config = load_configuration_from_env(environ)

# Initialize core components
STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

# Create agent application
AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE,
    adapter=ADAPTER,
    authorization=AUTHORIZATION,
    **agents_sdk_config
)

# Register handlers using decorators
@AGENT_APP.conversation_update("membersAdded")
async def on_members_added(context: TurnContext, _state: TurnState):
    await context.send_activity("Welcome!")
    return True

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    await context.send_activity(f"You said: {context.activity.text}")

एजेंट SDK load_configuration_from_env() प्रदान करता है जो स्वचालित रूप से पर्यावरण वेरिएबल्स से कॉन्फ़िगरेशन लोड करता है, जिससे मैनुअल कॉन्फ़िगरेशन पार्सिंग की आवश्यकता समाप्त हो जाती है। डेकोरेटर पैटर्न आपको स्पष्ट वर्ग-आधारित विरासत के बिना हैंडलर को घोषणात्मक रूप से पंजीकृत करने की अनुमति देता है।

प्रमाणीकरण और सुरक्षा

बॉट फ्रेमवर्क SDK में एडाप्टर में JSON वेब टोकन (JWT) सत्यापन शामिल था। एजेंट SDK प्रमाणीकरण चिंताओं को अलग करता है, ताकि आप प्रमाणीकरण मिडलवेयर को स्पष्ट रूप से कॉन्फ़िगर कर सकें।

उत्पादन वातावरण के लिए, सुनिश्चित करें कि कॉन्फ़िगरेशन के माध्यम से CloudAdapter JWT सत्यापन सक्षम है। एडाप्टर स्वचालित रूप से आवक अनुरोध MSAL प्रमाणीकरण कॉन्फ़िगरेशन का उपयोग कर मान्य करता है।

बॉट फ़्रेमवर्क एमुलेटर के साथ स्थानीय विकास के लिए, आप अपनी .env फ़ाइल में रिक्त क्रेडेंशियल्स का उपयोग कर सकते हैं:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

गतिविधि प्रबंधन

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

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

मुख्य अंतर

हैंडलर विधि हस्ताक्षर परिवर्तन

बॉट फ्रेमवर्क एसडीके हैंडलर आमतौर पर स्थितीय पैरामीटर का उपयोग करते हैं, जबकि एजेंट एसडीके हैंडलर प्राथमिक पैरामीटर के साथ समान TurnContext पैटर्न बनाए रखते हैं।

एजेंट SDK में अतिरिक्त तरीके

एजेंट SDK में अनुपलब्ध विधियाँ

माइग्रेशन उदाहरण

बॉट फ्रेमवर्क SDK

from botbuilder.core import ActivityHandler, TurnContext
from botbuilder.schema import ChannelAccount

class MyBot(ActivityHandler):
    async def on_message_activity(self, turn_context: TurnContext):
        await turn_context.send_activity(f"You said: {turn_context.activity.text}")

    async def on_members_added_activity(
        self,
        members_added: list[ChannelAccount],
        turn_context: TurnContext
    ):
        for member in members_added:
            if member.id != turn_context.activity.recipient.id:
                await turn_context.send_activity("Welcome!")

एजेंट एसडीके

from microsoft_agents.hosting.core import AgentApplication, TurnState, TurnContext

# AGENT_APP is initialized as shown in the Startup and initialization section

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    await context.send_activity(f"You said: {context.activity.text}")

@AGENT_APP.conversation_update("membersAdded")
async def on_members_added(context: TurnContext, _state: TurnState):
    for member in context.activity.members_added:
        if member.id != context.activity.recipient.id:
            await context.send_activity("Welcome!")
    return True

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

राज्य प्रबंधन

ConversationState, UserState, और PrivateConversationState कुछ अंतरों के साथ संगत हैं। कोर स्टेट मैनेजमेंट पैटर्न बॉट फ्रेमवर्क एसडीके के समान हैं।

आपको राज्य ऑब्जेक्ट्स को पंजीकृत करना होगा और संशोधनों के बाद उन्हें स्पष्ट रूप से सहेजना होगा।

from microsoft_agents.hosting.core import (
    AgentApplication,
    TurnState,
    TurnContext,
    ConversationState,
    UserState,
    MemoryStorage,
)

# Initialize storage and state
STORAGE = MemoryStorage()
conversation_state = ConversationState(STORAGE)
user_state = UserState(STORAGE)
count_property = conversation_state.create_property("conversation_data")

# AGENT_APP is initialized as shown in the Startup and initialization section

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    # Access state
    conversation_data = await count_property.get(context, {})

    # Modify state
    conversation_data["count"] = conversation_data.get("count", 0) + 1
    await count_property.set(context, conversation_data)

    await context.send_activity(f"Message count: {conversation_data['count']}")

    # Save state changes
    await conversation_state.save_changes(context)
    await user_state.save_changes(context)

भंडारण विकल्प

एजेंट SDK विभिन्न बैकएंड के लिए भंडारण कार्यान्वयन प्रदान करता है:

# Memory storage (development only)
from microsoft_agents.hosting.core import MemoryStorage
storage = MemoryStorage()

# Azure Blob Storage
from microsoft_agents.storage.blob import BlobStorage
storage = BlobStorage(
    connection_string="your-connection-string",
    container_name="bot-state"
)

# Azure Cosmos DB
from microsoft_agents.storage.cosmos import CosmosDbPartitionedStorage
storage = CosmosDbPartitionedStorage(
    cosmos_client_options={
        "url": "your-cosmos-url",
        "key": "your-cosmos-key"
    },
    database_id="bot-db",
    container_id="bot-state"
)

लॉगिंग

एजेंट एसडीके Python के मानक logging मॉड्यूल का उपयोग करता है। अपनी मुख्य अनुप्रयोग फ़ाइल में लॉगिंग कॉन्फ़िगर करें:

import logging

# Configure logging for Agents SDK
ms_agents_logger = logging.getLogger("microsoft_agents")
console_handler = logging.StreamHandler()
console_handler.setFormatter(
    logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
)
ms_agents_logger.addHandler(console_handler)
ms_agents_logger.setLevel(logging.INFO)

लॉग स्तर

• DEBUG: विस्तृत स्थानीय स्थिति अनुरेखण
• जानकारी: गतिविधि प्रबंधन, एपीआई कॉल, और बाहरी संस्थाओं से या उनसे अनुरोध
• चेतावनी: अनपेक्षित घटनाएँ जो संभावित समस्याओं का कारण बनती हैं
• त्रुटि: देखी गई त्रुटियां, चाहे पकड़ी गई हों या न पकड़ी गई हों

सामान्य माइग्रेशन पैटर्न

सरल इको बॉट

बॉट फ्रेमवर्क SDK में सिंपल इको बॉट

from botbuilder.core import ActivityHandler, TurnContext

class EchoBot(ActivityHandler):
    async def on_message_activity(self, turn_context: TurnContext):
        await turn_context.send_activity(f"Echo: {turn_context.activity.text}")

एजेंट एसडीके में सरल इको बॉट

from microsoft_agents.hosting.core import AgentApplication, TurnState, TurnContext

# AGENT_APP is initialized as shown in the Startup and initialization section

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    await context.send_activity(f"Echo: {context.activity.text}")

काउंटर के साथ राज्य प्रबंधन

from microsoft_agents.hosting.core import (
    AgentApplication,
    TurnState,
    TurnContext,
    ConversationState,
    MemoryStorage,
)

# Initialize storage and state
STORAGE = MemoryStorage()
conversation_state = ConversationState(STORAGE)
count_property = conversation_state.create_property("count")

# AGENT_APP is initialized as shown in the Startup and initialization section

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    count = await count_property.get(context, 0)
    count += 1
    await count_property.set(context, count)

    await context.send_activity(f"Message count: {count}")
    await conversation_state.save_changes(context)

माइक्रोसॉफ्ट टीम्स बॉट

from microsoft_agents.hosting.core import AgentApplication, TurnState, TurnContext

# AGENT_APP is initialized as shown in the Startup and initialization section
# Include microsoft-agents-hosting-teams in your dependencies for Teams support

@AGENT_APP.conversation_update("membersAdded")
async def on_members_added(context: TurnContext, _state: TurnState):
    for member in context.activity.members_added:
        await context.send_activity(f"Welcome to the team, {member.name}!")
    return True

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    # Remove mentions
    text = context.activity.remove_mention_text(context.activity.recipient.id)
    await context.send_activity(f"You said: {text}")

समस्या निवारण और सुझाव

निम्नलिखित युक्तियां आपको अधिक सफल होने में मदद कर सकती हैं।

आयात त्रुटियाँ

यदि आप आयात त्रुटियों का सामना करते हैं, तो सुनिश्चित करें कि आप सभी आयात कथनों में बिंदुओं ()microsoft_agents के बजाय अंडरस्कोर ()microsoft.agents का उपयोग कर रहे हैं। यह त्रुटि सबसे आम माइग्रेशन समस्या है।

Async/await पैटर्न

सभी बॉट विधियों को async होना चाहिए और अतुल्यकालिक संचालन के लिए await का उपयोग करना चाहिए। सुनिश्चित करें कि सभी send_activity पर किए गए कॉल, राज्य संचालन और संवाद संचालन await का उपयोग करें।

संकेत टाइप करें

एजेंट SDK Python प्रकार के संकेतों का बड़े पैमाने पर उपयोग करता है। बेहतर IDE समर्थन और त्रुटि का पता लगाने के लिए अपने बॉट कोड में प्रकार के संकेत जोड़ने पर विचार करें:

from microsoft_agents.hosting.core import TurnContext

async def on_message_activity(self, turn_context: TurnContext) -> None:
    await turn_context.send_activity("Hello")

कॉन्फ़िगरेशन सत्यापन

यदि कॉन्फ़िगरेशन त्रुटियों के कारण आपका बॉट प्रारंभ करने में विफल रहता है, तो सत्यापित करें कि आपके परिवेश चर नाम सही डबल-अंडरस्कोर ()__ संकेतन का उपयोग करते हैं और आपने सभी आवश्यक मान सेट किए हैं।

डीबगिंग के दौरान स्थानीय 401 त्रुटियाँ

यदि आप बॉट Framework एमुलेटर का उपयोग करके स्थानीय डीबगिंग के दौरान 401 त्रुटियाँ देखते हैं, तो सत्यापित करें कि आपके क्रेडेंशियल्स फ़ाइल में सही रूप से .env कॉन्फ़िगर किए गए हैं या एमुलेटर की प्रमाणीकरण सेटिंग्स का उपयोग करें।

Python संस्करण संगतता

सुनिश्चित करें कि आप Python 3.10 या उच्चतर का उपयोग कर रहे हैं। एजेंट SDK आधुनिक Python सुविधाओं का उपयोग करता है जो पहले के संस्करणों में उपलब्ध नहीं हैं।

माइग्रेशन चेकलिस्ट

✓ विश्लेषण और योजना बनाएं: किसी भी बहिष्कृत सुविधाओं की पहचान करें और माइग्रेशन बनाम पुनर्निर्माण का दायरा तय करें। ✓ Python संस्करण अपग्रेड करें: Python 3.10 या उच्चतर (3.11+ अनुशंसित) पर जाएं। ✓ पैकेज बदलें: हटाएं botbuilder-*; जोड़ें microsoft-agents-* (होस्टिंग-कोर, गतिविधि, होस्टिंग-एआईओhttp, प्रमाणीकरण-एमएसएएल, भंडारण प्रदाता, होस्टिंग-टीम)। ✓ आयात अपडेट करें: उपरोक्त तालिकाओं के अनुसार पाए/बदलें लागू करें; सभी microsoft.agents को microsoft_agents में बदलें। ✓ प्रकार और कक्षाएं अपडेट करें: नाम बदले गए एपीआई को ठीक करें और स्थिर विधियों को इंस्टेंस विधियों में ले TurnContext जाएंActivity। ✓ अद्यतन विन्यास: पदानुक्रमित नामकरण (डबल अंडरस्कोर) के साथ फ़ाइल बनाएं .env । ✓ अद्यतन इनिशियलाइज़ेशन: CloudAdapter को MsalAuth.from_environment() और AgentsHttpMiddleware के साथ प्रयोग करें। ✓ लॉगिंग कॉन्फ़िगर करें: microsoft_agents लॉगर के लिए Python लॉगिंग सेट करें। ✓ स्थानीय स्तर पर निर्माण और परीक्षण करें: क्रेडेंशियल्स के साथ बॉट फ्रेमवर्क एमुलेटर का उपयोग करें; मुख्य परिदृश्यों को मान्य करें। ✓ परिनियोजन और मॉनिटर: रोलआउट के बाद नए कॉन्फ़िगरेशन और वॉच लॉग से मेल खाने के लिए Azure में पर्यावरण चर अपडेट करें।

संबंधित सामग्री

• Azure Bot Framework SDK से Agents SDK माइग्रेशन के लिए मार्गदर्शन
• ऐज़ूर बोट फ्रेमवर्क SDK से माइक्रोसॉफ्ट 365 एजेंट्स SDK में .NET के लिए माइग्रेशन मार्गदर्शन
• Node.js के लिए Azure Bot Framework SDK से Microsoft 365 Agents SDK में माइग्रेशन के लिए मार्गदर्शन