Microsoft Bot Framework Python SDK (Core)

4.17.1 · abandoned · verified Sun Apr 12

The `botbuilder-core` library provides the foundational abstractions for building conversational AI bots using the Microsoft Bot Framework in Python. It includes base classes for handling activities, managing turns, and accessing conversation state. As of version 4.17.1, the entire Bot Framework Python SDK has reached End-of-Life (EOL) and will no longer receive updates or support. The project is effectively abandoned.

Warnings

breaking The 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.
Fix: Migrate 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.
gotcha As 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.
Fix: Ensure your development and deployment environments are using Python 3.8 or a later compatible version.
gotcha The 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.
Fix: Familiarize 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`.
gotcha Authentication 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.
Fix: Always 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).
deprecated While 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.
Fix: Treat the SDK as fully abandoned. The EOL status of 4.17.1 overrides any previous indications.

Install

pip install botbuilder-core botbuilder-integration-aiohttp Install core and AIOHTTP integration

Imports

ActivityHandler

from botbuilder.core import ActivityHandler

TurnContext
```
from botbuilder.core import TurnContext
```
BotFrameworkAdapter
```
from botbuilder.core 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.

Quickstart

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

view raw JSON →