microsoft-agents-hosting-core 1.3.0


pip install microsoft-agents-hosting-core

  Latest version

Released: Jul 30, 2026
Navigation
Project Links
Meta
Author: Microsoft Corporation
Requires Python: >=3.10
Classifiers

Programming Language
  • Python :: 3
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
  • Python :: 3.14

Operating System
  • OS Independent

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.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 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-fastapi PyPI Configures fastapi to run the Agent.
microsoft-agents-hosting-msteams PyPI Provides classes to host an Agent for Teams.
microsoft-agents-hosting-dialogs PyPI Dialog system with waterfall dialogs, prompts, and multi-turn conversation management.
microsoft-agents-hosting-slack PyPI Provides classes to host an Agent for Slack.
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.
microsoft-agents-authentication-entra-auth-sidecar PyPI 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 PyPI 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
1.3.0 Jul 30, 2026
1.2.0 Jul 20, 2026
1.2.0.dev20 Jul 14, 2026
1.2.0.dev16 Jul 11, 2026
1.2.0.dev10 Jul 10, 2026
1.2.0.dev9 Jul 09, 2026
1.2.0.dev7 Jul 08, 2026
1.2.0.dev5 Jul 07, 2026
1.2.0.dev4 Jun 24, 2026
1.2.0.dev1 Jun 23, 2026
1.2.0.dev0 Jun 20, 2026
1.1.0 Jun 19, 2026
1.1.0.dev9 Jun 19, 2026
1.1.0.dev8 Jun 18, 2026
1.1.0.dev7 Jun 16, 2026
1.1.0.dev1 Jun 03, 2026
1.1.0.dev0 May 23, 2026
1.0.0 May 22, 2026
0.10.0.dev9 May 22, 2026
0.10.0.dev8 May 20, 2026
0.10.0.dev7 May 19, 2026
0.10.0.dev6 May 15, 2026
0.10.0.dev5 May 13, 2026
0.10.0.dev4 May 02, 2026
0.10.0.dev3 Apr 30, 2026
0.10.0.dev2 Apr 29, 2026
0.10.0.dev1 Apr 17, 2026
0.10.0.dev0 Apr 16, 2026
0.9.1 May 04, 2026
0.9.0 Apr 15, 2026
0.9.0.dev11 Apr 15, 2026
0.9.0.dev10 Apr 11, 2026
0.9.0.dev9 Apr 08, 2026
0.9.0.dev8 Apr 04, 2026
0.9.0.dev7 Apr 03, 2026
0.9.0.dev6 Apr 02, 2026
0.9.0.dev5 Apr 01, 2026
0.9.0.dev4 Mar 27, 2026
0.9.0.dev3 Mar 24, 2026
0.9.0.dev2 Mar 17, 2026
0.9.0.dev1 Feb 25, 2026
0.8.0 Feb 24, 2026
0.8.0.dev4 Feb 18, 2026
0.8.0.dev3 Feb 12, 2026
0.8.0.dev2 Feb 05, 2026
0.8.0.dev0 Feb 04, 2026
0.7.0 Jan 21, 2026
0.7.0.dev16 Feb 04, 2026
0.7.0.dev12 Dec 17, 2025
0.7.0.dev10 Dec 09, 2025
0.7.0.dev8 Dec 03, 2025
0.7.0.dev6 Dec 02, 2025
0.7.0.dev4 Nov 27, 2025
0.7.0.dev1 Nov 21, 2025
0.7.0.dev0 Nov 19, 2025
0.6.1 Dec 01, 2025
0.6.0 Nov 18, 2025
0.6.0.dev17 Nov 15, 2025
0.6.0.dev16 Nov 14, 2025
0.6.0.dev15 Nov 13, 2025
0.6.0.dev11 Nov 12, 2025
0.6.0.dev10 Nov 06, 2025
0.6.0.dev9 Nov 01, 2025
0.6.0.dev8 Oct 31, 2025
0.6.0.dev7 Oct 29, 2025
0.6.0.dev4 Oct 28, 2025
0.6.0.dev1 Oct 23, 2025
0.5.3 Oct 31, 2025
0.5.2 Oct 31, 2025
0.5.1 Oct 28, 2025
0.5.0 Oct 22, 2025
0.5.0.dev19 Oct 22, 2025
0.5.0.dev17 Oct 21, 2025
0.5.0.dev11 Oct 16, 2025
0.5.0.dev10 Oct 15, 2025
0.5.0.dev7 Oct 14, 2025
0.5.0.dev5 Oct 11, 2025
0.5.0.dev3 Oct 09, 2025
0.4.0 Oct 07, 2025
0.4.0.dev18 Oct 08, 2025
0.4.0.dev16 Oct 07, 2025
0.4.0.dev14 Oct 03, 2025
0.4.0.dev10 Oct 02, 2025
0.4.0.dev7 Sep 11, 2025
0.4.0.dev6 Sep 10, 2025
0.4.0.dev4 Sep 09, 2025
0.4.0.dev3 Sep 05, 2025
0.4.0.dev1 Aug 28, 2025
0.3.2 Sep 17, 2025
0.3.1 Sep 09, 2025
0.3.0 Aug 27, 2025
0.3.0.dev0 Aug 19, 2025
0.2.0 Aug 18, 2025
0.2.0.dev1 Aug 15, 2025
0.1.2 Aug 12, 2025
0.1.1 Jul 28, 2025
0.0.0 Jul 25, 2025

Wheel compatibility matrix

Platform Python 3
any

Files in release

Extras: None
Dependencies:
microsoft-agents-activity (==1.3.0)
pyjwt (>=2.10.1)
isodate (>=0.6.1)
python-dotenv (>=1.1.1)
opentelemetry-api (>=1.27.0)
opentelemetry-sdk (>=1.27.0)