Azure Bot Framework SDK'den Microsoft 365 Aracıları SDK'sı'ye geçiş kılavuzu Python için

Bu makalede, Python için Bot Framework SDK'sından Python için Microsoft 365 Aracıları SDK'sı geçiş için gerekli değişiklikler açıklanmaktadır.

Tip

Bu çalışmayı yalnızca paket değiştirme işlemi değil, modernleştirme eforu olarak da değerlendirin. Agents SDK, daha basit ve görüş ayrımı olmayan kalıpları (asenkron/bekleme, bağımlılık enjeksiyonu, standart loglama) tercih eder ve eski özellikleri kaldırır. Yalnızca botunuzun gerçekten ihtiyaç duyduğu şeyleri koruyun ve eski şablon karmaşıklığını ileriye taşımaktan kaçının.

Önkoşullar

  • Python sürüm 3.10 veya üzeri (3.11+ önerilir, 3.14'e kadar destekler)
  • Mevcut Bot Framework SDK'sı projesi
  • Azure Bot Hizmeti kaynağı

Azure kaynakları

Mevcut Azure kaynaklarınız bu geçiş sırasında değişmeden kalır. Geçerli Azure Bot kaydınızı (Uygulama Kimliği ve gizli anahtar) kullanmaya devam edin. Bu değerleri daha sonra açıklanan yeni yapılandırma yapısında referans verirsiniz. Birçok çözüm ayrıca APP_ID, APP_PASSWORD ve APP_TENANT_ID gibi eski uygulama ayarlarını da içerir. Bu girdiler geçiş sırasında zararsızdır, ancak Microsoft 365 Aracıları SDK'sı bunları artık kullanmaz. Yeni yapılandırmayı doğruladıktan sonra bu ayarları kaldırabilirsiniz.

İlk adımlar

Paket bağımlılıklarını güncelleştirerek başlayın. Aşağıdaki değişiklikler, dokunmanız gerekebilecek tüm ad alanlarını kapsamaz, ancak çoğu paket değişikliğini işler.

Paket bağımlılıklarını güncelleştirme

Bot Framework SDK'sı Aracıları SDK'sı
botbuilder-core microsoft-agents-hosting-core
botbuilder-schema microsoft-agents-activity
botbuilder-azure microsoft-agents-storage-blob ve microsoft-agents-storage-cosmos
botbuilder-integration-aiohttp microsoft-agents-hosting-aiohttp

Botunuz Microsoft Teams ile tümleştirildiyse, temel Teams özellikleri için Teams Uzantısı paketini microsoft-agents-hosting-teams ekleyin.

Kimlik doğrulama için, MSAL tabanlı kimlik doğrulamayı ele almak adına microsoft-agents-authentication-msal ekleyin.

Kendi requirements.txt veya eşdeğer bağımlılık dosyanızı Bot Framework paketlerini Agent SDK eşdeğerleriyle değiştirecek şekilde güncelleyin. pip install -r requirements.txt Yeni bağımlılıkları kurmak için tercih ettiğiniz paket yöneticisini kullanın.

Agents SDK, kod kalite standartlarını, biçimlendirme için black ve linting için flake8 kullanarak uygular. Bu araçları geliştirme bağımlılıklarınıza eklemeyi düşünün.

İçeri aktarmaları güncelleştirme

Important

Agents SDK, import yollarında (microsoft_agents) nokta (microsoft.agents) yerine alt çizgiler kullanır. Bu değişiklik tüm ithalatları etkiler.

Ayrıca, importları güncelleyin. En kolay yaklaşım, tam metni proje çapında bulup değiştirmektir.

Bot Framework İçeri Aktarma Agents SDK Aktarımı
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 ...

Tür ve sınıf isimlerinin yeniden değiştirilmesi

Bazı türler ve sınıflar Agents SDK'da farklı isimlere sahiptir. Değişikliklerinizi yönlendirmek için aşağıdaki haritalamaları kullanın.

Bot Framework Aracıları SDK'sı
BotState AgentState
BotFrameworkAdapter CloudAdapter
BotFrameworkHttpClient AgentHttpClient
OAuthPromptSettings.connection_name OAuthPromptSettings.azure_bot_oauth_connection_name

Etkinlik sınıfı değişiklikleri

Agents SDK'daki sınıf, ActivityPydantic kullanılarak yerleşik doğrulama içerir. JSON veya sözlüklerden aktiviteleri ayrıştırıp doğrulayabilirsiniz.Activity.model_validate()

Ayrıca, Activity sınıf faaliyet yükleriyle ilgili işlemleri merkezileştirir. Daha önce TurnContext üzerinde statik yöntemler olan yöntemler şimdi Activity üzerinde örnek yöntemlerdir.

Bot Çerçevesi Statik Yöntemi Aracılar SDK'sı Örnek Yöntemi
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()

Yaygın turn_state başvuruları güncelleştirin. Aşağıdaki kullanımları uygun şekilde değiştirin.

Bot Framework Aracıları SDK'sı
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

Yapılandırma

Ajan SDK, yapılandırma için hiyerarşik bir adlandırma konvensiyası olan ortam değişkenleri kullanır.

Ortam değişkenleri

Dosyanızı .env aşağıdaki yapıda oluşturun veya güncelleyin:

# 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

Geçiş Notu: Ortam değişkeni adlarınızı aşağıdaki tabloda gösterildiği gibi güncelleştirin:

Bot Framework SDK'sı Aracıları SDK'sı
APP_ID veya MICROSOFT_APP_ID CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID
APP_PASSWORD veya MICROSOFT_APP_PASSWORD CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET
APP_TENANT_ID veya MICROSOFT_APP_TENANT_ID CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID

Agents SDK yapılandırması, iç içe konfigürasyon hiyerarşilerini temsil etmek için çift alt çizgiler (__) kullanır. Bu desen, farklı dağıtım ortamlarında esnek yapılandırma yönetimi sağlar.

Başlangıç ve başlatma

Başlatma Agents SDK'da farklıdır. Bot Framework SDK genellikle manuel adaptör yapılandırmasıyla kullanılır aiohttp . Agents SDK'yı kullanarak, yerleşik sunucu araçlarını basitleştirilmiş kurulum için kullanabilirsiniz.

Sunucu kurulumu

Bot Framework SDK yaklaşımı

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)

Aracılar SDK'sı yaklaşımı (dekoratör deseni)

Önerilen yaklaşım, daha modern ve bildirimsel bir stil için dekoratörlerle birlikte AgentApplication kullanır:

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 load_configuration_from_env() , ortam değişkenlerinden otomatik olarak yapılandırma yükleme sağlar ve manuel yapılandırma ayrıştırmasını ortadan kaldırır. Decorator modeli, işleyicileri açık sınıf tabanlı miras olmadan deklaratif olarak kaydetmenize olanak tanır.

Kimlik doğrulaması ve güvenlik

Bot Framework SDK, adaptörde JSON Web Token (JWT) doğrulamasını içeriyordu. Agents SDK, kimlik doğrulama endişelerini ayırır, böylece kimlik doğrulama ara yazılımını açıkça yapılandırmak mümkündür.

Üretim ortamları için, yapılandırma yoluyla JWT doğrulamasının etkinleştirildiğinden CloudAdapter emin olun. Adaptör, gelen isteği, MSAL kimlik doğrulama yapılandırmasını kullanarak otomatik olarak doğrular.

Bot Framework Emulator ile yerel geliştirme için, .env dosyanızdaki boş kimlik bilgilerini kullanabilirsiniz:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

Etkinlik yönetimi

Bot Framework SDK ile oluşturulan botların çoğu ActivityHandler temel sınıfını temel alır.

Agents SDK, daha kolay geçiş için benzer bir API yüzeyi koruyan uyumlu ActivityHandler bir sistem sunar.

Önemli farklar

Handler yöntemi imza değişiklikleri

Bot Framework SDK işleyicileri tipik olarak konumsal parametreler kullanırken, Agents SDK işleyicileri birincil parametre TurnContext ile aynı deseni korur.

Agents SDK'da Ek Yöntemler

Yöntem Description
on_message_delete() Mesaj silme etkinliklerini yönetir
on_message_update() İleti güncelleştirme etkinliklerini yönetir
on_sign_in_invoke() Oturum açma çağırma etkinliklerini işler

Agents SDK'da eksik yöntemler

Yöntem Nedeni
on_command_activity() Komut etkinlikleri desteklenmiyor
on_command_result_activity() Komut sonucu etkinlikleri desteklenmiyor

Geçiş örneği

Bot Framework SDK'sı

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

Aracıları SDK'sı

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

Göç işlemi çoğunlukla basittir, ana değişiklikler ise import ifadeleridir. Mevcut ActivityHandlertabanlı botların çoğu minimum modifikasyonla çalışır.

Durum yönetimi

ConversationState, UserState ve PrivateConversationState birkaç farkla uyumludur. Temel durum yönetim kalıpları Bot Framework SDK'ya benzer.

Durum nesnelerini kaydetmeli ve değişikliklerden sonra açıkça kaydetmelisiniz.

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)

Depolama seçenekleri

Agents SDK, farklı arka uçlar için depolama uygulamaları sağlar:

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

Logging

Aracılar SDK'sı Python standart logging modülünü kullanır. Ana uygulama dosyanızda logiyi yapılandırın:

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)

Günlük düzeyleri

  • DEBUG: Detaylı yerel durum takibi
  • BILGI: Etkinlik işleme, API çağrıları ve dış varlıklara veya kuruluşlardan gelen istekler
  • UYARI: Potansiyel sorunlara yol açan beklenmedik olaylar
  • HATA: Gözlemlenen hatalar, yakalanmış olsun ya da olmasın

Yaygın geçiş desenleri

Temel "echo bot"

Bot Framework SDK'da basit echo bot

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'da basit echo bot

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

Sayaçlı devlet yönetimi

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 botu

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

Sorun giderme ve ipuçları

Aşağıdaki ipuçları daha başarılı olmanıza yardımcı olabilir.

İtiş hataları

Eğer içe aktarma hatalarıyla karşılaşırsanız, tüm içe aktarma ifadelerinde nokta (microsoft_agents) yerine alt çizgi (microsoft.agents) kullandığınızdan emin olun. Bu hata, en yaygın göç sorunudur.

Asenkron/await kalıpları

Tüm bot yöntemleri async ve await asenkron işlemler için kullanılmalıdır. Çağrıların, durum işlemlerinin ve diyalog işlemlerinin send_activity kullanarak await ile gerçekleştirilmesini sağlayın.

Tür ipuçları

Aracılar SDK'sı Python tür ipuçlarını kapsamlı olarak kullanır. Daha iyi IDE desteği ve hata tespiti için bot koduna tip ipuçları eklemeyi düşünün:

from microsoft_agents.hosting.core import TurnContext

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

Yapılandırma doğrulaması

Botunuz yapılandırma hataları nedeniyle başlatılamıyorsa, ortam değişkeni adlarınızda doğru çift alt çizgi (__) biçiminin kullanıldığını ve gerekli tüm değerlerin ayarlandığını kontrol edin.

Hata ayıklama sırasında yerel 401 hataları

Bot Framework Emülatörü kullanarak yerel hata ayıklama sırasında 401 hatası görürseniz, kimlik bilgilerinizin dosyada .env doğru yapılandırıldığından emin olun veya Emülatörün kimlik doğrulama ayarlarını kullanın.

Python sürüm uyumluluğu

Python 3.10 veya üzerini kullandığınızdan emin olun. Aracılar SDK'sı, önceki sürümlerde bulunmayan modern Python özelliklerini kullanır.

Geçiş denetim listesi

✓ Analiz et ve plan yap: Kullanımdan aşağı düşen özellikleri tespit et ve göç mi yoksa yeniden inşa kapsamını da değerlendir. ✓ Python sürümünü yükseltin: Python 3.10 veya üzeri bir sürüme geçin (3.11+ önerilir). ✓ Paketleri değiştir: Kaldır botbuilder-*; ekle microsoft-agents-* (hosting-core, activity, hosting-aiohttp, authentication-msal, depolama sağlayıcıları, hosting-teams). ✓ İçe aktarmaları güncelle: Yukarıdaki tablolara göre bulma/değiştirme uygula; hepsini microsoft.agents 'ye microsoft_agentsdeğiştirin. ✓ Türleri ve sınıfları güncelleyin: Yeniden adlandırılan API'leri düzeltin ve statik metotları örnek TurnContext metotlara taşıyınActivity. ✓ Yapılandırmayı güncelle: Çift alt çizgi kullanarak hiyerarşik adlandırmalı bir .env dosyası oluşturun. ✓ Başlatmayı güncelle: CloudAdapter'i MsalAuth.from_environment() ve AgentsHttpMiddleware ile kullanın. ✓ Günlüğü yapılandır: Python için microsoft_agents günlük kaydediciyi ayarlayın. ✓ Yerel olarak oluştur ve test et: Bot Framework Emulator'u kimlik bilgileriyle kullanın; Temel senaryoları doğrulayın. ✓ Dağıt ve izle: Azure ortam değişkenlerini yeni yapılandırmayla eşleşecek şekilde güncelleyin ve dağıtım tamamlandıktan sonra günlükleri izleyin.

İlgili içerik

  • Last updated on