Guide de migration du Kit de développement logiciel Azure Bot Framework vers Microsoft 365 Agents SDK pour Python

Cet article décrit les modifications requises pour migrer du Kit de développement logiciel (SDK) Bot Framework pour Python vers le Microsoft 365 Agents SDK pour Python.

Tip

Traitez ce travail comme un effort de modernisation, pas seulement un échange de packages. Le SDK des agents privilégie des schémas plus simples et sans opinion (async/await, injection de dépendances, journalisation standard) et supprime les fonctionnalités héritées. Ne conservez que ce dont votre bot a réellement besoin et évitez d’emporter avec vous la complexité inutile des anciens modèles.

Prerequisites

• Python version 3.10 ou ultérieure (3.11+ recommandé, prend en charge jusqu’à 3.14)
• Projet sdk Bot Framework existant
• ressource Azure Bot Service

Ressources Azure

Vos ressources Azure existantes restent inchangées pendant cette migration. Continuez à utiliser votre inscription de bot Azure actuelle (ID d’application et secret). Vous faites référence à ces valeurs dans la nouvelle structure de configuration décrite plus loin. De nombreuses solutions incluent également des paramètres d’applications anciennes tels que APP_ID, APP_PASSWORD, et APP_TENANT_ID. Ces entrées sont inoffensives pendant la migration, mais les Microsoft 365 Agents SDK ne les utilisent plus. Vous pouvez supprimer ces paramètres après avoir validé la nouvelle configuration.

Premières étapes

Commencez par mettre à jour les dépendances de package. Les modifications suivantes ne couvrent pas tous les espaces de noms que vous pourriez avoir à modifier, mais elles gèrent la plupart des remplacements de packages.

Mettre à jour les dépendances de package

Kit de développement logiciel (SDK) Bot Framework	Kit de développement logiciel (SDK) Agents
botbuilder-core	microsoft-agents-hosting-core
botbuilder-schema	microsoft-agents-activity
botbuilder-azure	microsoft-agents-storage-blob et microsoft-agents-storage-cosmos
botbuilder-integration-aiohttp	microsoft-agents-hosting-aiohttp

Si votre bot s’intègre à Microsoft Teams, incluez le package d’extension Teams microsoft-agents-hosting-teams pour les fonctionnalités principales de Teams.

Pour l’authentification, ajoutez microsoft-agents-authentication-msal pour gérer l’authentification basée sur MSAL.

Mettez à jour le fichier de dépendance requirements.txt ou un fichier équivalent pour remplacer les paquets Bot Framework par leurs équivalents Agents SDK. Utilisez pip install -r requirements.txt ou votre gestionnaire de paquets préféré pour installer les nouvelles dépendances.

Le SDK des agents applique les normes de qualité du code en utilisant black pour la mise en forme et flake8 pour le linting. Envisagez d’ajouter ces outils à vos dépendances de développement.

Mettre à jour les importations

Important

Le SDK des agents utilise des soulignements dans les chemins d’importation (microsoft_agents) au lieu de points (microsoft.agents). Ce changement affecte toutes les importations.

Ensuite, mettez à jour les importations. La solution la plus simple consiste à rechercher et remplacer le texte exact à l’échelle du projet.

Importation du Bot Framework	Importation du SDK des assistants
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 ...

Renoms de types et de classes

Certains types et classes portent des noms différents dans le SDK des agents. Utilisez les mappages suivants pour guider vos modifications.

Bot Framework	Kit de développement logiciel (SDK) Agents
BotState	AgentState
BotFrameworkAdapter	CloudAdapter
BotFrameworkHttpClient	AgentHttpClient
OAuthPromptSettings.connection_name	OAuthPromptSettings.azure_bot_oauth_connection_name

Changements de classe d’activité

La Activity classe du SDK Agents inclut une validation intégrée en utilisant Pydantic. Vous pouvez analyser et valider des activités à partir de JSON ou de dictionnaires en utilisant Activity.model_validate().

De plus, la Activity classe centralise les opérations liées aux charges utiles d’activité. Les méthodes qui étaient auparavant des méthodes statiques sur TurnContext sont désormais des méthodes d’instance sur Activity:

Méthode statique du Bot Framework	Méthode d’instance SDK des assistants
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()

Mettez à jour les références courantes turn_state. Remplacez les utilisations suivantes en conséquence.

Bot Framework	Kit de développement logiciel (SDK) Agents
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

Paramétrage

Le SDK Agents utilise des variables d’environnement avec une convention de nommage hiérarchique pour la configuration.

Variables d’environnement

Créez ou mettez à jour votre .env fichier avec la structure suivante :

# 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

Remarque de migration : Mettez à jour les noms de vos variables d’environnement, comme indiqué dans le tableau suivant :

Kit de développement logiciel (SDK) Bot Framework	Kit de développement logiciel (SDK) Agents
APP_ID ou MICROSOFT_APP_ID	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID
APP_PASSWORD ou MICROSOFT_APP_PASSWORD	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET
APP_TENANT_ID ou MICROSOFT_APP_TENANT_ID	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID

La configuration de l'Agents SDK utilise des doubles traits de soulignement (__) pour représenter des hiérarchies de configuration imbriquées. Ce schéma permet une gestion de configuration flexible à travers différents environnements de déploiement.

Démarrage et initialisation

L’initialisation diffère dans le SDK Agents. Le SDK Bot Framework est généralement utilisé aiohttp avec la configuration manuelle de l’adaptateur. En utilisant le SDK des agents, vous pouvez utiliser les utilitaires serveur intégrés pour simplifier la configuration.

Configuration du serveur

Approche du SDK du Bot Framework

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)

Approche SDK des agents (motif décorateur)

L’approche recommandée utilise le AgentApplication avec des décorateurs pour un style plus moderne et déclaratif :

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

Le SDK des agents permet load_configuration_from_env() de charger automatiquement la configuration à partir des variables d’environnement, éliminant ainsi l’analyse manuelle de configuration. Le modèle décorateur permet d’enregistrer les manipulateurs de manière déclarative sans héritage explicite basé sur la classe.

Authentification et sécurité

Le SDK Bot Framework incluait la validation JSON Web Token (JWT) dans l’adaptateur. Le SDK des agents sépare les préoccupations liées à l’authentification, donc vous pouvez configurer explicitement le middleware d’authentification.

Pour les environnements de production, assurez-vous que la validation JWT est activée via la CloudAdapter configuration. L’adaptateur valide automatiquement les requêtes entrantes en utilisant la configuration d’authentification MSAL.

Pour le développement local avec l’émulateur Bot Framework, vous pouvez utiliser des identifiants vides dans votre fichier .env :

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

Gestion des activités

La plupart des bots créés avec le Kit de développement logiciel (SDK) Bot Framework sont basés sur la classe de ActivityHandler base.

Le SDK des agents fournit un élément compatible ActivityHandler qui maintient une surface API similaire pour faciliter la migration.

Principales différences

Modifications de la signature de la méthode du gestionnaire

Les gestionnaires SDK du Bot Framework utilisent généralement des paramètres positionnels, tandis que les gestionnaires SDK des agents maintiennent le même schéma avec TurnContext que paramètre principal.

Méthodes supplémentaires dans Agents SDK

Méthode	Description
on_message_delete()	Gère les activités de suppression de messages
on_message_update()	Gère les activités de mise à jour des messages
on_sign_in_invoke()	Gère les activités d’invocation pour la connexion

Méthodes manquantes dans le SDK des agents

Méthode	Motif
on_command_activity()	Les activités de commande ne sont pas prises en charge
on_command_result_activity()	Les activités de résultat de commande ne sont pas prises en charge

Exemple de migration

Kit de développement logiciel (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!")

Kit de développement logiciel (SDK) Agents

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

La migration est globalement simple, les principaux changements étant les déclarations d’importation. La plupart des bots existants ActivityHandlerfonctionnent avec des modifications minimales.

Gestion de l'état

ConversationState, UserStateet PrivateConversationState sont compatibles avec quelques différences. Les schémas de gestion de l’état central sont similaires au SDK Bot Framework.

Vous devez enregistrer les objets d’état et les sauvegarder explicitement après modifications.

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)

Options de stockage

Le SDK des agents fournit des implémentations de stockage pour différents 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"
)

Exploitation forestière

Le Kit de développement logiciel (SDK) Agents utilise le module logging standard de Python. Configurez la connexion dans votre fichier principal d’application :

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)

Niveaux de journalisation

• DÉBOGAGE : suivi de l’état local avec verbosité
• INFO : Gestion des activités, appels API et requêtes vers ou depuis des entités externes
• AVERTISSEMENT : Événements imprévus qui causent des problèmes potentiels
• ERREUR : Erreurs observées, qu’elles aient été détectées ou non

Modèles de migration courants

Bot d’écho simple

Simple echo bot dans le SDK du Bot Framework

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

Bot simple d'écho dans le SDK Agents

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

Gestion de l’état avec compteur

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

Résolution des problèmes et conseils

Les conseils suivants peuvent vous aider à mieux réussir.

Erreurs d’importation

Si vous rencontrez des erreurs d’importation, assurez-vous d’utiliser des soulignements (microsoft_agents) au lieu de points (microsoft.agents) dans toutes les instructions d’importation. Cette erreur est le problème de migration le plus courant.

Modèles Async/await

Toutes les méthodes bot doivent être async et utiliser await pour les opérations asynchrones. Assurez-vous que tous les appels vers send_activity, les opérations d’état et les opérations de dialogue utilisent await.

Indicateurs de type

Le Kit de développement logiciel (SDK) Agents utilise abondamment les annotations de type Python. Envisagez d’ajouter des conseils de type à votre code de bot pour un meilleur support IDE et une meilleure détection d’erreurs :

from microsoft_agents.hosting.core import TurnContext

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

Validation de la configuration

Si votre bot ne démarre pas à cause d’erreurs de configuration, vérifiez que les noms de vos variables d’environnement utilisent la bonne notation double-underscore (__) et que vous avez défini toutes les valeurs requises.

Erreurs HTTP 401 locales lors du débogage

Si vous constatez des erreurs 401 lors du débogage local en utilisant l’émulateur Bot Framework, vérifiez que vos identifiants sont correctement configurés dans le .env fichier ou utilisez les paramètres d’authentification de l’émulateur.

compatibilité des versions Python

Vérifiez que vous utilisez Python 3.10 ou version ultérieure. Le Kit de développement logiciel (SDK) Agents utilise des fonctionnalités de Python modernes qui ne sont pas disponibles dans les versions antérieures.

Liste des éléments à vérifier pour la migration

✓ Analyser et planifier : Identifier les fonctionnalités obsolètes et décider de la portée de migration par rapport à la reconstruction. ✓ Upgrade Python version : passer à Python 3.10 ou version ultérieure (3.11+ recommandé). ✓ Remplacer les paquets : Supprimer botbuilder-*; add microsoft-agents-* (hosting-core, activity, hosting-aiohttp, authentication-msal, fournisseurs de stockage, hosting-teams). ✓ Mettre à jour les importations : appliquer le « chercher/remplacer » selon les tableaux ci-dessus ; Changez tout microsoft.agents en microsoft_agents. ✓ Mettre à jour les types et classes : Corriger les API renommées et déplacer TurnContext les méthodes statiques vers Activity les méthodes d’instance. ✓ Mettre à jour la configuration : Créer .env un fichier avec une nomenclature hiérarchique (doubles soulignements). ✓ Mise à jour initialisation : Utiliser CloudAdapter avec MsalAuth.from_environment() et AgentsHttpMiddleware. ✓ Configurer la journalisation : configurez la journalisation Python pour le journal microsoft_agents. ✓ Construire et tester localement : Utiliser l’émulateur Bot Framework avec les identifiants ; Validez les scénarios principaux. ✓ Déployer et surveiller : Mettez à jour les variables d'environnement dans Azure pour correspondre à la nouvelle configuration et surveillez les journaux après le déploiement.

Contenu connexe

• Guide de migration du Azure Bot Framework SDK vers le SDK Agents
• Guide de migration de Azure Bot Framework SDK vers Microsoft 365 Agents SDK pour .NET
• Guide de migration du kit de développement logiciel (SDK) Bot Framework pour Azure vers le kit de développement logiciel (SDK) Agents de Microsoft 365 pour Node.js