Azure Bot Framework SDK Microsoft 365 -agenttien SDK siirtämisen ohjeet Python

Tässä artikkelissa kuvataan tarvittavat muutokset siirtymiseksi Bot Framework SDK:sta Python Python Microsoft 365 -agenttien SDK.

Vaatimukset

• Python versio 3.10 tai uudempi (suositus yli 3,11) tukee enintään 3,14:ää.
• Aiemmin luotu Bot Framework SDK -projekti
• Azure Bot Service resurssi

Azure-resurssit

Olemassa olevat Azure resurssit pysyvät muuttumattomina tämän siirron aikana. Jatka nykyisen Azure Botin rekisteröimistä (sovellustunnus ja salainen koodi). Viittaat näihin arvoihin myöhemmin kuvatussa uudessa konfiguraatiorakenteessa. Monet ratkaisut sisältävät myös vanhoja sovellusasetuksia, kuten APP_ID, APP_PASSWORD, ja APP_TENANT_ID. Nämä merkinnät ovat haitattomia siirron aikana, mutta Microsoft 365 -agenttien SDK eivät enää käytä niitä. Voit poistaa nämä asetukset, kun olet vahvistanut uuden asetuksen.

Ensimmäiset vaiheet

Aloita päivittämällä pakettien riippuvuudet. Seuraavat muutokset eivät kata kaikkia nimitiloja, joihin saatat joutua koskemaan, mutta ne käsittelevät useimmat pakettikorvaukset.

Pakettien riippuvuuksien päivittäminen

Jos bottisi integroituu Microsoft Teams kanssa, sisällytä Teams-laajennuspakettiin microsoft-agents-hosting-teams Teamsin ydinominaisuuksille.

Tunnistautumisen hallintaa varten lisää microsoft-agents-authentication-msal käsittelemään MSAL-pohjaista tunnistautumista.

Päivitä oma requirements.txt tai vastaava riippuvuustiedostosi korvaamaan Bot Framework -paketit niiden Agent-SDK-vastineilla. Käytä pip install -r requirements.txt tai haluamaasi paketinhallintaa uusien riippuvuuksien asentamiseen.

Agents SDK valvoo koodin laatustandardeja muotoilun black ja flake8 lintauksen avulla. Harkitse näiden työkalujen lisäämistä kehitysriippuvuuksiisi.

Päivitä tuonnit

Seuraavaksi päivitä tuonnit. Helpoin tapa on koko projektin kattava etsi ja korvaa tarkka teksti.

Tyyppi- ja luokkien uudelleennimet

Joillakin tyypeillä ja luokilla on eri nimet Agenttien SDK:ssa. Käytä seuraavia kartoituksia ohjaamaan muutoksiasi.

Toimintaluokkien muutokset

Agents SDK:n Activity luokka sisältää sisäänrakennetun validoinnin käyttämällä Pydanticia. Voit jäsentää ja validoida toimintoja JSONista tai sanakirjoista käyttämällä Activity.model_validate().

Lisäksi luokka Activity keskittää toimintakuormiin liittyvät toiminnot. Metodit, joilla aiemmin oli staattisia metodejaTurnContext, ovat nyt instanssimetodeja :Activity

Päivitä yleiset turn_state-viittaukset. Korvaa seuraavat käytöt vastaavasti.

Määritys

Agent-SDK käyttää ympäristömuuttujia hierarkkisella nimeämiskäytännöllä konfigurointia varten.

Ympäristömuuttujat

Luo tai päivitä tiedostosi .env seuraavalla rakenteella:

# 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

Siirron huomautus: päivitä ympäristömuuttujien nimet seuraavassa taulukossa esitetyllä tavalla:

Agentin SDK-konfiguraatio käyttää kaksoisalaviivoja (__) esittämään sisäkkäisiä konfiguraatiohierarkioita. Tämä malli mahdollistaa joustavan konfiguraationhallinnan eri käyttöönottoympäristöissä.

Käynnistys ja alustaminen

Alustus vaihtelee Agents SDK:ssa. Bot Framework SDK:ta käytetään aiohttp tyypillisesti manuaalisen adapterin konfiguraatiossa. Agents SDK:n avulla voit käyttää sisäänrakennettuja palvelintyökaluja yksinkertaistettuun asennukseen.

Palvelimen asennus

Bot Framework SDK -lähestymistapa

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 -lähestymistapa (sisustuskuvio)

Suositeltu lähestymistapa käyttää AgentApplication sisustajien kanssa modernimman, deklaratiivsemman tyylin luomiseksi:

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 mahdollistaa load_configuration_from_env() konfiguraation automaattisen latauksen ympäristömuuttujista, jolloin manuaalinen konfiguraation jäsennys poistuu. Sisustusmalli mahdollistaa käsittelijöiden rekisteröinnin deklaratiivisesti ilman eksplisiittistä luokkapohjaista periytymistä.

Todentaminen ja suojaus

Bot Framework SDK sisälsi JSON Web Token (JWT) -validoinnin sovittimeen. Agent-SDK erottaa todennuskysymykset, joten autentikointiväliohjelmiston voi konfiguroida eksplisiittisesti.

Tuotantoympäristöissä varmista, että JWT-validointi on käytössä konfiguroinnin CloudAdapter kautta. Sovitin validoi saapuvat pyynnöt automaattisesti MSAL-todennuskonfiguraatiolla.

Paikallisessa kehityksessä Bot Framework Emulatorilla voit käyttää tyhjiä tunnuksia .env-tiedostossasi:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

Toiminnan hallinta

Useimmat Bot Framework SDK:n avulla luodut botit perustuvat ActivityHandler perusluokkaan.

Agents SDK tarjoaa yhteensopivan ActivityHandler version, joka ylläpitää samankaltaista API-pintaa helpompaa migraatiota varten.

Tärkeimmät erot

Käsittelijämetodin allekirjoitusmuutokset

Bot Frameworkin SDK-käsittelijät käyttävät tyypillisesti paikkaparametreja, kun taas agenttien SDK-käsittelijät ylläpitävät samaa kaavaa, TurnContext joka on kuin pääparametri.

Lisämenetelmät Agents SDK:ssa

Puuttuvat menetelmät Agents SDK:ssa

Migraatioesimerkki

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

Agenttien 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

Migraatio on pääosin suoraviivaista, ja tärkeimmät muutokset ovat import-lauseet. Useimmat olemassa ActivityHandlerolevat botit toimivat mahdollisimman vähäisin muutoksin.

Osavaltion hallinta

ConversationState, UserState ja PrivateConversationState ovat yhteensopivia muutamien eroavaisuuksien kanssa. Ydintilahallinnan mallit ovat samankaltaisia kuin Bot Framework SDK:ssa.

Sinun täytyy rekisteröidä tilaobjektit ja tallentaa ne nimenomaisesti muutosten jälkeen.

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)

Tallennustilavaihtoehdot

Agent-SDK tarjoaa tallennustoteutuksia eri taustajärjestelmille:

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

Lokiin kirjaaminen

Agenttien SDK käyttää Python vakiomuotoista logging -moduulia. Määritä kirjautuminen pääsovellustiedostoosi:

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)

Lokien tasot

• DEBUG: Yksityiskohtainen paikallisen tilan seuranta
• INFO: Toiminnan käsittely, API-kutsut ja pyynnöt ulkoisille tahoille tai niiden lähettämistä
• VAROITUS: Odottamattomat tapahtumat, jotka aiheuttavat mahdollisia ongelmia
• VIRHE: Havaitut virheet, olivatpa ne havaittu tai jääneet kiinni

Yleiset muuttoreitit

Yksinkertainen kaikurobotti

Yksinkertainen kaiku-botti Bot Framework SDK:ssa

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

Yksinkertainen kaikurobotti Agents SDK:ssa

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

Tilanhallinta laskurin avulla

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

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

Vianmääritys ja vihjeet

Seuraavat vihjeet saattavat auttaa sinua menestymään paremmin.

Tuontivirheet

Jos kohtaat tuontivirheitä, varmista, että käytät kaikissa tuontilauseissa alleviivauksia (microsoft_agents) pisteiden () sijaanmicrosoft.agents. Tämä virhe on yleisin migraatio-ongelma.

Asynkroniset/odotuskuviot

Kaikkien bottimetodien on oltava async ja käytettävä await asynkronisissa operaatioissa. Varmista, että kaikki kutsut send_activity, tilaoperaatiot ja dialogitoiminnot käyttävät await.

Tyyppivinkit

Agents SDK käyttää Python laajasti vihjeitä. Harkitse tyyppivihjeiden lisäämistä bottikoodiin paremman IDE-tuen ja virheiden tunnistuksen saamiseksi:

from microsoft_agents.hosting.core import TurnContext

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

Kokoonpanon validointi

Jos botti ei käynnisty konfiguraatiovirheiden vuoksi, varmista, että ympäristömuuttujien nimet käyttävät oikeaa kaksoisalleviivatusta (__) ja että olet asettanut kaikki tarvittavat arvot.

Paikalliset 401-virheet virheenkorjauksen aikana

Jos näet 401-virheitä paikallisessa debuggauksessa käyttämällä Bot Framework Emulatoria, varmista, että tunnuksesi ovat oikein tiedostossa .env tai käytä emulaattorin todennusasetuksia.

Python version yhteensopivuus

Varmista, että käytät Python 3.10 tai uudempaa. Agents SDK käyttää nykyaikaisia Python ominaisuuksia, jotka eivät ole käytettävissä aiemmissa versioissa.

Siirron tarkistusluettelo

✓ Analysoi ja suunnittele: Tunnista kaikki vanhentuneet ominaisuudet ja päätä migraatiosta vs. uudelleenrakentamisen laajuudesta. ( Upgrade Python versio: Siirry arvoon Python 3.10 tai uudempi (suositus on yli 3,11). ✓ Korvaa paketit: Poista botbuilder-*; lisää microsoft-agents-* (hosting-core, activity, hosting-aiohttp, authentication-msal, tallennuspalveluntarjoajat, hosting-teams). ✓ Päivitä tuonnit: Sovella etsi/korvaa yllä olevien taulukoiden mukaisesti; muuta kaikki microsoft.agents muotoon microsoft_agents. ✓ Päivitä tyypit ja luokat: Korjaa uudelleen nimetyt API:t ja siirrä TurnContext staattiset metodit instanssimetodeihin Activity . ✓ Päivitä asetukset: Luo .env tiedosto hierarkkisella nimellä (kaksoisalleviivat). ✓ Päivitä alustus: Käytä CloudAdapter ja MsalAuth.from_environment().AgentsHttpMiddleware ( Määritä kirjaaminen: määritä Python kirjaaminen microsoft_agentskirjaustoiminnolle. ✓ Rakenna ja testaa paikallisesti: Käytä Bot Framework Emulatoria tunnuksilla; Vahvista ydinskenaariot. ( Deploy ja monitor: Päivitä Azure ympäristömuuttujat vastaamaan uutta kokoonpanoa ja katso lokit käyttöönoton jälkeen.

Liittyvä sisältö

• Azure Bot Framework SDK:sta Agents SDK:n siirto-ohjeisiin
• Azure Bot Framework SDK–Microsoft 365 -agenttien SDK-siirto-ohjeet .NET:lle
• Azure Bot Framework SDK:sta Microsoft 365 -agenttien SDK Node.js