Meta

• Author: Microsoft Corporation License-Expression: MIT
• Requires: Python >=3.10

Classifiers

• Operating System
  • OS Independent
• Programming Language
  • Python :: 3
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
  • Python :: 3.14

Microsoft Agents Hosting Core

👁 PyPI version

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.0.0	2026-05-22	1.0.0 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	👁 PyPI	Types and validators implementing the Activity protocol spec.
microsoft-agents-hosting-core	👁 PyPI	Core library for Microsoft Agents hosting.
microsoft-agents-hosting-aiohttp	👁 PyPI	Configures aiohttp to run the Agent.
microsoft-agents-hosting-teams	👁 PyPI	Provides classes to host an Agent for Teams.
microsoft-agents-storage-blob	👁 PyPI	Extension to use Azure Blob as storage.
microsoft-agents-storage-cosmos	👁 PyPI	Extension to use CosmosDB as storage.
microsoft-agents-authentication-msal	👁 PyPI	MSAL-based authentication for Microsoft Agents.

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

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

Installation

pipinstallmicrosoft-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 defon_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 defon_hello(context: TurnContext, _state: TurnState):
 await context.send_activity("Hello!")


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

Error Handling

@AGENT_APP.error
async defon_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

• 📦 All SDK Packages on PyPI
• 📖 Complete Documentation
• 💡 Python Samples Repository
• 🐛 Report Issues

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

Verified details

These details have been verified by PyPI

Maintainers

👁 Avatar for microsoft from gravatar.com
microsoft

Unverified details

These details have not been verified by PyPI

Project links

• Homepage

• Download URL: microsoft_agents_hosting_core-1.0.0.tar.gz
• Upload date: May 22, 2026
• Size: 122.5 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: RestSharp/106.13.0.0

Hashes for microsoft_agents_hosting_core-1.0.0.tar.gz

Algorithm	Hash digest
SHA256	97619d012fcdfe530364a98ffccb244304f4f0a1bc37b0d90dab7eb8ebefcab3
MD5	8b4b121f1fadfe730388c5026669b4a6
BLAKE2b-256	832b8ef8e551b855cbf57c181ba890c6d5a7990ed2cd6a794cfde7e71b9b4006

See more details on using hashes here.

• Download URL: microsoft_agents_hosting_core-1.0.0-py3-none-any.whl
• Upload date: May 22, 2026
• Size: 186.3 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: RestSharp/106.13.0.0

Hashes for microsoft_agents_hosting_core-1.0.0-py3-none-any.whl

Algorithm	Hash digest
SHA256	8c2299670e852f436faef9804b7cad65706d094df683a492a6c8ee7a9f816775
MD5	39dce9323d802da4f9b24f7a43332101
BLAKE2b-256	ad833a08f7581913ce7351065e41d6e26227782f050a6583527a4359ccf6b622

See more details on using hashes here.