Pre-release

This release is a pre-release and may not be stable for production use.

Microsoft Agents Hosting Core

The core hosting library for Microsoft 365 Agents SDK. This library provides the fundamental building blocks for creating conversational AI agents, including activity processing, state management, authentication, and channel communication.

This is the heart of the Microsoft 365 Agents SDK - think of it as the engine that powers your conversational agents. It handles the complex orchestration of conversations, manages state across turns, and provides the infrastructure needed to build production-ready agents that work across Microsoft 365 platforms.

What is this?

This library is part of the Microsoft 365 Agents SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The SDK enables developers to create intelligent agents that work across multiple platforms including Microsoft Teams, M365 Copilot, Copilot Studio, and web chat, with support for third-party integrations like Slack, Facebook Messenger, and Twilio.

Release Notes

Version	Date	Release Notes
1.5.0	2026-08-26	1.5.0 Release Notes
1.4.0	2026-08-18	1.4.0 Release Notes
1.3.0	2026-07-30	1.3.0 Release Notes
1.2.0	2026-07-17	1.2.0 Release Notes
1.1.0	2026-06-19	1.1.0 Release Notes
1.0.0	2026-05-22	1.0.0 Release Notes
0.9.1	2026-05-04	0.9.1 Release Notes
0.9.0	2026-04-15	0.9.0 Release Notes
0.8.0	2026-02-23	0.8.0 Release Notes
0.7.0	2026-01-21	0.7.0 Release Notes
0.6.1	2025-12-01	0.6.1 Release Notes
0.6.0	2025-11-18	0.6.0 Release Notes
0.5.0	2025-10-22	0.5.0 Release Notes

Packages Overview

We offer the following PyPI packages to create conversational experiences based on Agents:

Package Name	PyPI Version	Description
`microsoft-agents-activity`		Types and validators implementing the Activity protocol spec.
`microsoft-agents-hosting-core`		Core library for Microsoft Agents hosting.
`microsoft-agents-hosting-aiohttp`		Configures aiohttp to run the Agent.
`microsoft-agents-hosting-fastapi`		Configures fastapi to run the Agent.
`microsoft-agents-hosting-msteams`		Provides classes to host an Agent for Teams.
`microsoft-agents-hosting-dialogs`		Dialog system with waterfall dialogs, prompts, and multi-turn conversation management.
`microsoft-agents-hosting-slack`		Provides classes to host an Agent for Slack.
`microsoft-agents-storage-blob`		Extension to use Azure Blob as storage.
`microsoft-agents-storage-cosmos`		Extension to use CosmosDB as storage.
`microsoft-agents-authentication-msal`		MSAL-based authentication for Microsoft Agents.
`microsoft-agents-authentication-entra-auth-sidecar`		Credential-free Entra ID Agent ID authentication via the sidecar.

Additionally we provide a Copilot Studio Client, to interact with Agents created in CopilotStudio:

Package Name	PyPI Version	Description
`microsoft-agents-copilotstudio-client`		Direct to Engine client to interact with Agents created in CopilotStudio

Installation

pip install microsoft-agents-hosting-core

Simple Echo Agent

See the Quickstart sample for full working code.

agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    await context.send_activity(f"You said: {context.activity.text}")

...

start_server(
    agent_application=AGENT_APP,
    auth_configuration=CONNECTION_MANAGER.get_default_connection_configuration(),
)

Core Concepts

AgentApplication vs ActivityHandler

AgentApplication - Modern, fluent API for building agents:

Decorator-based routing (@agent_app.activity("message"))
Built-in state management and middleware
AI-ready with authorization support
Type-safe with generics

ActivityHandler - Traditional inheritance-based approach:

Override methods for different activity types
More familiar to Bot Framework developers
Lower-level control over activity processing

Route-based Message Handling

@AGENT_APP.message(re.compile(r"^hello$"))
async def on_hello(context: TurnContext, _state: TurnState):
    await context.send_activity("Hello!")


@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    await context.send_activity(f"you said: {context.activity.text}")

Error Handling

@AGENT_APP.error
async def on_error(context: TurnContext, error: Exception):
    # NOTE: In production environment, you should consider logging this to Azure
    #       application insights.
    print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
    traceback.print_exc()

    # Send a message to the user
    await context.send_activity("The bot encountered an error or bug.")

Key Classes Reference

Core Classes

AgentApplication - Main application class with fluent API
ActivityHandler - Base class for inheritance-based agents
TurnContext - Context for each conversation turn
TurnState - State management across conversation turns

State Management

ConversationState - Conversation-scoped state
UserState - User-scoped state across conversations
TempState - Temporary state for current turn
MemoryStorage - In-memory storage (development)

Messaging

MessageFactory - Create different types of messages
CardFactory - Create rich card attachments
InputFile - Handle file attachments

Authorization

Authorization - Authentication and authorization manager
ClaimsIdentity - User identity and claims

Quick Links

Sample Applications

Name	Description	README
Quickstart	Simplest agent	Quickstart
Auto Sign In	Simple OAuth agent using Graph and GitHub	auto-signin
OBO Authorization	OBO flow to access a Copilot Studio Agent	obo-authorization
Semantic Kernel Integration	A weather agent built with Semantic Kernel	semantic-kernel-multiturn
Streaming Agent	Streams OpenAI responses	azure-ai-streaming
Copilot Studio Client	Console app to consume a Copilot Studio Agent	copilotstudio-client
Cards Agent	Agent that uses rich cards to enhance conversation design	cards

Release files for microsoft-agents-hosting-core 1.6.1.dev9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for microsoft-agents-hosting-core 1.6.1.dev9
File	Size	Uploaded
microsoft_agents_hosting_core-1.6.1.dev9.tar.gz	157.7 kB	Sep 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for microsoft-agents-hosting-core 1.6.1.dev9
File	Interpreter	ABI	Platform	Reset
microsoft_agents_hosting_core-1.6.1.dev9-py3-none-any.whl 230.5 kB Sep 15, 2026	Python 3	none	any	Details

Total release size: 388.2 kB

Release files / microsoft_agents_hosting_core-1.6.1.dev9.tar.gz

Download URL	microsoft_agents_hosting_core-1.6.1.dev9.tar.gz
Size	157.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`dc57df0159ee1315256a96feb605c84c3477ab630b2015ea71ce30a761ddccab`
BLAKE2b-256 checksum How to use checksums	`87956fbf8f78cb02850ebb0b0b40b64d2395b5bafa268ff692c6c672ec7521f8`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`RestSharp/106.13.0.0`

Release files / microsoft_agents_hosting_core-1.6.1.dev9-py3-none-any.whl

Download URL	microsoft_agents_hosting_core-1.6.1.dev9-py3-none-any.whl
Size	230.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7206f403c33f7fafeb28b7c27945987b87faa657d788ec6d0f2ec35a1cab7e59`
BLAKE2b-256 checksum How to use checksums	`4f09ba80ac8b04b377636f0c2449d70af57fb66cfee58fd722407d3c55ce7949`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`RestSharp/106.13.0.0`