Panduan migrasi Azure Bot Framework SDK ke Agen SDK Microsoft 365 untuk Python

Artikel ini menjelaskan perubahan yang diperlukan untuk bermigrasi dari Bot Framework SDK untuk Python ke Agen SDK Microsoft 365 untuk Python.

Tip

Perlakukan pekerjaan ini sebagai upaya modernisasi, tidak hanya pertukaran paket. Agen SDK mendukung pola yang lebih sederhana dan tidak berpendapat (asinkron/tunggu, injeksi dependensi, pencatatan standar) dan menghapus fitur lama. Simpan hanya apa yang sebenarnya dibutuhkan bot Anda dan hindari membawa kompleksitas templat lama ke depan.

Prasyarat

• Python versi 3.10 atau yang lebih tinggi (3.11+ direkomendasikan, mendukung hingga 3.14)
• Proyek Bot Framework SDK yang ada
• sumber daya Azure Bot Service

Sumber daya Azure

Sumber daya Azure Anda yang ada tetap tidak berubah selama migrasi ini. Lanjutkan menggunakan pendaftaran Bot Azure Anda saat ini (ID Aplikasi dan rahasia). Anda mereferensikan nilai-nilai tersebut dalam struktur konfigurasi baru yang dijelaskan nanti. Banyak solusi juga menyertakan pengaturan aplikasi lama seperti APP_ID, APP_PASSWORD, dan APP_TENANT_ID. Entri ini tidak berbahaya selama migrasi tetapi Agen SDK Microsoft 365 tidak lagi menggunakannya. Anda dapat menghapus pengaturan ini setelah memvalidasi konfigurasi baru.

Langkah pertama

Mulailah dengan memperbarui dependensi paket. Perubahan berikut tidak mencakup setiap namespace yang mungkin perlu Anda sentuh, tetapi menangani sebagian besar pengganti paket.

Memperbarui dependensi paket

SDK Bot Framework	Agen SDK
botbuilder-core	microsoft-agents-hosting-core
botbuilder-schema	microsoft-agents-activity
botbuilder-azure	microsoft-agents-storage-blob dan microsoft-agents-storage-cosmos
botbuilder-integration-aiohttp	microsoft-agents-hosting-aiohttp

Jika bot Anda terintegrasi dengan Microsoft Teams, sertakan paket Ekstensi Teams microsoft-agents-hosting-teams untuk fitur Teams inti.

Untuk autentikasi, tambahkan microsoft-agents-authentication-msal untuk menangani autentikasi berbasis MSAL.

Perbarui requirements.txt atau file dependensi yang setara untuk mengganti paket Bot Framework dengan Agen SDK mereka yang setara. Gunakan pip install -r requirements.txt atau pengelola paket pilihan Anda untuk menginstal dependensi baru.

Agen SDK memberlakukan standar kualitas kode menggunakan black untuk pemformatan dan flake8 untuk linting. Pertimbangkan untuk menambahkan alat ini ke dependensi pengembangan Anda.

Memperbarui impor

Penting

Agents SDK menggunakan garis bawah di jalur impor (microsoft_agents) alih-alih titik (microsoft.agents). Perubahan ini memengaruhi semua impor.

Selanjutnya, perbarui impor. Pendekatan termudah adalah menemukan dan mengganti teks yang tepat di seluruh proyek.

Impor Kerangka Kerja Bot	Impor SDK Agen
from botbuilder.core import ...	from microsoft_agents.hosting.core import ...
from botbuilder.schema import ...	from microsoft_agents.activity import ...
from botbuilder.integration.aiohttp import ...	from microsoft_agents.hosting.aiohttp import ...
from botbuilder.core.teams import ...	from microsoft_agents.hosting.teams import ...

Penggantian nama jenis dan kelas

Beberapa jenis dan kelas memiliki nama yang berbeda di Agents SDK. Gunakan pemetaan berikut untuk memandu perubahan Anda.

Kerangka Kerja Bot	Agen SDK
BotState	AgentState
BotFrameworkAdapter	CloudAdapter
BotFrameworkHttpClient	AgentHttpClient
OAuthPromptSettings.connection_name	OAuthPromptSettings.azure_bot_oauth_connection_name

Perubahan kelas aktivitas

Activity Kelas di Agents SDK menyertakan validasi bawaan dengan menggunakan Pydantic. Anda dapat mengurai dan memvalidasi aktivitas dari JSON atau kamus dengan menggunakan Activity.model_validate().

Selain itu, kelas Activity memusatkan operasi yang terkait dengan muatan aktivitas. Metode yang sebelumnya adalah metode statis pada TurnContext sekarang menjadi metode instans pada Activity.

Metode Statis Kerangka Kerja Bot	Metode Instans Agen SDK
TurnContext.apply_conversation_reference()	activity.apply_conversation_reference()
TurnContext.get_conversation_reference()	activity.get_conversation_reference()
TurnContext.get_reply_conversation_reference()	activity.get_reply_conversation_reference()
TurnContext.remove_recipient_mention()	activity.remove_recipient_mention()
TurnContext.get_mentions()	activity.get_mentions()
TurnContext.remove_mention_text()	activity.remove_mention_text()

Perbarui referensi turn_state umum. Ganti penggunaan berikut sebagaimana mestinya.

Kerangka Kerja Bot	Agen SDK
turn_context.turn_state.get(ConnectorClient)	turn_context.services.get(ConnectorClient)
turn_context.turn_state.get(UserTokenClient)	turn_context.services.get(UserTokenClient)
turn_context.turn_state	turn_context.services

Konfigurasi

Agents SDK menggunakan variabel lingkungan dengan konvensi penamaan hierarkis untuk konfigurasi.

Variabel lingkungan

Buat atau perbarui file Anda .env dengan struktur berikut:

# 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

Catatan Migrasi: Perbarui nama variabel lingkungan Anda seperti yang diperlihatkan dalam tabel berikut:

SDK Bot Framework	Agen SDK
APP_ID atau MICROSOFT_APP_ID	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID
APP_PASSWORD atau MICROSOFT_APP_PASSWORD	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET
APP_TENANT_ID atau MICROSOFT_APP_TENANT_ID	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID

Konfigurasi Agents SDK menggunakan garis bawah ganda (__) untuk mewakili hierarki konfigurasi berlapis. Pola ini memungkinkan manajemen konfigurasi yang fleksibel di berbagai lingkungan penyebaran.

Startup dan inisialisasi

Inisialisasi berbeda di Agents SDK. Bot Framework SDK biasanya digunakan aiohttp dengan konfigurasi adaptor manual. Dengan menggunakan Agents SDK, Anda dapat menggunakan utilitas server bawaan untuk penyiapan yang disederhanakan.

Penyiapan server

Pendekatan 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)

Pendekatan Agen SDK (pola dekorator)

Pendekatan yang direkomendasikan menggunakan AgentApplication dengan dekorator untuk gaya deklaratif yang lebih modern.

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

Agents SDK menyediakan load_configuration_from_env() untuk memuat konfigurasi secara otomatis dari variabel lingkungan, menghilangkan penguraian konfigurasi manual. Pola dekorator memungkinkan Anda mendaftarkan penanganan secara deklaratif tanpa pewarisan berbasis kelas yang eksplisit.

Autentikasi dan keamanan

Bot Framework SDK menyertakan validasi JSON Web Token (JWT) dalam adaptor. Agents SDK memisahkan masalah autentikasi, sehingga Anda dapat mengonfigurasi middleware autentikasi secara eksplisit.

Untuk lingkungan produksi, pastikan validasi JWT diaktifkan melalui CloudAdapter konfigurasi. Adaptor secara otomatis memvalidasi permintaan masuk dengan menggunakan konfigurasi autentikasi MSAL.

Untuk pengembangan lokal dengan Bot Framework Emulator, Anda dapat menggunakan kredensial kosong di file .env:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

Penanganan aktivitas

Sebagian besar bot yang dibuat dengan Bot Framework SDK didasarkan pada ActivityHandler kelas dasar.

Agen SDK menyediakan ActivityHandler yang kompatibel dan mempertahankan antarmuka API yang sama untuk memudahkan migrasi.

Perbedaan utama

Perubahan tanda tangan metode penanganan

Handler SDK Kerangka Kerja Bot biasanya menggunakan parameter posisional, sedangkan handler SDK Agen mempertahankan pola yang sama dengan TurnContext sebagai parameter utama.

Metode tambahan di Agents SDK

Metode	Deskripsi
on_message_delete()	Menangani aktivitas penghapusan pesan
on_message_update()	Menangani aktivitas pembaruan pesan
on_sign_in_invoke()	Menangani aktivitas pemanggilan masuk

Metode yang tidak ditemukan pada Agents SDK

Metode	Reason
on_command_activity()	Aktivitas perintah tidak didukung
on_command_result_activity()	Aktivitas hasil perintah tidak didukung

Contoh migrasi

SDK Bot Framework

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

Agen 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

Migrasi sebagian besar mudah, dengan perubahan utama adalah pernyataan impor. Sebagian besar bot yang ada berbasis ActivityHandler bekerja dengan modifikasi minimal.

Manajemen status

ConversationState, UserState, dan PrivateConversationState kompatibel dengan beberapa perbedaan. Pola manajemen status inti mirip dengan SDK Bot Framework.

Anda harus mendaftarkan objek status dan menyimpannya secara eksplisit setelah modifikasi.

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)

Opsi penyimpanan

Agents SDK menyediakan implementasi penyimpanan untuk backend yang berbeda:

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

Pengelogan

Agents SDK menggunakan modul logging standar Python. Konfigurasikan pengelogan di file aplikasi utama Anda:

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)

Tingkat log

• DEBUG: Pelacakan status lokal secara menyeluruh
• INFO: Penanganan aktivitas, panggilan API, dan permintaan ke atau dari entitas eksternal
• PERINGATAN: Kejadian tak terduga yang menyebabkan potensi masalah
• ERROR: Kesalahan yang diamati, baik yang terdeteksi maupun yang tidak terdeteksi

Pola migrasi umum

Bot echo sederhana

Bot pembalas sederhana di 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 sederhana di 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}")

Manajemen status dengan penghitung

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

Pemecahan masalah dan tips

Kiat berikut mungkin membantu Anda menjadi lebih sukses.

Kesalahan impor

Jika Anda mengalami error impor, pastikan Anda menggunakan garis bawah (microsoft_agents), bukan titik (microsoft.agents) di semua pernyataan impor. Kesalahan ini adalah masalah migrasi yang paling umum.

Pola asinkron/tunggu

Semua metode bot harus async dan menggunakan await untuk operasi asinkron. Pastikan semua panggilan ke send_activity, operasi status, dan operasi dialog menggunakan await.

Ketik petunjuk

Agents SDK menggunakan petunjuk tipe Python secara ekstensif. Pertimbangkan untuk menambahkan petunjuk jenis ke kode bot Anda untuk dukungan IDE dan deteksi kesalahan yang lebih baik:

from microsoft_agents.hosting.core import TurnContext

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

Validasi konfigurasi

Jika bot Anda gagal memulai karena kesalahan konfigurasi, verifikasi nama variabel lingkungan Anda menggunakan notasi garis bawah ganda (__) yang benar dan Anda menetapkan semua nilai yang diperlukan.

Kesalahan 401 lokal selama debugging

Jika Anda melihat error 401 selama debugging lokal dengan menggunakan Bot Framework Emulator, verifikasi kredensial Anda dikonfigurasi dengan benar dalam .env file atau gunakan setelan autentikasi Emulator.

kompatibilitas versi Python

Pastikan Anda menggunakan Python 3.10 atau yang lebih tinggi. Agen SDK menggunakan fitur Python modern yang tidak tersedia di versi sebelumnya.

Daftar periksa migrasi

✓ Menganalisis dan merencanakan: Identifikasi fitur yang tidak digunakan lagi dan tentukan migrasi vs. membangun kembali cakupan. ✓ Mutakhirkan versi Python: Pindah ke Python 3,10 atau lebih tinggi (3,11+ direkomendasikan). ✓ Ganti paket: Hapus botbuilder-*; tambahkan microsoft-agents-* (hosting-core, aktivitas, hosting-aiohttp, authentication-msal, storage providers, hosting-teams). ✓ Perbarui impor: Terapkan temukan/ganti sesuai tabel di atas; ubah semua microsoft.agents menjadi microsoft_agents. ✓ Perbarui jenis dan kelas: Perbaiki API yang diganti namanya dan pindahkan TurnContext metode statis ke Activity metode instans. ✓ Perbarui konfigurasi: Buat file .env dengan penamaan hierarkis (garis bawah ganda). ✓ Inisialisasi perbarui: Gunakan CloudAdapter dengan MsalAuth.from_environment() dan AgentsHttpMiddleware. ✓ Konfigurasi pengelogan: Menyiapkan pengelogan Python untuk pencatat microsoft_agents. ✓ Bangun dan uji secara lokal: Gunakan Bot Framework Emulator dengan kredensial; Validasi skenario inti. ✓ Deploy dan monitor: Perbarui variabel lingkungan di Azure agar sesuai dengan konfigurasi baru dan tonton log setelah peluncuran.

Konten terkait

• Panduan migrasi dari Azure Bot Framework SDK ke Agents SDK
• Panduan migrasi Azure Bot Framework SDK ke Agen SDK Microsoft 365 untuk .NET
• Panduan migrasi Azure Bot Framework SDK ke Agen SDK Microsoft 365 untuk Node.js