Azure Bot Framework SDK zum Microsoft 365 Agents SDK Migrationsleitfaden für Python

In diesem Artikel werden die erforderlichen Änderungen beschrieben, die vorgenommen werden müssen, um vom Bot Framework SDK für Python auf das Microsoft 365 Agents SDK für Python zu migrieren.

Tipp

Behandeln Sie diese Arbeit als Modernisierungsaufwand, nicht nur als Pakettausch. Das Agents SDK bevorzugt einfachere, unbestimmte Muster (asynchron/erwarten, Abhängigkeitsinjektion, Standard-Protokollierung) und entfernt Legacy-Funktionen. Halten Sie nur das, was Ihr Bot tatsächlich benötigt, und vermeiden Sie, alte Vorlagenkomplexität voranzutreiben.

Voraussetzungen

• Python Version 3.10 oder höher (3.11+ empfohlen, unterstützt bis zu 3,14)
• Vorhandenes Bot Framework SDK-Projekt
• Azure Bot Service Ressource

ressourcen Azure

Ihre vorhandenen Azure Ressourcen bleiben während dieser Migration unverändert. Verwenden Sie weiterhin Ihre aktuelle Azure Bot-Registrierung (App-ID und geheimer Schlüssel). Du beziehst dich auf diese Werte in der später beschriebenen neuen Konfigurationsstruktur. Viele Lösungen beinhalten auch Legacy-App-Einstellungen wie APP_ID, APP_PASSWORD, und APP_TENANT_ID. Diese Einträge sind während der Migration harmlos, aber die Microsoft 365 Agents SDK verwenden sie nicht mehr. Du kannst diese Einstellungen entfernen, nachdem du die neue Konfiguration überprüft hast.

Erste Schritte

Beginnen Sie, indem Sie Paketabhängigkeiten aktualisieren. Die folgenden Änderungen behandeln nicht jeden Namespace, den Sie möglicherweise berühren müssen, aber sie behandeln die meisten Paketersetzungen.

Aktualisieren von Paketabhängigkeiten

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

Wenn Ihr Bot in Microsoft Teams integriert ist, schließen Sie das Teams-Erweiterungspaket microsoft-agents-hosting-teams für die wichtigsten Microsoft Teams-Features ein.

Für die Authentifizierung fügen Sie microsoft-agents-authentication-msal hinzu, um die MSAL-basierte Authentifizierung zu verwalten.

Aktualisieren Sie Ihre requirements.txt- oder eine entsprechende Abhängigkeitsdatei, um Bot-Framework-Pakete durch deren Agents-SDK-Äquivalente zu ersetzen. Verwenden Sie pip install -r requirements.txt oder Ihren bevorzugten Paketmanager, um die neuen Abhängigkeiten zu installieren.

Das Agents SDK setzt Code-Qualitätsstandards durch, indem es black für die Formatierung und flake8 für das Linting verwendet. Überlegen Sie, diese Werkzeuge zu Ihren Entwicklungsabhängigkeiten hinzuzufügen.

Importe aktualisieren

Von Bedeutung

Das Agents SDK verwendet Unterzeichen in Importpfaden (microsoft_agents) anstelle von Punkten (microsoft.agents). Diese Änderung betrifft alle Importe.

Als Nächstes: Aktualisierung der Importe. Der einfachste Ansatz ist ein projektweites Suchen und Ersetzen des exakten Textes.

Bot-Framework-Import	Agents-SDK-Import
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 ...

Umbenennungen von Typ und Klasse

Einige Typen und Klassen haben im Agents SDK unterschiedliche Namen. Verwenden Sie die folgenden Zuordnungen, um Ihre Änderungen zu steuern.

Bot Framework	Agenten-SDK
BotState	AgentState
BotFrameworkAdapter	CloudAdapter
BotFrameworkHttpClient	AgentHttpClient
OAuthPromptSettings.connection_name	OAuthPromptSettings.azure_bot_oauth_connection_name

Änderungen der Aktivitätsklassen

Die Activity Klasse im Agents SDK enthält eine integrierte Validierung mittels Pydantic. Sie können Aktivitäten aus JSON oder Wörterbüchern parsen und validieren, indem Sie Activity.model_validate() verwenden.

Zusätzlich zentralisiert die Klasse Activity Operationen im Zusammenhang mit Aktivitätsnutzlasten. Methoden, die zuvor statische Methoden auf TurnContext waren, sind jetzt Instanzmethoden auf Activity:

Bot Framework Statische Methode	Agents SDK Instanzmethode
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()

Aktualisieren allgemeiner turn_state Verweise. Ersetzen Sie die folgenden Verwendungen entsprechend.

Bot Framework	Agenten-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

Konfiguration

Das Agents SDK verwendet Umgebungsvariablen mit einer hierarchischen Namenskonvention für die Konfiguration.

Umgebungsvariablen

Erstellen oder aktualisieren Sie Ihre .env Datei mit folgender Struktur:

# 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

Migrationshinweis: Aktualisieren Sie die Namen ihrer Umgebungsvariablen, wie in der folgenden Tabelle dargestellt:

Bot Framework-SDK	Agenten-SDK
APP_ID oder MICROSOFT_APP_ID	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID
APP_PASSWORD oder MICROSOFT_APP_PASSWORD	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET
APP_TENANT_ID oder MICROSOFT_APP_TENANT_ID	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID

Die Agents SDK-Konfiguration verwendet doppelte Unterstriche (__), um verschachtelte Konfigurationshierarchien darzustellen. Dieses Muster ermöglicht ein flexibles Konfigurationsmanagement über verschiedene Deployment-Umgebungen hinweg.

Start und Initialisierung

Die Initialisierung unterscheidet sich im Agents SDK. Das Bot Framework SDK wird typischerweise mit manueller Adapterkonfiguration verwendet aiohttp . Mit dem Agents SDK können Sie die integrierten Server-Utilities für eine vereinfachte Einrichtung nutzen.

Serveraufbau

Bot-Framework-SDK-Ansatz

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-Ansatz (Decorator-Muster)

Der empfohlene Ansatz verwendet die AgentApplication mit Dekoratoren für einen moderneren und deklarativen Stil:

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

Das Agents SDK ermöglicht load_configuration_from_env() es, automatisch Konfigurationen aus Umgebungsvariablen zu laden, wodurch manuelles Konfigurationsparsen entfällt. Das Decorator-Muster erlaubt es, Handler deklarativ zu registrieren, ohne explizite klassenbasierte Vererbung.

Authentifizierung und Sicherheit

Das Bot Framework SDK enthielt die JSON Web Token (JWT)-Validierung im Adapter. Das Agents SDK trennt Authentifizierungsprobleme, sodass man die Authentifizierungs-Middleware explizit konfigurieren kann.

Für Produktionsumgebungen sollten Sie sicherstellen, dass die JWT-Validierung durch die Konfiguration CloudAdapter aktiviert ist. Der Adapter validiert automatisch eingehende Anfragen mithilfe der MSAL-Authentifizierungskonfiguration.

Für die lokale Entwicklung mit dem Bot Framework Emulator können Sie leere Zugangsdaten in Ihrer .env-Datei verwenden:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

Umgang mit Aktivitäten

Die meisten Bots, die mit dem Bot Framework SDK erstellt wurden, basieren auf der ActivityHandler Basisklasse.

Das Agents SDK bietet eine kompatible ActivityHandler Plattform, die eine ähnliche API-Oberfläche für eine einfachere Migration beibehält.

Wichtige Unterschiede

Änderungen der Handler-Methodensignatur

Bot-Framework-SDK-Handler verwenden typischerweise positionsbezogene Parameter, während Agents-SDK-Handler das gleiche Muster mit TurnContext als primären Parameter beibehalten.

Zusätzliche Methoden im Agents SDK

Methode	Description
on_message_delete()	Behandelt Nachrichtenlöschaktivitäten
on_message_update()	Behandelt Nachrichtenaktualisierungsaktivitäten
on_sign_in_invoke()	Behandelt Anmelde-Aufrufaktivitäten

Fehlende Methoden im Agents SDK

Methode	Ursache
on_command_activity()	Befehlsaktivitäten werden nicht unterstützt
on_command_result_activity()	Befehlsergebnisaktivitäten werden nicht unterstützt

Migrationsbeispiel

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

Agenten-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

Die Migration ist größtenteils unkompliziert, wobei die Hauptänderungen die Importanweisungen sind. Die meisten bestehenden ActivityHandlerBots funktionieren mit minimalen Modifikationen.

Zustandsverwaltung

ConversationState, UserStateund PrivateConversationState sind mit einigen Unterschieden kompatibel. Die Kern-Zustandsmanagementmuster ähneln dem Bot Framework SDK.

Du musst Zustandsobjekte registrieren und sie nach Änderungen explizit speichern.

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)

Speicheroptionen

Das Agents SDK bietet Speicherimplementierungen für verschiedene Backends:

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

Protokollierung

Das Agents SDK verwendet Python Standardmodul logging. Konfigurieren Sie das Logging in Ihrer Hauptanwendungsdatei:

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)

Protokollebenen

• DEBUG: Ausführliche lokale Statusverfolgung
• INFO: Aktivitätshandhabung, API-Aufrufe und Anfragen an oder von externen Akteuren
• WARNUNG: Unerwartete Ereignisse, die potenzielle Probleme verursachen
• FEHLER: Beobachtete Fehler, ob entdeckt oder nicht entdeckt

Allgemeine Migrationsmuster

Einfacher Echo-Bot

Einfacher Echo-Bot im 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}")

Einfacher Echo-Bot im 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}")

Staatsverwaltung mit Zähler

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-Bot

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

Problembehandlung und Tipps

Die folgenden Tipps können Ihnen helfen, erfolgreicher zu sein.

Importfehler

Wenn du auf Importfehler stößt, stelle sicher, dass du in allen Importanweisungen Unterstreiche (microsoft_agents) statt Punkte (microsoft.agents) verwendest. Dieser Fehler ist das häufigste Migrationsproblem.

Async/Wait-Muster strukturieren

Alle Botmethoden müssen async und await für asynchrone Operationen nutzen. Stellen Sie sicher, dass alle Aufrufe zu send_activity sowie Zustandsoperationen und Dialogoperationen await verwenden.

Typ-Hinweise

Das Agents SDK verwendet Python Typhinweise umfassend. Überlege, Typhinweise in deinen Bot-Code einzubauen, um die IDE-Unterstützung und Fehlererkennung zu verbessern:

from microsoft_agents.hosting.core import TurnContext

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

Konfigurationsüberprüfung

Wenn dein Bot aufgrund von Konfigurationsfehlern nicht startet, überprüfe, ob deine Umgebungsvariablennamen die korrekte Doppel-Unterstrich-(__)-Notation verwenden und dass du alle erforderlichen Werte gesetzt hast.

Lokale 401-Fehler beim Debuggen

Wenn Sie beim lokalen Debugging mit dem Bot Framework Emulator 401-Fehler sehen, überprüfen Sie, ob Ihre Zugangsdaten in der .env Datei korrekt konfiguriert sind oder verwenden Sie die Authentifizierungseinstellungen des Emulators.

Python Versionskompatibilität

Stellen Sie sicher, dass Sie Python 3.10 oder höher verwenden. Das Agents SDK verwendet moderne Python Features, die in früheren Versionen nicht verfügbar sind.

Migrationscheckliste

✓ Analysieren und planen: Identifizieren Sie alle veralteten Funktionen und entscheiden Sie sich über Migration vs. Neuaufbau. ► Upgrade Python Version: Wechseln sie zu Python 3,10 oder höher (3,11+ empfohlen). ✓ Pakete ersetzen: Entfernen botbuilder-*; Hinzufügen microsoft-agents-* (hosting-core, activity, hosting-aiohttp, authentication-msal, Speicheranbieter, hosting-teams). ✓ Importe aktualisieren: Suchen/ersetzen gemäß den obigen Tabellen anwenden; Ändere alle microsoft.agents zu microsoft_agents. ✓ Aktualisieren Sie Typen und Klassen: Ändern Sie umbenannte APIs und übertragen TurnContext Sie statische Methoden auf Activity Instanzmethoden. ✓ Konfiguration aktualisieren: Datei mit hierarchischer Benennung erstellen .env (doppelte Unterstreichung). ✓ Aktualisierungsinitialisierung: Verwenden Sie CloudAdapter mit MsalAuth.from_environment() und AgentsHttpMiddleware. ► Konfigurationsprotokollierung: Richten Sie Python Protokollierung für microsoft_agents Logger ein. ✓ Lokal bauen und testen: Verwenden Sie den Bot Framework Emulator mit Zugangsdaten; Validiere Kernszenarien. ► Deploy and monitor: Aktualisieren Sie Umgebungsvariablen in Azure, um die neue Konfiguration abzugleichen und Protokolle nach dem Rollout zu überwachen.

Verwandte Inhalte

• Azure Bot Framework SDK zu Agents SDK-Migrationsleitfaden
• Azure Bot Framework SDK zum Microsoft 365 Agents SDK Migrationsleitfaden für .NET
• Azure Bot Framework SDK zum Microsoft 365 Agents SDK Migrationsleitfaden für Node.js