Diretrizes de migração do Azure Bot Framework SDK para o SDK de Agentes do Microsoft 365 para Python

Este artigo descreve as alterações necessárias para migrar do SDK do Bot Framework para Python para o SDK de Agentes do Microsoft 365 para Python.

Tip

Trate esse trabalho como um esforço de modernização, e não apenas uma troca de pacote. O SDK Agents favorece padrões mais simples e sem opinião (assync/await, injeção de dependências, log padrão) e remove recursos legados. Mantenha apenas aquilo de que seu bot realmente precisa e evite levar adiante a complexidade do modelo antigo.

Pré-requisitos

Python versão 3.10 ou superior (3.11+ recomendado, dá suporte a até 3.14)
Projeto do SDK do Bot Framework existente
Recurso do Azure Serviço de Bot

Recursos do Azure

Os recursos de Azure existentes permanecem inalterados durante essa migração. Continue usando o registro atual do bot Azure (ID do aplicativo e segredo). Você faz referência a esses valores na nova estrutura de configuração descrita mais adiante. Muitas soluções também incluem configurações de aplicativos legados como APP_ID, APP_PASSWORD, e APP_TENANT_ID. Essas entradas são inofensivas durante a migração, mas o SDK de Agentes do Microsoft 365 não as usa mais. Você pode remover essas configurações depois de validar a nova configuração.

Primeiras etapas

Comece atualizando as dependências de pacote. As alterações a seguir não abrangem todos os namespaces que talvez seja necessário tocar, mas elas lidam com a maioria das substituições do pacote.

Atualizar dependências de pacote

SDK do Bot Framework	SDK de Agentes
`botbuilder-core`	`microsoft-agents-hosting-core`
`botbuilder-schema`	`microsoft-agents-activity`
`botbuilder-azure`	`microsoft-agents-storage-blob` e `microsoft-agents-storage-cosmos`
`botbuilder-integration-aiohttp`	`microsoft-agents-hosting-aiohttp`

Se o bot se integrar ao Microsoft Teams, inclua o pacote de Extensão do Teams microsoft-agents-hosting-teams para os principais recursos do Teams.

Para autenticação, adicione microsoft-agents-authentication-msal para gerenciar a autenticação baseada em MSAL.

Atualize requirements.txt ou arquivo de dependência equivalente para substituir os pacotes do Bot Framework pelos equivalentes do SDK de Agentes. Use pip install -r requirements.txt ou seu gerenciador de pacotes preferido para instalar as novas dependências.

O SDK de Agentes aplica padrões de qualidade de código usando black para formatação e flake8 para efetuar lint. Considere adicionar essas ferramentas às suas dependências de desenvolvimento.

Atualizar importações

Important

O SDK Agents usa sublinhados nos caminhos de importação (microsoft_agents) em vez de pontos (microsoft.agents). Essa mudança afeta todas as importações.

Em seguida, atualize as importações. A abordagem mais fácil é um processo de busca e substituição do texto exato em todo o projeto.

Importação do Framework de Bots	Importação do SDK de Agentes
`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 ...`

Renomeação de tipos e classes

Alguns tipos e classes têm nomes diferentes no SDK de Agentes. Use os mapeamentos a seguir para orientar suas mudanças.

Bot Framework	SDK de Agentes
`BotState`	`AgentState`
`BotFrameworkAdapter`	`CloudAdapter`
`BotFrameworkHttpClient`	`AgentHttpClient`
`OAuthPromptSettings.connection_name`	`OAuthPromptSettings.azure_bot_oauth_connection_name`

Mudanças de classe de atividade

A Activity classe no SDK Agents inclui validação embutida usando o Pydantic. Você pode analisar e validar atividades a partir de JSON ou dicionários usando Activity.model_validate().

Além disso, a Activity classe centraliza operações relacionadas a payloads de atividade. Métodos que antes eram estáticos em TurnContext agora são métodos de instância em Activity:

Método Estático do Bot Framework	Método de Instância do SDK de Agentes
`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()`

Atualize referências turn_state comuns. Substitua devidamente os usos a seguir.

Bot Framework	SDK de Agentes
`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`

Configuração

O SDK Agents utiliza variáveis de ambiente com uma convenção hierárquica de nomes para configuração.

Variáveis de ambiente

Crie ou atualize seu .env arquivo com a seguinte estrutura:

# 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

Observação de Migração: atualize os nomes das variáveis de ambiente, conforme mostrado na tabela a seguir:

SDK do Bot Framework	SDK de Agentes
`APP_ID` ou `MICROSOFT_APP_ID`	`CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID`
`APP_PASSWORD` ou `MICROSOFT_APP_PASSWORD`	`CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET`
`APP_TENANT_ID` ou `MICROSOFT_APP_TENANT_ID`	`CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID`

A configuração do Agents SDK utiliza sublinhados duplos (__) para representar hierarquias de configuração aninhadas. Esse padrão permite uma gestão flexível de configuração em diferentes ambientes de implantação.

Início e inicialização

A inicialização difere no SDK dos Agentes. O Bot Framework SDK normalmente é usado aiohttp com configuração manual de adaptadores. Usando o SDK Agents, você pode usar os utilitários de servidor integrados para uma configuração simplificada.

Configuração do servidor

Abordagem do SDK do 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)

Abordagem de SDK de Agentes (padrão decorador)

A abordagem recomendada utiliza o AgentApplication com decoradores para um estilo mais moderno e declarativo:

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

O SDK Agents permite load_configuration_from_env() carregar automaticamente a configuração a partir de variáveis de ambiente, eliminando a análise manual de configuração. O padrão decorador permite registrar os manipuladores declarativamente sem herança explícita baseada em classes.

Autenticação e segurança

O Bot Framework SDK incluía validação JSON Web Token (JWT) no adaptador. O SDK Agents separa as preocupações de autenticação, então você pode configurar middleware de autenticação explicitamente.

Para ambientes de produção, certifique-se de que a validação do JWT seja habilitada por meio da CloudAdapter configuração. O adaptador valida automaticamente as solicitações recebidas usando a configuração de autenticação MSAL.

Para desenvolvimento local com o Bot Framework Emulator, você pode usar credenciais vazias no seu arquivo .env:

# Only for local development with Emulator
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__ANONYMOUS_ALLOWED=True

Tratamento de atividades

A maioria dos bots criados com o SDK do Bot Framework baseia-se na classe base ActivityHandler.

O SDK de Agentes fornece um ActivityHandler compatível que mantém uma superfície de API semelhante para facilitar a migração.

Principais diferenças

Alterações na assinatura do método Handler

Os manipuladores de SDK do Bot Framework normalmente usam parâmetros posicionais, enquanto os handlers do SDK dos Agentes mantêm o mesmo padrão com TurnContext como parâmetro principal.

Métodos adicionais no SDK de Agentes

Método	Description
`on_message_delete()`	Manipula atividades de exclusão de mensagens
`on_message_update()`	Manipula as atividades de atualização de mensagens
`on_sign_in_invoke()`	Manipula as atividades de invocação de entrada

Métodos ausentes no SDK de Agentes

Método	Motivo
`on_command_activity()`	Não há suporte para atividades de comando
`on_command_result_activity()`	Não há suporte para atividades de resultado de comando

Exemplo de migração

SDK do Bot Framework

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 de Agentes

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

A migração é em sua maioria simples, com as principais mudanças sendo as declarações de importação. A maioria dos bots baseados em ActivityHandler funcionam com modificações mínimas.

Gerenciamento de estado

ConversationState, UserState e PrivateConversationState são compatíveis com algumas diferenças. Os padrões de gerenciamento de estado central são semelhantes ao SDK do Bot Framework.

Você deve registrar os objetos de estado e salvá-los explicitamente após modificações.

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)

Opções de armazenamento

O SDK Agents fornece implementações de armazenamento para diferentes 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"
)

Registrar em log

O SDK de Agentes usa o módulo logging padrão do Python. Configure o loging no seu arquivo principal de aplicação:

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)

Níveis de log

DEPURAÇÃO: rastreamento local de estado detalhado
INFO: Tratamento de atividades, chamadas de API e requisições para ou de entidades externas
AVISO: Eventos inesperados que causam problemas potenciais
ERRO: erros observados, sejam capturados ou não

Padrões comuns de migração

Echo bot simples

Echo bot simples no SDK do 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 simples no SDK dos Agentes

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

Gerenciamento do estado com contador

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

Solução de problemas e dicas

As dicas a seguir podem ajudar você a ser mais bem-sucedido.

Erros de importação

Se você encontrar erros de importação, certifique-se de usar sublinhados (microsoft_agents) em vez de pontos (microsoft.agents) em todas as instruções de importação. Esse erro é o problema de migração mais comum.

Padrões assíncronos ou de espera

Todos os métodos de bots devem ser async e usar await para operações assíncronas. Garanta que todas as chamadas para send_activity, operações de estado e operações de diálogo utilizem await.

Anotações de tipo

O SDK de Agentes usa dicas de tipo Python extensivamente. Considere adicionar anotações de tipo ao seu código de bot para melhor suporte ao IDE e detecção de erros.

from microsoft_agents.hosting.core import TurnContext

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

Validação de configuração

Se seu bot não iniciar devido a erros de configuração, verifique se os nomes das variáveis do ambiente usam a notação correta de duplo sublinhado (__) e que você definiu todos os valores necessários.

Erros 401 locais durante a depuração

Se você encontrar erros 401 durante a depuração local usando o Bot Framework Emulator, verifique se suas credenciais estão corretamente configuradas no .env arquivo ou use as configurações de autenticação do emulador.

Compatibilidade de versão do Python

Verifique se você está usando Python 3.10 ou superior. O SDK de Agentes usa recursos de Python modernos que não estão disponíveis em versões anteriores.

Lista de verificação de migração

✓ Analisar e planejar: Identificar quaisquer recursos obsoletos e decidir o escopo de migração versus reconstrução. ✓ Atualizar versão do Python: atualizar para Python 3.10 ou superior (3.11+ é recomendado). ✓ Substituir pacotes: remover botbuilder-*;, adicionar microsoft-agents-* (hospedagem-principal, atividade, hospedagem-aiohttp, autenticação-msal, provedores de armazenamento, hospedagem-equipes). ✓ Atualizar importações: aplica localizar/substituir conforme as tabelas acima; altere todos microsoft.agents para microsoft_agents. ✓ Atualizar tipos e classes: Corrija APIs renomeadas e move TurnContext métodos estáticos para Activity métodos de instância. ✓ Atualizar configuração: Criar .env arquivo com nomeação hierárquica (duplo sublinhado). ✓ Atualizar inicialização: use CloudAdapter com MsalAuth.from_environment() e AgentsHttpMiddleware. ✓ Configuração de log: configure o log Python para o logger microsoft_agents. ✓ Construir e testar localmente: Use o Bot Framework Emulator com credenciais; Valide cenários centrais. ✓ Deploy e monitor: atualize as variáveis de ambiente no Azure para que correspondam à nova configuração e observe os logs após a implementação.

Comentários

Esta página foi útil?

Last updated on 2026-05-13