Azure Bot Framework SDK voor SDK voor Microsoft 365-agenten migratierichtlijnen voor Python

In dit artikel worden de vereiste wijzigingen beschreven die moeten worden gemigreerd van de Bot Framework SDK voor Python naar de SDK voor Microsoft 365-agenten voor Python.

Vereiste voorwaarden

• Python versie 3.10 of hoger (3.11+ aanbevolen, ondersteunt maximaal 3.14)
• Bestaand Bot Framework SDK-project
• Azure Bot Service-resource

Azure-hulpmiddelen

Uw bestaande Azure-resources blijven ongewijzigd tijdens deze migratie. Blijf uw huidige Azure Bot-registratie gebruiken (app-id en geheim). Je verwijst naar die waarden in de nieuwe configuratiestructuur die later wordt beschreven. Veel oplossingen bevatten ook legacy-app-instellingen zoals APP_ID, APP_PASSWORD, en APP_TENANT_ID. Deze vermeldingen zijn onschuldig tijdens de migratie, maar de SDK voor Microsoft 365-agenten gebruikt ze niet meer. Je kunt deze instellingen verwijderen nadat je de nieuwe configuratie hebt gevalideerd.

Eerste stappen

Begin met het bijwerken van pakketafhankelijkheden. De volgende wijzigingen hebben geen betrekking op elke naamruimte die u mogelijk moet aanraken, maar ze verwerken de meeste pakketvervangingen.

Pakketafhankelijkheden bijwerken

Als uw bot integreert met Microsoft Teams, neemt u het Teams Extension-pakket microsoft-agents-hosting-teams op voor de kernfuncties van Teams.

Voor authenticatie voeg je toe microsoft-agents-authentication-msal om MSAL-gebaseerde authenticatie te verwerken.

Update je requirements.txt of een equivalent afhankelijkheidsbestand om Bot Framework-pakketten te vervangen door hun Agents SDK-equivalenten. Gebruik pip install -r requirements.txt of uw voorkeurspakketbeheerder om de nieuwe afhankelijkheden te installeren.

De Agents SDK handhaaft codekwaliteitsnormen door gebruik te maken van black voor opmaak, en van flake8 voor linting. Overweeg deze tools toe te voegen aan je ontwikkelafhankelijkheden.

Importbewerkingen bijwerken

Vervolgens update je imports. De eenvoudigste aanpak is een projectbrede zoek-en-vervanging van de exacte tekst.

Type- en klassehernoemingen

Sommige types en klassen hebben verschillende namen in de Agents SDK. Gebruik de volgende mappings om je veranderingen te sturen.

Veranderingen van activiteitsklasse

De Activity klasse in de Agents SDK bevat ingebouwde validatie door gebruik te maken van Pydantic. Je kunt activiteiten uit JSON of woordenboeken parsen en valideren door gebruik te maken van Activity.model_validate().

Daarnaast centraliseert de Activity klasse operaties die verband houden met activiteitspayloads. Methoden die voorheen statische methoden op TurnContext waren, zijn nu instantiemethoden op Activity:

Algemene turn_state verwijzingen bijwerken. Vervang de volgende gebruiksgegevens dienovereenkomstig.

Configuratie

De Agents SDK gebruikt omgevingsvariabelen met een hiërarchische naamgevingsconventie voor de configuratie.

Omgevingsvariabelen

Maak of werk je .env bestand bij met de volgende structuur:

# 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

Opmerking bij migratie: werk de namen van uw omgevingsvariabelen bij, zoals wordt weergegeven in de volgende tabel:

De Agents SDK-configuratie gebruikt dubbele onderscores (__) om geneste configuratiehiërarchieën weer te geven. Dit patroon maakt flexibel configuratiebeheer mogelijk over verschillende deploymentomgevingen heen.

Opstart en initialisatie

De initialisatie verschilt in de Agents SDK. De Bot Framework SDK wordt doorgaans gebruikt aiohttp met handmatige adapterconfiguratie. Door de Agents SDK te gebruiken, kun je de ingebouwde serverhulpmiddelen gebruiken voor een vereenvoudigde installatie.

Serveropstelling

Bot Framework SDK-benadering

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)

Benadering van SDK voor agents (decorator-patroon)

De aanbevolen aanpak gebruikt de AgentApplication met decorators voor een modernere, declaratieve stijl:

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

De Agents SDK biedt load_configuration_from_env() het automatisch laden van configuraties uit omgevingsvariabelen, waardoor handmatige configuratieparsing wordt geëlimineerd. Het Decoratorpatroon stelt je in staat handlers declaratief te registreren zonder expliciete klassegebaseerde overerving.

Verificatie en beveiliging

De Bot Framework SDK bevatte JSON Web Token (JWT) validatie in de adapter. De Agents SDK scheidt authenticatieproblemen, zodat je authenticatie-middleware expliciet kunt configureren.

Voor productieomgevingen zorg ervoor dat JWT-validatie via de CloudAdapter configuratie is ingeschakeld. De adapter valideert automatisch binnenkomende verzoeken door gebruik te maken van de MSAL-authenticatieconfiguratie.

Voor lokale ontwikkeling met de Bot Framework Emulator kun je lege inloggegevens gebruiken in je .env-bestand:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

Activiteitsafhandeling

De meeste bots die zijn gemaakt met de Bot Framework SDK, zijn gebaseerd op de ActivityHandler basisklasse.

De Agents SDK biedt een compatibele ActivityHandler API die een vergelijkbaar API-oppervlak onderhoudt voor eenvoudigere migratie.

Belangrijkste verschillen

Handtekeningwijzigingen met handlermethode

Bot Framework SDK-handlers gebruiken doorgaans positionele parameters, terwijl Agents SDK-handlers hetzelfde patroon behouden als TurnContext de primaire parameter.

Aanvullende methoden in Agents SDK

Ontbrekende methoden in Agents SDK

Voorbeeld van migratie

Bot Framework Software Development Kit

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

SDK voor agenten

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

De migratie is grotendeels eenvoudig, met als belangrijkste wijzigingen de import-instructies. De meeste bestaande op ActivityHandler gebaseerde bots werken met minimale aanpassingen.

Toestandbeheer

ConversationState, UserState en PrivateConversationState zijn compatibel met enkele verschillen. De kernpatronen voor state management lijken op die van de Bot Framework SDK.

Je moet statusobjecten registreren en expliciet opslaan na aanpassingen.

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)

Opslagopties

De Agents SDK biedt opslagimplementaties voor verschillende 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"
)

Logboekregistratie

De Agents SDK maakt gebruik van de standaardmodule logging van Python. Configureer het loggen in je hoofdapplicatiebestand:

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)

Logboekniveaus

• DEBUG: Uitgebreide lokale staatstracking
• INFO: Afhandeling van activiteiten, API-aanroepen en verzoeken naar of van externe entiteiten
• WAARSCHUWING: Onverwachte gebeurtenissen die mogelijke problemen veroorzaken
• FOUT: Geobserveerde fouten, of ze nu vastgesteld zijn of niet zijn opgemerkt

Algemene migratiepatronen

Eenvoudige echo-bot

Eenvoudige echo-bot in 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}")

Eenvoudige echo-bot in 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}")

Toestandbeheer met teller

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)

Teamsbot

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

Problemen oplossen en tips

De volgende tips kunnen u helpen om succesvoller te zijn.

Importfouten

Als je importfouten tegenkomt, zorg er dan voor dat je underscores (microsoft_agents) gebruikt in plaats van dots (microsoft.agents) in alle importinstructies. Deze fout is het meest voorkomende migratieprobleem.

Async/await-patronen

Alle botmethoden moeten async zijn en await gebruiken voor asynchrone operaties. Zorg ervoor dat alle aanroepen naar send_activity, toestandsoperaties en dialoogoperaties gebruikmaken van await.

Type-aanduidingen

De Agents SDK gebruikt Python type hints uitgebreid. Overweeg om typehints toe te voegen aan je botcode voor betere IDE-ondersteuning en foutdetectie:

from microsoft_agents.hosting.core import TurnContext

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

Configuratievalidatie

Als je bot niet opstart door configuratiefouten, controleer dan of de namen van je omgevingsvariabelen de juiste double-underscore (__) notatie gebruiken en dat je alle vereiste waarden hebt ingesteld.

Lokale 401-fouten tijdens het debuggen

Als je 401-fouten ziet tijdens lokaal debuggen met de Bot Framework Emulator, controleer dan of je inloggegevens correct zijn geconfigureerd in het .env bestand of gebruik de authenticatie-instellingen van de emulator.

Python versiecompatibiliteit

Zorg ervoor dat u Python 3.10 of hoger gebruikt. De Agents SDK maakt gebruik van moderne Python functies die niet beschikbaar zijn in eerdere versies.

Controlelijst voor migratie

✓ Analyseren en plannen: Identificeer verouderde functies en beslis over migratie versus herbouw van scope. ✓ Upgrade Python versie: Verplaatsen naar Python 3.10 of hoger (3.11+ aanbevolen). ✓ Pakketten vervangen: Verwijderen botbuilder-*; toevoegen (hosting-core microsoft-agents-* , activity, hosting-aiohttp, authentication-msal, storage providers, hosting-teams). ✓ ✓ Imports bijwerken: pas zoeken en vervangen toe volgens de bovenstaande tabellen; wijzig alle microsoft.agents in microsoft_agents. ✓ Update-typen en klassen: Fix hernoemde API's en verplaats TurnContext statische methoden naar Activity instantiemethoden. ✓ Updateconfiguratie: Maak .env bestand aan met hiërarchische naamgeving (dubbele onderstreepten). ✓ Update-initialisatie: Gebruik CloudAdapter met MsalAuth.from_environment() en AgentsHttpMiddleware. ✓ Logboekregistratie configureren: Python logboekregistratie instellen voor microsoft_agents logger. ✓ Lokaal bouwen en testen: Gebruik de Bot Framework Emulator met inloggegevens; Valideer kernscenario's. ✓ Deploy en monitor: Omgevingsvariabelen bijwerken in Azure zodat deze overeenkomen met de nieuwe configuratie en logboeken bekijken na de implementatie.

Verwante inhoud

• Migratierichtlijnen voor Azure Bot Framework SDK naar Agents SDK
• Azure Bot Framework SDK naar SDK voor Microsoft 365-agenten migratierichtlijnen voor .NET
• Azure Bot Framework SDK voor SDK voor Microsoft 365-agenten migratierichtlijnen voor Node.js