Azure Bot Framework SDK per Managed Disks indicazioni sulla migrazione per Python

Questo articolo descrive le modifiche necessarie per eseguire la migrazione da Bot Framework SDK per Python all'Managed Disks per Python.

Prerequisiti

• Python versione 3.10 o successiva (3.11+ consigliato, supporta fino a 3.14)
• Progetto Bot Framework SDK esistente
• Azure servizio Bot risorsa

Risorse di Azure

Le risorse Azure esistenti rimangono invariate durante questa migrazione. Continuare a usare la registrazione corrente di Azure Bot (ID applicazione e segreto). Fai riferimento a quei valori nella nuova struttura di configurazione descritta più avanti. Molte soluzioni includono anche impostazioni legacy come APP_ID, APP_PASSWORD, e APP_TENANT_ID. Queste voci sono innocue durante la migrazione, ma l'SDK per agenti Microsoft 365 non le utilizza più. Puoi rimuovere queste impostazioni dopo aver validato la nuova configurazione.

Passaggi iniziali

Per iniziare, aggiorna le dipendenze dei pacchetti. Le modifiche seguenti non coprono ogni spazio dei nomi che potrebbe essere necessario toccare, ma gestiscono la maggior parte delle sostituzioni dei pacchetti.

Aggiornare le dipendenze dei pacchetti

Se il vostro bot è integrato con Microsoft Teams, dovreste includere il pacchetto dell'estensione Teams microsoft-agents-hosting-teams con le funzionalità principali di Teams.

Per l'autenticazione, aggiungi microsoft-agents-authentication-msal per gestire l'autenticazione basata su MSAL.

Aggiorna il tuo requirements.txt file di dipendenza o quello equivalente per sostituire i pacchetti Bot Framework con i loro equivalenti SDK Agents. Usa pip install -r requirements.txt il tuo gestore di pacchetti preferito per installare le nuove dipendenze.

L'SDK degli Agenti applica gli standard di qualità del codice utilizzando black sia per la formattazione che flake8 per il linting. Considera di aggiungere questi strumenti alle tue dipendenze di sviluppo.

Aggiornare le importazioni

Poi, aggiorna le importazioni. L'approccio più semplice è un progetto di ricerca e sostituzione del testo esatto.

Rinomi di tipi e classi

Alcuni tipi e classi hanno nomi diversi nell'SDK degli agenti. Usa le seguenti mappe per guidare le tue modifiche.

Modifiche della classe di attività

La Activity classe nell'SDK degli Agenti include una validazione integrata tramite Pydantic. Puoi analizzare e validare le attività da JSON o dizionari usando Activity.model_validate().

Inoltre, la Activity classe centralizza le operazioni relative ai payload di attività. I metodi che prima erano metodi statici su TurnContext sono ora metodi di istanza su Activity:

Aggiorna i riferimenti turn_state comuni. Sostituisci di conseguenza gli utilizzi seguenti.

Impostazione

L'SDK degli agenti utilizza variabili di ambiente con una convenzione gerarchica di denominazione per la configurazione.

Variabili di ambiente

Crea o aggiorna il tuo .env file con la seguente struttura:

# 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

Nota di migrazione: Aggiornare i nomi delle variabili d'ambiente come indicato nella tabella seguente:

La configurazione SDK degli agenti utilizza doppi sottolineamenti (__) per rappresentare gerarchie di configurazione annidate. Questo modello consente una gestione della configurazione flessibile tra diversi ambienti di distribuzione.

Avvio e inizializzazione

L'inizializzazione differisce nell'SDK Agenti. L'SDK del Bot Framework è tipicamente utilizzato aiohttp con la configurazione manuale degli adattatori. Utilizzando l'SDK degli agenti, puoi utilizzare le utility server integrate per una configurazione semplificata.

Configurazione del server

Approccio SDK del 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)

Approccio SDK degli agenti (modello decorator)

L'approccio consigliato prevede l'uso di AgentApplication con i decoratori per uno stile più moderno e dichiarativo.

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

L'SDK degli agenti consente load_configuration_from_env() di caricare automaticamente la configurazione dalle variabili dell'ambiente, eliminando l'analisi manuale della configurazione. Il modello decorator permette di registrare i gestori in modo dichiarativo senza un'esplicita eredità basata su classi.

Autenticazione e sicurezza

L'SDK del Bot Framework includeva la validazione JSON Web Token (JWT) nell'adattatore. L'SDK degli agenti separa le preoccupazioni di autenticazione, così puoi configurare esplicitamente il middleware di autenticazione.

Per gli ambienti di produzione, assicurarsi che la validazione JWT sia abilitata tramite la CloudAdapter configurazione. L'adattatore valida automaticamente le richieste in arrivo utilizzando la configurazione di autenticazione MSAL.

Per lo sviluppo locale con l'emulatore Bot Framework, puoi usare credenziali vuote nel tuo file .env:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

Gestione delle attività

La maggior parte dei bot creati con il Bot Framework SDK si basa sulla classe base ActivityHandler.

L'SDK degli agenti fornisce un elemento ActivityHandler compatibile che mantiene una superficie API simile per facilitare la migrazione.

Differenze principali

Cambiamenti nella firma del metodo handler

I gestori SDK del Bot Framework tipicamente utilizzano parametri posizionali, mentre i gestori SDK degli agenti mantengono lo stesso schema con TurnContext come parametro principale.

Metodi aggiuntivi nell'SDK degli agenti

Metodi mancanti nell'SDK degli agenti

Esempio di migrazione

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

SDK per agenti

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 migrazione è per lo più semplice, con i principali cambiamenti che riguardano le dichiarazioni di importazione. La maggior parte dei bot basati su ActivityHandler esistenti funziona con modifiche minime.

Gestione dello stato

ConversationState, UserState, e PrivateConversationState sono compatibili con alcune differenze. I modelli di gestione dello stato core sono simili al Bot Framework SDK.

Devi registrare gli oggetti di stato e salvarli esplicitamente dopo le modifiche.

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)

Opzioni di archiviazione

L'SDK degli Agenti fornisce implementazioni di storage per diversi backend:

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

Registrazione

Agents SDK usa il modulo standard logging di Python. Configura il logging nel file principale dell'applicazione:

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)

Livelli di log

• DEBUG: tracciamento dettagliato dello stato locale
• INFO: Gestione delle attività, chiamate API e richieste da o verso entità esterne
• ATTENZIONE: Eventi imprevisti che causano potenziali problemi
• ERRORE: Errori osservati, che siano stati individuati o non

Modelli di migrazione comuni

Bot di eco semplice

Echobot semplice nell'SDK del 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}")

Echo bot semplice nell'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}")

Gestione dello stato con contropartita

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

Risoluzione dei problemi e suggerimenti

I suggerimenti seguenti potrebbero risultare più efficaci.

Errori di importazione

Se incontri errori di importazione, assicurati di usare sottolinee (microsoft_agents) invece di punti (microsoft.agents) in tutte le istruzioni di importazione. Questo errore è il problema di migrazione più comune.

Modelli di async/await

Tutti i metodi bot devono essere async ed utilizzare await per operazioni asincrone. Assicurati che tutte le chiamate a send_activity, operazioni di stato e operazioni di dialogo usino await.

Annotazioni di tipo

Agents SDK utilizza ampiamente i type hints di Python. Considera di aggiungere suggerimenti di tipo al codice del tuo bot per un migliore supporto IDE e rilevamento degli errori:

from microsoft_agents.hosting.core import TurnContext

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

Convalida della configurazione

Se il tuo bot non si avvia a causa di errori di configurazione, verifica che i nomi delle variabili dell'ambiente utilizzino la notazione corretta doppia sottolineatura (__) e che tu abbia impostato tutti i valori richiesti.

Errori locali 401 durante il debug

Se noti errori 401 durante il debug locale usando l'emulatore Bot Framework, verifica che le tue credenziali siano correttamente configurate nel .env file o usa le impostazioni di autenticazione dell'emulatore.

compatibilità delle versioni di Python

Assicurarsi di usare Python 3.10 o versione successiva. Agents SDK usa funzionalità di Python moderne non disponibili nelle versioni precedenti.

Elenco di controllo per la migrazione

✓ Analizza e pianifica: Identifica eventuali funzionalità obsolete e decidi l'ambito di migrazione rispetto alla ricostruzione. ✓ Upgrade versione Python: passare a Python 3.10 o versione successiva (3.11+ consigliato). ✓ Sostituire i pacchetti: Rimuovere botbuilder-*; aggiungere microsoft-agents-* (hosting-core, activity, hosting-aiohttp, authentication-msal, fornitori di storage, hosting-teams). ✓ Aggiorna importazioni: applica il metodo trova/sostituzione secondo le tabelle sopra; Cambia tutto microsoft.agents in microsoft_agents. ✓ Aggiornare tipi e classi: Correggere API rinominate e spostare TurnContext metodi statici ai Activity metodi di istanza. ✓ Aggiorna configurazione: Crea .env file con denominazione gerarchica (doppio sottolineo). ✓ Aggiorna l'inizializzazione: Usa CloudAdapter con MsalAuth.from_environment() e AgentsHttpMiddleware. ✓ Configurare il logging: Configurare il log di Python per microsoft_agents logger. ✓ Compila e testa localmente: Usa l'emulatore Bot Framework con le credenziali; Valida gli scenari fondamentali. ✓ Deploy e monitor: aggiornare le variabili di ambiente in Azure in modo che corrispondano alla nuova configurazione e controllare i log dopo l'implementazione.

Contenuti correlati

• Guida alla migrazione da Azure Bot Framework SDK a Agents SDK
• Indicazioni sulla migrazione da Azure Bot Framework SDK a Managed Disks per .NET
• Migrazione da Azure Bot Framework SDK ai Managed Disks: guida per Node.js