Install & Compatibility
Where this runs
tested against v4.17.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.544s · 55.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.6s · import 1.430s · 58MB
56MB installed
● package 56MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ActivityHandler
✓ from botbuilder.core import ActivityHandler
TurnContext
✓ from botbuilder.core import TurnContext
BotFrameworkAdapter
✓ from botbuilder.core import BotFrameworkAdapter
✗ from botbuilder.adapters.botframework import BotFrameworkAdapter
While BotFrameworkAdapter is available directly in botbuilder-core, for AIOHTTP integration, BotFrameworkHttpAdapter from botbuilder-integration-aiohttp is typically used instead.
BotFrameworkHttpAdapter
✓ from botbuilder.integration.aiohttp import BotFrameworkHttpAdapter
This specific adapter is needed to run a bot with the aiohttp web framework.
This quickstart demonstrates a basic 'echo' bot using `botbuilder-core`'s `ActivityHandler` and `TurnContext`. It's integrated with an `aiohttp` web server via `BotFrameworkHttpAdapter` from `botbuilder-integration-aiohttp` to create a runnable endpoint. Run this code and connect to it using the Bot Framework Emulator or another channel.
import os
import asyncio
from aiohttp import web
from botbuilder.core import ActivityHandler, TurnContext
from botbuilder.schema import Activity
from botbuilder.integration.aiohttp import BotFrameworkHttpAdapter
class MyEchoBot(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: [object], turn_context: TurnContext):
for member in members_added:
if member.id != turn_context.activity.recipient.id:
await turn_context.send_activity("Hello and welcome!")
# Configuration (replace with your actual values or env vars)
# For local testing without authentication, these can be empty strings
APP_ID = os.environ.get("MicrosoftAppId", "")
APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
# Create the BotFrameworkHttpAdapter
adapter = BotFrameworkHttpAdapter(APP_ID, APP_PASSWORD)
# Create the bot instance
bot = MyEchoBot()
# Listen for incoming requests on /api/messages
async def messages(request):
if "application/json" in request.headers["Content-Type"]:
body = await request.json()
else:
return web.Response(status=400)
activity = Activity().deserialize(body)
auth_header = request.headers["Authorization"] if "Authorization" in request.headers else ""
try:
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=200)
except Exception as e:
print(f"Error processing activity: {e}")
return web.Response(status=500, text=str(e))
# Setup AIOHTTP web application
app = web.Application()
app.router.post("/api/messages", messages)
if __name__ == "__main__":
try:
web.run_app(app, host="localhost", port=3978)
except Exception as e:
raise e
Debug
Known issues
breakingThe Microsoft Bot Framework Python SDK, including `botbuilder-core`, has reached End-of-Life (EOL) with version 4.17.1. It is no longer actively maintained, supported, or receiving updates. New development should avoid this library.fixMigrate to alternative solutions for building conversational agents, such as the Microsoft 365 Agents SDK or other active bot development frameworks. Do not start new projects with this SDK.
affects: 4.17.1 and later
gotchaAs of SDK version 4.15.0, the underlying `aiohttp` dependency requires Python 3.8 or newer. Bots deployed on Python 3.7 or older will encounter dependency conflicts or runtime errors.fixEnsure your development and deployment environments are using Python 3.8 or a later compatible version.
affects: 4.15.0+
gotchaThe library is built on `asyncio`. All bot logic, especially I/O operations and callbacks, must be `async` and properly `await`ed. Failure to do so can lead to deadlocks, unresponsive bots, or silent failures.fixFamiliarize yourself with Python's `asyncio` framework. Ensure all methods interacting with `TurnContext` or performing network/disk I/O are `async def` and called using `await`.
affects: All versions
gotchaAuthentication is crucial for secure bots. Bots typically require `MicrosoftAppId` and `MicrosoftAppPassword` for production deployments. Running locally without these credentials might require specific adapter configurations to disable authentication checks, which is not recommended for production.fixAlways configure `MicrosoftAppId` and `MicrosoftAppPassword` (preferably via environment variables) for production bots. For local testing, ensure your emulator or client is correctly configured for local authentication or that your adapter is explicitly set to allow unauthenticated access (for development only).
affects: All versions
deprecatedWhile a temporary 'deprecation cancelled' notice appeared for version 4.14.5, the SDK ultimately did reach End-of-Life with 4.17.1. This inconsistency might cause confusion for developers checking release notes.fixTreat the SDK as fully abandoned. The EOL status of 4.17.1 overrides any previous indications.
affects: 4.14.5, 4.17.1
Upgrade
Version history
4.17.1latest on PyPI · released Jan 5, 2026
Audit
Dependencies
aiohttprequiredUsed for asynchronous HTTP communication and a common web server for bot endpoints.
botbuilder-integration-aiohttpoptionalProvides the BotFrameworkHttpAdapter to integrate with aiohttp web applications, essential for a runnable bot.