Azure Bot Framework SDK를 Microsoft 365 에이전트 SDK로 마이그레이션하기 위한 Python 지침

이 문서에서는 Python Bot Framework SDK에서 Python Microsoft 365 에이전트 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 더 이상 사용하지 않습니다. 새 설정을 검증한 후에 이 설정들을 제거할 수 있습니다.

첫 번째 단계

패키지 종속성을 업데이트하여 시작합니다. 다음 변경 내용은 터치해야 할 수 있는 모든 네임스페이스를 다루지는 않지만 대부분의 패키지 대체를 처리합니다.

패키지 종속성 업데이트

봇이 Microsoft Teams 통합되는 경우 핵심 Teams 기능에 대한 Teams 확장 패키지 microsoft-agents-hosting-teams 포함합니다.

인증을 위해서는 MSAL 기반 인증을 처리하기 위해 microsoft-agents-authentication-msal를 추가하세요.

봇 프레임워크 패키지를 에이전트 SDK와 동등한 것으로 교체하도록 본인 requirements.txt 또는 이에 상응하는 의존성 파일을 업데이트하세요. pip install -r requirements.txt 새로운 의존성을 설치하려면 원하는 패키지 관리자나 사용하세요.

에이전트 SDK는 black 서식 지정 및 flake8 린팅을 통해 코드 품질 표준을 준수하도록 강제합니다. 이러한 도구들을 개발 의존성에 추가하는 것을 고려해 보세요.

임포트 업데이트

다음으로, 가져오기를 업데이트하세요. 가장 쉬운 방법은 프로젝트 전체에서 정확한 텍스트를 찾고 교체하는 것입니다.

유형 및 클래스 이름 변경

일부 유형과 클래스는 에이전트 SDK에서 서로 다른 이름을 가집니다. 다음 매핑을 참고하여 변경 사항을 안내하세요.

활동 클래스 변경

Agents SDK의 클래스는 ActivityPydantic을 사용하여 내장된 검증 기능을 포함하고 있습니다. JSON이나 사전 Activity.model_validate()에서 활동을 파싱하고 검증할 수 있습니다.

또한, 이 클래스는 Activity 활동 페이로드와 관련된 연산을 중앙 집중화합니다. 이전에 TurnContext의 정적 메서드였던 것들은 이제 Activity의 인스턴스 메서드가 되었습니다.

일반적인 turn_state 참조를 업데이트합니다. 그에 따라 다음 사용량을 바꿉니다.

구성

에이전트 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

마이그레이션 참고: 다음 표와 같이 환경 변수 이름을 업데이트합니다.

에이전트 SDK 구성은 중첩된 구성 계층을 나타내기 위해 이중 밑줄무늬__()를 사용합니다. 이 패턴은 다양한 배포 환경 간에 유연한 구성 관리를 가능하게 합니다.

시작 및 초기화

초기화 방식은 에이전트 SDK에서 다릅니다. 봇 프레임워크 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)

에이전트 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}")

에이전트 SDK load_configuration_from_env() 는 환경 변수에서 자동으로 구성을 로드하여 수동 구성 파싱을 없애줍니다. 데코레이터 패턴은 명시적인 클래스 기반 상속 없이 핸들러를 선언적으로 등록할 수 있게 해줍니다.

인증 및 보안

Bot Framework SDK는 어댑터에 JSON 웹 토큰(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 기반으로 합니다.

에이전트 SDK는 유사한 API 표면을 유지하여 마이그레이션을 용이하게 하는 호환 ActivityHandler 버전을 제공합니다.

주요 차이점

핸들러 메서드 서명 변경

봇 프레임워크 SDK 핸들러는 일반적으로 위치 매개변수를 사용하며, 에이전트 SDK 핸들러는 기본 매개변수로 동일한 패턴 TurnContext 을 유지합니다.

에이전트 SDK의 추가 메서드

에이전트 SDK에서 누락된 메서드

마이그레이션 예제

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)

스토리지 옵션

에이전트 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"
)

로깅

에이전트 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)

로그 수준

• 디버그: 상세한 로컬 상태 추적
• 정보: 활동 처리, API 호출, 외부 기관과의 요청
• 경고: 잠재적 문제를 일으키는 예상치 못한 사건들
• 오류: 발견되었든 잡히지 않았든 관찰된 오류

일반적인 마이그레이션 패턴

간단한 에코봇

Bot Framework SDK의 Simple echo bot

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을 사용하여야 합니다.

형식 힌트

에이전트 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 되어 있는지 확인하거나 Emulator의 인증 설정을 사용하세요.

Python 버전 호환성

Python 3.10 이상을 사용하고 있는지 확인합니다. 에이전트 SDK는 이전 버전에서 사용할 수 없는 최신 Python 기능을 사용합니다.

마이그레이션 검사 목록

✓ 분석 및 계획: 사용 중단된 기능을 식별하고 마이그레이션 또는 재구축 범위를 결정합니다. ✓ 업그레이드 Python 버전: Python 3.10 이상으로 이동(3.11 이상 권장). ✓ 패키지 교체: botbuilder-* 제거, microsoft-agents-* 추가(hosting-core, activity, hosting-aiohttp, authentication-msal, storage providers, hosting-teams). ✓ 가져오기 업데이트: 위 표에 따라 찾기/교체 적용; 모든 microsoft.agents 것을 microsoft_agents로 변환합니다. ✓ 타입 및 클래스 업데이트: 변경된 API를 수정하고 정적 메서드를 인스턴스 메서드로 TurnContext 이동 Activity 하세요. ✓ 구성 업데이트: 파일을 이중 밑줄로 계층적으로 명명하여 .env 생성합니다. ✓ 초기화 업데이트: CloudAdapter와 MsalAuth.from_environment(), 그리고 AgentsHttpMiddleware를 사용하세요. ✓ 로깅 구성: microsoft_agents 로거에 대한 Python 로깅을 설정합니다. ✓ 로컬에서 빌드 및 테스트: 자격 증명과 함께 봇 프레임워크 에뮬레이터 사용; 핵심 시나리오를 검증하세요. ✓ 지원 및 모니터: 새 구성과 일치하도록 Azure 환경 변수를 업데이트하고 출시 후 로그를 확인합니다.

관련 콘텐츠

• Azure Bot Framework SDK에서 Agents SDK로 마이그레이션 지침
• .NET 용 Azure Bot Framework SDK에서 Microsoft 365 에이전트 SDK로의 마이그레이션 지침
• Node.js에 대한 Azure Bot Framework SDK에서 Microsoft 365 에이전트 SDK로의 마이그레이션 지침