Azure Bot Framework SDK から Microsoft 365 エージェント SDK への Python 向け移行ガイダンス

この記事では、Bot Framework SDK for Python から Python のMicrosoft 365 エージェント SDKに移行するために必要な変更について説明します。

ヒント

この作業を単なるパッケージの入れ替えではなく、最新化の取り組みとして扱います。 Agents SDKは、よりシンプルで意見を述べないパターン(非同期/待機、依存性注入、標準ログ)を支持し、レガシー機能を削除しています。 ボットが実際に必要とするものだけを残し、古いテンプレートの複雑さを引き継がないように回避してください。

前提条件

• Python バージョン 3.10 以降 (3.11 以降を推奨、最大 3.14 をサポート)
• 既存の Bot Framework SDK プロジェクト
• Azure Bot Service リソース

Azureのリソース

既存のAzure リソースは、この移行中も変更されません。 現在のAzure ボット登録 (アプリ ID とシークレット) を引き続き使用します。 これらの値は、後述する新しい構成構造で参照します。 多くのソリューションには、 APP_ID、 APP_PASSWORD、 APP_TENANT_IDなどのレガシーアプリ設定も含まれています。 これらのエントリは移行中は無害ですが、Microsoft 365 エージェント SDKでは使用されなくなりました。 新しい設定を検証した後にこれらの設定を削除できます。

最初のステップ

まず、パッケージの依存関係を更新します。 以下の変更は、必要に応じて変更を加える可能性のあるすべての名前空間を網羅しているわけではありませんが、ほとんどのパッケージ置換を処理します。

パッケージの依存関係を更新する

Bot Framework SDK（ボット フレームワーク ソフトウェア開発キット）	エージェント SDK
botbuilder-core	microsoft-agents-hosting-core
botbuilder-schema	microsoft-agents-activity
botbuilder-azure	microsoft-agents-storage-blob および microsoft-agents-storage-cosmos
botbuilder-integration-aiohttp	microsoft-agents-hosting-aiohttp

ボットがMicrosoft Teamsと統合されている場合は、Teams のコア機能用の Teams 拡張機能パッケージ microsoft-agents-hosting-teams を含めます。

認証には、MSALベースの認証を処理する microsoft-agents-authentication-msal を追加してください。

requirements.txtまたは同等の依存ファイルを更新して、Bot FrameworkパッケージをAgents SDKの同等に置き換えてください。 新しい依存関係をインストールするには、 pip install -r requirements.txt またはお好みのパッケージマネージャーを使ってください。

Agents SDKは、フォーマットに black 、lintingに flake8 を用いることでコード品質基準を強制します。 これらのツールを開発依存関係に追加することを検討してください。

インポートの更新

Important

Agents SDKはインポートパスで点(microsoft_agents)ではなくアンダースコア(microsoft.agents)を使用しています。 この変更はすべてのインポートに影響します。

次にインポートを更新します。 最も簡単な方法は、プロジェクト全体で正確なテキストを見つけて置換することです。

Bot Framework のインポート	Agents SDK のインポート
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 ...

種類とクラスの名称変更

Agents SDKでは、タイプやクラスによって異なる名前が付けられています。 以下のマッピングを使って変更を指針してください。

Bot Framework	エージェント SDK
BotState	AgentState
BotFrameworkAdapter	CloudAdapter
BotFrameworkHttpClient	AgentHttpClient
OAuthPromptSettings.connection_name	OAuthPromptSettings.azure_bot_oauth_connection_name

アクティビティクラスの変更

Agents SDKの Activity クラスには 、Pydanticを用いた組み込みの検証機能が含まれています。 JSONや辞書からアクティビティを解析・検証するには Activity.model_validate()を使えます。

さらに、 Activity クラスはアクティビティペイロードに関連する操作を中央集約します。 以前は静的メソッドだったメソッドは、 TurnContext 上でインスタンスメソッドとして使われ Activity:

ボットフレームワーク静的メソッド	Agents SDK Instance メソッド
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()

一般的な turn_state 参照を更新します。 それに応じて、次の使用法を置き換えます。

Bot Framework	エージェント 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

設定

Agents SDKは環境変数を階層的な命名規則で設定します。

環境変数

以下の構造で .env ファイルを作成または更新してください:

# 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

移行に関する注: 次の表に示すように、環境変数の名前を更新します。

Bot Framework SDK（ボット フレームワーク ソフトウェア開発キット）	エージェント SDK
APP_ID または MICROSOFT_APP_ID	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID
APP_PASSWORD または MICROSOFT_APP_PASSWORD	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET
APP_TENANT_ID または MICROSOFT_APP_TENANT_ID	CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID

Agents SDKの設定では、ネストされた構成階層を表すためにダブルアンダースコア(__)を使用します。 このパターンにより、異なる展開環境間で柔軟な構成管理が可能になります。

立ち上げと初期化

初期化はAgents SDKで異なります。 Bot Framework SDKは通常、手動のアダプター設定と aiohttp が使用されました。 Agents SDKを使えば、組み込みのサーバーユーティリティを使って簡単なセットアップが可能です。

サーバーの設定

ボットフレームワークSDKアプローチ

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 のアプローチ (デコレーターパターン)

推奨されるアプローチは、デコレーターと共にAgentApplicationを使用することで、より現代的かつ宣言的なスタイルとなります。

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は、環境変数から設定を自動的に読み込む load_configuration_from_env() を提供し、手動の設定解析を不要にします。 デコレーターパターンは、クラスベースの継承を明示的に行わずにハンドラを宣言的に登録できるようにします。

認証とセキュリティ

Bot Framework SDKには、アダプター内にJSON Web Token(JWT)の検証機能が含まれていました。 Agents SDKは認証の懸念を分離しているため、認証ミドルウェアを明示的に設定できます。

本番環境では、 CloudAdapter 構成を通じてJWT検証が有効であることを確認しましょう。 アダプターはMSAL認証設定を用いて受信リクエストを自動的に検証します。

Bot Framework Emulatorでのローカル開発では、.envファイル内の空の認証情報を使用できます:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

アクティビティの処理

Bot Framework SDK で作成されたほとんどのボットは、 ActivityHandler 基本クラスに基づいています。

Agents SDKは、移行を容易にするために類似したAPIサーフェスを維持する互換性のある対応 ActivityHandler を提供します。

主な違い

ハンドラーメソッドシグネチャの変更

Bot Framework SDKハンドラは通常、位置パラメータを使用しますが、Agents SDKハンドラは TurnContext を主要なパラメータとして同じパターンを維持します。

Agents SDKの追加メソッド

Method	説明
on_message_delete()	メッセージ削除アクティビティを処理する
on_message_update()	メッセージ更新アクティビティを処理する
on_sign_in_invoke()	サインイン呼び出しアクティビティを処理します

Agents SDKに欠けているメソッド

Method	理由
on_command_activity()	コマンド アクティビティはサポートされていません
on_command_result_activity()	コマンド結果アクティビティはサポートされていません

移行の例

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

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

移行はほぼ単純で、主な変更点はインポートステートメントです。 既存のほとんどの ActivityHandlerベースのボットは、最小限の修正で動作します。

ステート管理

ConversationState、UserState、PrivateConversationState は互換性がありますが、いくつかの違いがあります。 コアな状態管理パターンはBot Framework SDKに似ています。

状態オブジェクトを登録し、修正後に明示的に保存する必要があります。

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)

ストレージ オプション

Agents SDKは、さまざまなバックエンド向けのストレージ実装を提供します:

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

ログ記録

Agents SDK では、Pythonの標準の logging モジュールが使用されます。 メインアプリケーションファイルでログログを設定しましょう:

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)

ログ レベル

• DEBUG: 冗長なローカル状態トラッキング
• 情報:アクティビティの取り扱い、API呼び出し、外部からのリクエスト
• 警告:予期せぬ出来事があり、問題を引き起こす可能性があります
• エラー: 見つかった誤り、捕捉されたか未捕捉かに関わらず

一般的な移行パターン

シンプルなエコーボット

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

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

カウンターを用いた状態管理

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 ボット。

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

トラブルシューティングとヒント

次のヒントは、より成功に役立つ可能性があります。

インポート エラー

インポートエラーが発生した場合は、すべてのインポート文でドット(microsoft_agents)ではなくアンダースコア(microsoft.agents)を使ってください。 このエラーは最も一般的な移行問題です。

非同期/待機パターン

すべてのボットメソッドは async され、非同期操作には await を使用しなければなりません。 すべての send_activity呼び出し、状態操作、ダイアログ操作に await を使用することを確認してください。

型ヒント

Agents SDK では、Python型ヒントが広範囲に使用されます。 より良いIDEサポートとエラー検出のために、ボットコードに型ヒントを追加することを検討してください:

from microsoft_agents.hosting.core import TurnContext

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

構成の検証

設定ミスでボットが起動しない場合は、環境変数名が正しいダブルアンダースコア(__)表記法を使っているか、必要な値をすべて設定しているかを確認してください。

デバッグ中のローカル401エラー

Bot Framework Emulatorを使ってローカルデバッグ中に401エラーが見られた場合は、 .env ファイルで認証情報が正しく設定されているか、エミュレーターの認証設定をご利用ください。

Pythonバージョンの互換性

Python 3.10 以降を使用していることを確認します。 Agents SDK では、以前のバージョンでは使用できない最新のPython機能が使用されます。

移行チェックリスト

✓ 分析と計画:廃止された機能を特定し、移行か再構築の範囲を決定します。 ✓ アップグレード Python バージョン: Python 3.10 以降に移動します (3.11 以降をお勧めします)。 ✓ パッケージの置き換え:botbuilder-*(hosting-core、activity、hosting-aiohttp、authentication-msal、storage providers、hosting-teams)を削除microsoft-agents-*追加します。 ✓ インポートの更新: 上記の表に従って検索/置換を適用します。すべてのmicrosoft.agentsをmicrosoft_agentsに変更してください。 ✓ タイプとクラスの更新:名前変更されたAPIを修正し、静的メソッドTurnContextActivityインスタンスメソッドに移行します。 ✓ 設定の更新:階層的な命名(ダブルアンダースコア)で .env ファイルを作成する。 ✓ 初期化の更新: CloudAdapterをMsalAuth.from_environment()およびAgentsHttpMiddlewareとともに使用。 ✓ 構成ログ: microsoft_agents ロガーのPythonログを設定します。 ✓ ローカルでのビルドとテスト:認証情報付きのボットフレームワークエミュレーターを使用する;コアシナリオを検証する。 ✓ デプロイと監視: Azureの環境変数を更新して、ロールアウト後に新しい構成に一致させ、ログを監視します。

関連するコンテンツ

• Azure Bot Framework SDK から Agents SDK への移行ガイダンス
• Azure Bot Framework SDK から Microsoft 365 エージェント SDK への .NET 用移行ガイダンス
• Node.js 向け Azure Bot Framework SDK から Microsoft 365 エージェント SDK への移行ガイダンス