הדרכת העברה מ-Azure Bot Framework SDK ל-Microsoft 365 Agents SDK עבור Python

מאמר זה מתאר את השינויים הדרושים להעברה מ- Bot Framework SDK עבור Python ל- Microsoft 365 Agents SDK for Python.

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

• Python גירסה 3.10 ואילך (מומלץ 3.11 ומעלה, תומכת ב- 3.14 ומעלה)
• פרוייקט SDK קיים של Bot Framework
• Azure Bot Service משאב

משאבים של Azure

המשאבים Azure שלך יישארו ללא שינוי במהלך העברה זו. יש להמשיך להשתמש ברישום Azure Bot הנוכחי (מזהה יישום ומפתח סודי). עליך להפנות לערכים אלה במבנה התצורה החדש המתואר מאוחר יותר. פתרונות רבים כוללים גם הגדרות אפליקציה מדור קודם, APP_IDכגון , APP_PASSWORDו- APP_TENANT_ID. ערכים אלה אינם מזיקים במהלך ההעברה, אך Microsoft 365 Agents SDK משתמש בהם עוד. באפשרותך להסיר הגדרות אלה לאחר אימות התצורה החדשה.

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

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

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

אם הבוט שלך משתלב עם Microsoft Teams, כלול את חבילת ההרחבות של Teams microsoft-agents-hosting-teams עבור תכונות ליבה של Teams.

עבור אימות, הוסף את microsoft-agents-authentication-msal כדי לטפל באימות מבוסס-MSAL.

עדכן את requirements.txt קובץ התלות שלך או את קובץ התלות המקביל כדי להחליף חבילות Bot Framework ב- Agents SDK המקבילות לו. השתמש pip install -r requirements.txt או במנהל החבילות המועדף עליך כדי להתקין את יחסי התלות החדשים.

ה-Agents SDK אוכף תקני איכות קוד באמצעות black לblackעיצוב ו-flake8 לflake8בדיקת lint. שקול להוסיף כלים אלה ליי תלות הפיתוח שלך.

עדכון ייבוא

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

שינוי שם של סוג ומחלקה

לחלק מהסוגים והמחלקות יש שמות שונים ב-Agents SDK. השתמש במיפויים הבאים כדי להדריך את השינויים שלך.

שינויים בכיתה של פעילות

המחלקה Activity ב- SDK Agents כוללת אימות מוכלל באמצעות Pydantic. באפשרותך לנתח ולאמת פעילויות מ- JSON או מ המילונים באמצעות Activity.model_validate().

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

עדכן הפניות turn_state נפוצות. החלף את השימושים הבאים בהתאם.

תצורה

ה- SDK Agents משתמש במשתנה סביבה עם מוסכמה הירארכית למתן שמות עבור תצורה.

משתני סביבה

צור או עדכן .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 Agents משתמשת במקף תחתון כפול (__) כדי לייצג הירארכיות תצורה מקוננות. תבנית זו מאפשרת ניהול תצורה גמיש בסביבות פריסה שונות.

אתחול והפעלה

האתחול שונה ב-Agents SDK. ה- SDK של Bot Framework משמש בדרך כלל aiohttp עם תצורת מתאם ידני. באמצעות ה- SDK Agents, באפשרותך להשתמש בכלי השירות המוכללים של השרת להגדרה פשוטה יותר.

הגדרת שרת

גישה ל- 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)

הגישה של Agents SDK (תבנית מעצב)

הגישה המומלצת משתמשת 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 של Bot Framework כלל אימות JSON Web Token (JWT) במתאם. ה- SDK של הסוכנים מפריד בין חששות לאימות, כך שבאפשרותך לקבוע תצורה של תוכנת ביניים של אימות באופן מפורש.

עבור בסביבות ייצור, ודא כי אימות JWT זמין באמצעות התצורה CloudAdapter . המתאם מאמת באופן אוטומטי בקשות נכנסות באמצעות תצורת אימות MSAL.

לפיתוח מקומי עם אמולטור Bot Framework, באפשרותך להשתמש באישורים ריקים בקובץ ה- .env שלך:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

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

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

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

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

שינויים בחתימת שיטת המטפל

מטפלים ב- SDK של Bot Framework משתמשים בדרך כלל בפרמטרים של מיקום, בעוד שמטפלים ב- Agents SDK TurnContext שומרים על אותה תבנית עם הפרמטר הראשי.

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

שיטות חסרות ב-Agents 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

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

ניהול סטייט

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 של הסוכנים מספק יישומי אחסון עבור קצה עורפי שונה:

# 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) משתמשת במודול הסטנדרטי 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)

רמות רישום

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

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

בוט אקו פשוט

בוט הד פשוט ב- 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}")

בוט הד פשוט ב- 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)

בוט של 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) בכל משפטי הייבוא. שגיאה זו היא בעיית ההעברה הנפוצה ביותר.

תבניות אסינכרונית/ממתינות

כל שיטות ה- Bot חייבות 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 מקומיות במהלך איתור באגים

אם אתה רואה 401 שגיאות במהלך איתור באגים מקומי באמצעות אמולטור Bot Framework, .env ודא שהתצורה של האישורים שלך נקבעה כראוי בקובץ או השתמש בהגדרות האימות של אמולטור.

Python תאימות גירסאות

ודא שאתה משתמש ב- Python 3.10 ואילך. ה- SDK Agents משתמש בתכונות Python מודרניות שאינן זמינות בגירסאות קודמות.

רשימת בדיקה להגירה

✓ ניתוח ותכנון: זהה תכונות שהוצאו משימוש והחלט על טווח ההעברה לעומת בנייה מחדש. ₪ שדרג גרסת Python: לשדרג ל-Python 3.10 או גרסה גבוהה יותר (3.11+ מומלץ). - החלף חבילות: הסר botbuilder-*; microsoft-agents-* הוסף (hosting-core, פעילות, hosting-aiohttp, authentication-msal, ספקי אחסון, hosting-teams). ₪ ייבוא עדכון: החל חיפוש/החלפה על כל הטבלאות לעיל; שנה הכל ל microsoft.agents - microsoft_agents. ✓ עדכון סוגים ומחלקות: תקן ממשקי API ששמם השתנה והעבר TurnContextשיטות סטטיות של TurnContext לשיטות מופע של Activity. • תצורת עדכון: צור .env קובץ עם שמות הירארכיים (מקפים תחתונים כפולים). - אתחול עדכון: השתמש עם CloudAdapter ו MsalAuth.from_environment() - AgentsHttpMiddleware. ₪ Configure logging: הגדר רישום Python עבור microsoft_agents logger. צורך לבנות ולבדוק באופן מקומי: השתמש באמולטור מסגרת Bot עם אישורים; לאמת תרחישי ליבה. ₪ פריסה וצג: עדכן משתני סביבה ב- Azure כך שיתאימו לתצורה החדשה וצפה ביומני הרישום לאחר הפריסה.

תוכן קשור

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