Οδηγίες μετεγκατάστασης από το Azure Bot Framework SDK στο SDK παραγόντων Microsoft 365 για Python.

Αυτό το άρθρο περιγράφει τις απαιτούμενες αλλαγές για μετεγκατάσταση από το Bot Framework SDK για Python στο SDK παραγόντων Microsoft 365 για Python.

Προαπαιτούμενα

• Python έκδοση 3.10 ή νεότερη (συνιστάται 3,11+, υποστηρίζει έως 3,14)
• Υπάρχον έργο Bot Framework SDK
• πόρος Azure Bot Service

πόροι του Azure

Οι υπάρχοντες Azure πόροι σας παραμένουν αμετάβλητοι κατά τη διάρκεια αυτής της μετεγκατάστασης. Συνεχίστε να χρησιμοποιείτε την τρέχουσα Azure καταχώρηση bot (αναγνωριστικό εφαρμογής και μυστικός κωδικός). Μπορείτε να αναφέρετε αυτές τις τιμές στη νέα δομή ρύθμισης παραμέτρων που περιγράφεται παρακάτω. Πολλές λύσεις περιλαμβάνουν επίσης ρυθμίσεις εφαρμογών παλαιού τύπου, όπως APP_ID, APP_PASSWORDκαι APP_TENANT_ID. Αυτές οι καταχωρήσεις είναι ακίνδυνες κατά τη μετεγκατάσταση, αλλά η SDK παραγόντων Microsoft 365 δεν τις χρησιμοποιεί πλέον. Μπορείτε να καταργήσετε αυτές τις ρυθμίσεις μετά την επικύρωση της νέας διαμόρφωσης.

Πρώτα βήματα

Ξεκινήστε ενημερώνοντας τις εξαρτήσεις πακέτων. Οι ακόλουθες αλλαγές δεν καλύπτουν κάθε χώρο ονομάτων που ίσως χρειαστεί να αγγίξετε, αλλά χειρίζονται τις περισσότερες αντικαταστάσεις πακέτων.

Ενημέρωση εξαρτήσεων πακέτων

Εάν το bot σας ενοποιείται με Microsoft Teams, συμπεριλάβετε το πακέτο επέκτασης Teams microsoft-agents-hosting-teams για βασικές δυνατότητες του Teams.

Για έλεγχο ταυτότητας, προσθέστε microsoft-agents-authentication-msal για να χειριστείτε τον έλεγχο ταυτότητας που βασίζεται σε MSAL.

Ενημερώστε το δικό σας requirements.txt ή ισοδύναμο αρχείο εξάρτησης για να αντικαταστήσετε τα πακέτα Bot Framework με τα αντίστοιχα SDK παραγόντων. Χρησιμοποιήστε pip install -r requirements.txt ή τον διαχειριστή πακέτων που προτιμάτε για να εγκαταστήσετε τις νέες εξαρτήσεις.

Το SDK παραγόντων επιβάλλει πρότυπα ποιότητας κώδικα χρησιμοποιώντας black για μορφοποίηση και flake8 για linting. Εξετάστε το ενδεχόμενο να προσθέσετε αυτά τα εργαλεία στις εξαρτήσεις ανάπτυξής σας.

Ενημέρωση εισαγωγών

Στη συνέχεια, ενημερώστε τις εισαγωγές. Η ευκολότερη προσέγγιση είναι η εύρεση και αντικατάσταση του ακριβούς κειμένου σε όλο το έργο.

Μετονομασίες τύπων και κλάσεων

Ορισμένοι τύποι και κλάσεις έχουν διαφορετικά ονόματα στο SDK παραγόντων. Χρησιμοποιήστε τις παρακάτω αντιστοιχίσεις για να καθοδηγήσετε τις αλλαγές σας.

Αλλαγές κατηγορίας δραστηριότητας

Η Activity κλάση στο SDK παραγόντων περιλαμβάνει ενσωματωμένη επικύρωση με χρήση του Pydantic. Μπορείτε να αναλύσετε και να επικυρώσετε δραστηριότητες από JSON ή λεξικά χρησιμοποιώντας Activity.model_validate()το .

Επιπλέον, η 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 παραγόντων. Το Bot Framework SDK χρησιμοποιείται aiohttp συνήθως με μη αυτόματη διαμόρφωση προσαρμογέα. Χρησιμοποιώντας το SDK παραγόντων, μπορείτε να χρησιμοποιήσετε τα ενσωματωμένα βοηθητικά προγράμματα διακομιστή για απλοποιημένη ρύθμιση.

Ρύθμιση διακομιστή

Προσέγγιση Bot Framework 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)

Προσέγγιση SDK Agents (μοτίβο διακοσμητή)

Η προτεινόμενη προσέγγιση χρησιμοποιεί το 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() αυτόματη φόρτωση διαμόρφωσης από μεταβλητές περιβάλλοντος, εξαλείφοντας τη μη αυτόματη ανάλυση διαμόρφωσης. Το μοτίβο διακοσμητή σάς επιτρέπει να καταχωρείτε χειριστές δηλωτικά χωρίς ρητή κληρονομικότητα βάσει κλάσης.

Έλεγχος ταυτότητας και ασφάλεια

Το Bot Framework SDK περιλάμβανε επικύρωση JSON Web Token (JWT) στον προσαρμογέα. Το SDK παραγόντων διαχωρίζει τα ζητήματα ελέγχου ταυτότητας, ώστε να μπορείτε να ρυθμίσετε ρητά τις παραμέτρους του ενδιάμεσου λογισμικού ελέγχου ταυτότητας.

Για περιβάλλοντα παραγωγής, βεβαιωθείτε ότι η επικύρωση JWT είναι ενεργοποιημένη μέσω της CloudAdapter διαμόρφωσης. Ο προσαρμογέας επικυρώνει αυτόματα τις εισερχόμενες αιτήσεις χρησιμοποιώντας τη ρύθμιση παραμέτρων ελέγχου ταυτότητας MSAL.

Για τοπική ανάπτυξη με τον εξομοιωτή Bot Framework, μπορείτε να χρησιμοποιήσετε κενά διαπιστευτήρια στο αρχείο .env:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

Χειρισμός δραστηριότητας

Τα περισσότερα bot που δημιουργούνται με το Bot Framework SDK βασίζονται στη ActivityHandler βασική κλάση.

Το SDK παραγόντων παρέχει μια συμβατή ActivityHandler επιφάνεια που διατηρεί μια παρόμοια επιφάνεια API για ευκολότερη μετεγκατάσταση.

Βασικές διαφορές

Αλλαγές υπογραφής μεθόδου διαχειριστή

Οι χειριστές SDK του Bot Framework χρησιμοποιούν συνήθως παραμέτρους θέσης, ενώ οι χειριστές SDK παραγόντων διατηρούν το ίδιο μοτίβο με TurnContext την κύρια παράμετρο.

Πρόσθετες μέθοδοι στο SDK παραγόντων

Μέθοδοι που λείπουν στο SDK παραγόντων

Παράδειγμα μετεγκατάστασης

Bot Framework 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!")

Agents SDK

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

Η μετεγκατάσταση είναι ως επί το πλείστον απλή, με τις κύριες αλλαγές να είναι οι δηλώσεις εισαγωγής. Τα περισσότερα υπάρχοντα bots που βασίζονται στο ActivityHandler λειτουργούν με ελάχιστες τροποποιήσεις.

Διαχείριση πολιτειών

ConversationState, UserState, και PrivateConversationState είναι συμβατά με ορισμένες διαφορές. Τα βασικά μοτίβα διαχείρισης κατάστασης είναι παρόμοια με το Bot Framework SDK.

Πρέπει να καταχωρίσετε αντικείμενα κατάστασης και να τα αποθηκεύσετε ρητά μετά από τροποποιήσεις.

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 παραγόντων παρέχει υλοποιήσεις χώρου αποθήκευσης για διαφορετικά backend:

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

Καταγραφή

Το SDK Agents χρησιμοποιεί την τυπική εκπαιδευτική ενότητα logging του Python. Διαμορφώστε την καταγραφή στο κύριο αρχείο της εφαρμογής σας:

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)

Επίπεδα καταγραφής

• ΕΝΤΟΠΙΣΜΟΣ ΣΦΑΛΜΑΤΩΝ: Αναλυτική παρακολούθηση τοπικής κατάστασης
• ΠΛΗΡΟΦΟΡΙΕΣ: Χειρισμός δραστηριότητας, κλήσεις API και αιτήσεις προς ή από εξωτερικές οντότητες
• ΠΡΟΕΙΔΟΠΟΙΗΣΗ: Απροσδόκητα συμβάντα που προκαλούν πιθανά προβλήματα
• ΣΦΑΛΜΑ: Σφάλματα που παρατηρήθηκαν, είτε εντοπίστηκαν είτε δεν εντοπίστηκαν

Κοινά πρότυπα μετανάστευσης

Απλό echo bot

Απλό echo bot στο Bot Framework 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}")

Απλό echo bot στο Agents SDK

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)

Bot για το Teams

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

Όλες οι μέθοδοι bot πρέπει να είναι async και να χρησιμοποιούνται await για ασύγχρονες λειτουργίες. Βεβαιωθείτε ότι όλες οι κλήσεις προς send_activity, οι λειτουργίες κατάστασης και οι λειτουργίες διαλόγου χρησιμοποιούν await.

Υποδείξεις κειμένου

Το Agents SDK χρησιμοποιεί εκτενώς υποδείξεις τύπου της Python. Εξετάστε το ενδεχόμενο να προσθέσετε υποδείξεις τύπου στον κώδικα του bot σας για καλύτερη υποστήριξη IDE και ανίχνευση σφαλμάτων:

from microsoft_agents.hosting.core import TurnContext

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

Επικύρωση διαμόρφωσης

Εάν το bot σας αποτύχει να ξεκινήσει λόγω σφαλμάτων ρύθμισης παραμέτρων, επαληθεύστε ότι τα ονόματα των μεταβλητών περιβάλλοντος χρησιμοποιούν τη σωστή σημειογραφία διπλής υπογράμμισης (__) και ότι έχετε ορίσει όλες τις απαιτούμενες τιμές.

Σφάλματα 401 κατά την τοπική διαδικασία εντοπισμού σφαλμάτων

Εάν δείτε σφάλματα 401 κατά τον τοπικό εντοπισμό σφαλμάτων χρησιμοποιώντας τον εξομοιωτή Bot Framework, βεβαιωθείτε ότι τα διαπιστευτήριά σας έχουν ρυθμιστεί σωστά στο .env αρχείο ή χρησιμοποιήστε τις ρυθμίσεις ελέγχου ταυτότητας του εξομοιωτή.

Συμβατότητα έκδοσης Python

Βεβαιωθείτε ότι χρησιμοποιείτε Python 3,10 ή νεότερη έκδοση. Το SDK Agents χρησιμοποιεί σύγχρονες Python δυνατότητες που δεν είναι διαθέσιμες σε προηγούμενες εκδόσεις.

Λίστα ελέγχου μετεγκατάστασης

✓ Ανάλυση και σχεδιασμός: Προσδιορίστε τυχόν καταργημένες λειτουργίες και αποφασίστε το εύρος μετεγκατάστασης έναντι ανακατασκευής. ✓ Επανάβαθμη έκδοση Python: Μετακίνηση σε Python 3,10 ή νεότερη έκδοση (συνιστάται 3,11+ ). ✓ Αντικατάσταση πακέτων: Κατάργηση botbuilder-*; προσθήκη microsoft-agents-* (hosting-core, activity, hosting-aiohttp, authentication-msal, storage providers, hosting-teams). ✓ Ενημέρωση εισαγωγών: Εφαρμογή εύρεσης/αντικατάστασης σύμφωνα με τους παραπάνω πίνακες. αλλάξτε όλα microsoft.agents σε microsoft_agents. ✓ Ενημέρωση τύπων και κλάσεων: Διορθώστε τα μετονομασμένα API και μετακινήστε TurnContext τις στατικές μεθόδους σε Activity μεθόδους παρουσίας. ✓ Ενημέρωση διαμόρφωσης: Δημιουργία.env αρχείου με ιεραρχική ονομασία (διπλές υπογράμμιση). ✓ Προετοιμασία ενημέρωσης: Χρήση CloudAdapter με MsalAuth.from_environment() και AgentsHttpMiddleware. ✓ Ρύθμιση καταγραφής: Ρυθμίστε την καταγραφή Python για το logger microsoft_agents. ✓ Δημιουργία και δοκιμή τοπικά: Χρησιμοποιήστε τον εξομοιωτή Bot Framework με διαπιστευτήρια. επικύρωση βασικών σεναρίων. ✓ Deploy και monitor: Ενημερώστε τις μεταβλητές περιβάλλοντος στο Azure για να ταιριάζουν με τη νέα ρύθμιση παραμέτρων και παρακολουθήστε τα αρχεία καταγραφής μετά την παράδοση.

Σχετικό περιεχόμενο

• Azure οδηγίες μετεγκατάστασης του Bot Framework SDK σε Agents SDK
• Οδηγίες μετεγκατάστασης του Azure Bot Framework SDK στο SDK παραγόντων Microsoft 365 για το .NET
• Οδηγίες μετεγκατάστασης από το Azure Bot Framework SDK στο SDK παραγόντων Microsoft 365 για Node.js