Migreringsvägledning för Azure Bot Framework SDK till Microsoft 365 Agents SDK för Python

I den här artikeln beskrivs de ändringar som krävs för att migrera från Bot Framework SDK för Python till Microsoft 365 Agents SDK för Python.

Tips/Råd

Behandla det här arbetet som en moderniseringsinsats, inte bara ett paketbyte. Agents SDK föredrar enklare, obestämda mönster (asynk/vänta, beroendeinjektion, standardloggning) och tar bort äldre funktioner. Behåll bara det som din robot faktiskt behöver och undvik att föra vidare den gamla mallkomplexiteten.

Förutsättningar

• Python version 3.10 eller senare (3.11+ rekommenderas, stöder upp till 3.14)
• Befintligt Bot Framework SDK-projekt
• Azure Bot Service resurs

Azure resurser

Dina befintliga Azure resurser förblir oförändrade under den här migreringen. Fortsätt att använda din aktuella Azure robotregistrering (app-ID och hemlighet). Du refererar till dessa värden i den nya konfigurationsstrukturen som beskrivs senare. Många lösningar inkluderar också äldre appinställningar såsom APP_ID, APP_PASSWORD, och APP_TENANT_ID. Dessa poster är ofarliga under migreringen, men Microsoft 365-agenterna använder dem inte längre i SDK:et. Du kan ta bort dessa inställningar efter att du har validerat den nya konfigurationen.

De första stegen

Börja med att uppdatera paketberoenden. Följande ändringar omfattar inte alla namnrymder du kan behöva uppdatera, men de hanterar de flesta paketersättningar.

Uppdatera paketberoenden

Bot Frameworks utvecklingskit	Agents-SDK
botbuilder-core	microsoft-agents-hosting-core
botbuilder-schema	microsoft-agents-activity
botbuilder-azure	microsoft-agents-storage-blob och microsoft-agents-storage-cosmos
botbuilder-integration-aiohttp	microsoft-agents-hosting-aiohttp

Om roboten integreras med Microsoft Teams inkluderar du Teams-tilläggspaketet microsoft-agents-hosting-teams för grundläggande Teams-funktioner.

För autentisering, lägg till microsoft-agents-authentication-msal för att hantera MSAL-baserad autentisering.

Uppdatera din requirements.txt eller motsvarande beroendefil för att ersätta Bot Framework-paket med deras motsvarigheter till Agents SDK. Använd pip install -r requirements.txt eller din föredragna pakethanterare för att installera de nya beroendena.

Agents SDK upprätthåller kodkvalitetsstandarder genom att använda black för formatering och flake8 linting. Överväg att lägga till dessa verktyg i dina utvecklingsberoenden.

Uppdatera importer

Viktigt!

Agents SDK använder understreck i importvägar (microsoft_agents) istället för punkter (microsoft.agents). Denna förändring påverkar alla import.

Nästa steg, uppdatera importen. Det enklaste tillvägagångssättet är en projektomfattande sök-och-ersätt av exakt text.

Import av botramverk	Agent-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 ...

Typ- och klassombyten

Vissa typer och klasser har olika namn i Agents SDK. Använd följande mappningar för att vägleda dina förändringar.

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

Förändringar av aktivitetsklass

Klassen Activity i Agents SDK inkluderar inbyggd validering genom att använda Pydantic. Du kan tolka och validera aktiviteter från JSON eller ordböcker genom att använda Activity.model_validate().

Dessutom centraliserar Activity klassen operationer relaterade till aktivitetslaster. Metoder som tidigare var statiska metoder på TurnContext är nu instansmetoder på Activity:

Bot Framework statisk metod	Agent-SDK-instansmetod
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()

Uppdatera vanliga turn_state referenser. Ersätt följande användningar i enlighet med detta.

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

Agents SDK använder miljövariabler med en hierarkisk namngivningskonvention för konfiguration.

Miljövariabler

Skapa eller uppdatera din .env fil med följande 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

Migreringskommentar: Uppdatera miljövariabelnamnen enligt följande tabell:

Bot Frameworks utvecklingskit	Agents-SDK
APP_ID eller MICROSOFT_APP_ID	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID
APP_PASSWORD eller MICROSOFT_APP_PASSWORD	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET
APP_TENANT_ID eller MICROSOFT_APP_TENANT_ID	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID

Agents SDK-konfigurationen använder dubbla understreck (__) för att representera nästlade konfigurationshierarkier. Detta mönster möjliggör flexibel konfigurationshantering över olika distributionsmiljöer.

Start och initialisering

Initialiseringen skiljer sig i Agents SDK. Bot Framework SDK används aiohttp vanligtvis med manuell adapterkonfiguration. Genom att använda Agents SDK kan du använda de inbyggda serververktygen för förenklad installation.

Serveruppsättning

Bot Framework SDK-metoden

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-metod (dekoratörsmönster)

Den rekommenderade metoden använder sig av AgentApplication med dekoratörer för en mer modern, deklarativ 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}")

Agents SDK möjliggör load_configuration_from_env() automatisk laddning av konfiguration från miljövariabler, vilket eliminerar manuell konfigurationsparsing. Decorator-mönstret låter dig registrera hanterare deklarativt utan explicit klassbaserat arv.

Autentisering och säkerhet

Bot Framework SDK inkluderade validering av JSON Web Token (JWT) i adaptern. Agents SDK separerar autentiseringsaspekter, så du kan konfigurera autentiseringsmiddleware tydligt.

För produktionsmiljöer, se till att JWT-validering är aktiverad via konfigurationen CloudAdapter . Adaptern validerar automatiskt inkommande förfrågningar genom att använda MSAL-autentiseringskonfigurationen.

För lokal utveckling med Bot Framework Emulator kan du använda tomma inloggningsuppgifter i din .env-fil:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

Aktivitetshantering

De flesta robotar som skapats med Bot Framework SDK baseras på basklassen ActivityHandler.

Agents SDK erbjuder en kompatibel ActivityHandler lösning som upprätthåller en liknande API-yta för enklare migrering.

Viktiga skillnader

Ändringar i hanterarmetodens signatur

Bot Framework SDK-hanterare använder vanligtvis positionsparametrar, medan Agents SDK-hanterare behåller samma mönster med TurnContext som primärparameter.

Ytterligare metoder i Agents SDK

Metod	Description
on_message_delete()	Hanterar aktiviteter för borttagning av meddelanden
on_message_update()	Hanterar aktiviteter för meddelandeuppdatering
on_sign_in_invoke()	Hanterar aktiviteter för inloggningsanrop

Saknade metoder i Agents SDK

Metod	Reason
on_command_activity()	Kommandoaktiviteter stöds inte
on_command_result_activity()	Aktiviteter för kommandoresultat stöds inte

Migreringsexempel

Bot Frameworks utvecklingskit

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

Migreringen är mestadels enkel, med de största förändringarna i importsatserna. De flesta befintliga ActivityHandlerbottar fungerar med minimala modifieringar.

Tillståndshantering

ConversationState, UserState och PrivateConversationState är kompatibla med några skillnader. De grundläggande tillståndshanteringsmönstren liknar Bot Framework SDK.

Du måste registrera tillståndsobjekt och uttryckligen spara dem efter ändringar.

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)

Lagringsalternativ

Agents SDK tillhandahåller lagringsimplementationer för olika 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"
)

Loggning

Agents SDK använder Python standardmodulen logging. Konfigurera loggning i din huvudapplikationsfil:

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)

Loggnivåer

• FELSÖKNING: Utförlig lokal tillståndsspårning
• INFO: Aktivitetshantering, API-anrop och förfrågningar till eller från externa enheter
• VARNING: Oväntade händelser som orsakar potentiella problem
• FEL: Observerade fel, oavsett om de upptäcktes eller inte upptäcktes

Vanliga migreringsmönster

Enkel ekobot

Enkel echo-bot i 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}")

Enkel echo-bot i 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}")

Tillståndshantering med räknare

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

Felsökning och tips

Följande tips kan hjälpa dig att bli mer framgångsrik.

Importfel

Om du stöter på importfel, se till att du använder understreck (microsoft_agents) istället för punkter (microsoft.agents) i alla importsatser. Detta fel är det vanligaste migrationsproblemet.

Async/await-mönster

Alla botmetoder måste vara async och användas await för asynkrona operationer. Se till att alla anrop till send_activity, state operations och dialogoperationer använder await.

Skriv tips

Agents SDK använder Python typtips i stor utsträckning. Överväg att lägga till typtips i din botkod för bättre IDE-stöd och felupptäckt:

from microsoft_agents.hosting.core import TurnContext

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

Konfigurationsverifiering

Om din bot inte startar på grund av konfigurationsfel, kontrollera att miljöns variabler har rätt dubbelunderstryksnotation (__) och att du har satt alla nödvändiga värden.

Lokala 401-fel under felsökning

Om du ser 401-fel under lokal felsökning med hjälp av Bot Framework Emulator, kontrollera att dina inloggningsuppgifter är korrekt konfigurerade .env i filen eller använd emulatorns autentiseringsinställningar.

Python versionskompatibilitet

Kontrollera att du använder Python 3.10 eller senare. Agents SDK använder moderna Python funktioner som inte är tillgängliga i tidigare versioner.

Checklista för migrering

✓ Analysera och planera: Identifiera eventuella föråldrade funktioner och beslut om migrering kontra ombyggnadsomfattning. √ Upgrade Python version: Flytta till Python 3.10 eller senare (3.11+ rekommenderas). ✓ Ersätt paket: Ta bort botbuilder-*; lägg till microsoft-agents-* (hosting-core, activity, hosting-aiohttp, authentication-msal, lagringsleverantörer, hosting-teams). ✓ Uppdatera import: Tillämpa sök/ersätt enligt tabellerna ovan; ändra alla microsoft.agents till microsoft_agents. ✓ Uppdatera typer och klasser: Fixa omdöpta API:er och flytta TurnContext statiska metoder till Activity instansmetoder. ✓ Uppdatera konfiguration: Skapa .env fil med hierarkisk namngivning (dubbla understreck). ✓ Uppdateringsinitialisering: Använd CloudAdapter med MsalAuth.from_environment() och AgentsHttpMiddleware. √ Konfigurera loggning: Konfigurera Python loggning för microsoft_agents logger. ✓ Bygg och testa lokalt: Använd Bot Framework Emulator med inloggningsuppgifter; Validera kärnscenarier. √ Distribuera och övervaka: Uppdatera miljövariabler i Azure för att matcha den nya konfigurationen och titta på loggar efter distributionen.

Relaterat innehåll

• Migreringsvägledning för Azure Bot Framework SDK till Agents SDK
• Azure Bot Framework SDK till Microsoft 365 Agents SDK vägledning för migrering för .NET
• Migreringsvägledning från Azure Bot Framework SDK till Microsoft 365 Agents SDK för Node.js