Microsoft Agents Hosting for aiohttp

0.9.0 verified Fri May 01 auth: no python

Integration library for hosting Microsoft Agents applications using the aiohttp web framework. Version 0.9.0 supports Python >=3.10 and provides middleware and routing for building agent-based HTTP services.

pip install microsoft-agents-hosting-aiohttp

Common errors

error ModuleNotFoundError: No module named 'microsoft' ↓

cause The package 'microsoft-agents-hosting-aiohttp' is not installed, or installed but import path is wrong.

fix

Run 'pip install microsoft-agents-hosting-aiohttp' and import using 'from microsoft.agents.hosting.aiohttp import ...'

error TypeError: __init__() got an unexpected keyword argument 'settings' ↓

cause Using old API where AioHttpHost accepted 'settings' dict directly.

fix

Use CloudAdapter for configuration: AioHttpHost(app=app, adapter=CloudAdapter(...))

error RuntimeError: Application not configured for agents ↓

cause Agent routes were not registered because 'host.register_routes()' was not called.

fix

After creating AioHttpHost instance, call 'host.register_routes()' before starting the app.

Warnings

breaking The package was renamed from 'agents-hosting-aiohttp' to 'microsoft-agents-hosting-aiohttp' in version 0.9.0. Old import paths will break. ↓

fix Update import to 'from microsoft.agents.hosting.aiohttp import ...'

deprecated The 'AioHttpHost' constructor no longer accepts 'settings' parameter directly; use 'CloudAdapter' for configuration. ↓

fix Pass adapter=CloudAdapter(...) instead of settings dict.

gotcha Missing BOT_APP_ID or BOT_APP_PASSWORD environment variables will cause runtime authentication failures without clear error messages. Always set them or use local adapter for development. ↓

fix Set BOT_APP_ID and BOT_APP_PASSWORD environment variables, or use CloudAdapter with app_id='' and password='' for local testing.

Imports

AioHttpHost

wrong

from agents.hosting.aiohttp import AioHttpHost

correct

from microsoft.agents.hosting.aiohttp import AioHttpHost

Package namespace uses 'microsoft.agents' not 'agents'

Quickstart

Creates an aiohttp web application with Microsoft Agent hosting middleware.

import os
from aiohttp import web
from microsoft.agents.hosting.aiohttp import AioHttpHost, CloudAdapter

app = web.Application()
host = AioHttpHost(
    app=app,
    adapter=CloudAdapter(
        bot_app_id=os.environ.get('BOT_APP_ID', ''),
        bot_app_password=os.environ.get('BOT_APP_PASSWORD', '')
    )
)
host.register_routes()

if __name__ == '__main__':
    web.run_app(app, port=3978)