Registry / llm-agents / microsoft-agents-hosting-core

microsoft-agents-hosting-core

JSON →
library1.0.0pypypiunverified

The `microsoft-agents-hosting-core` library is the foundational component of the Microsoft 365 Agents SDK for Python. It provides the essential building blocks for creating conversational AI agents, handling core functionalities such as activity processing, state management, and channel communication. This library is crucial for orchestrating conversations and managing agent state across turns, enabling the development of production-ready agents for platforms like Microsoft Teams, M365 Copilot, Copilot Studio, and web chat. It is actively maintained with frequent updates.

pip install microsoft-agents-hosting-core
INSTALL
IMPORT
SIG · MICROSOFT-AGENTS-H
M
microsoft-agents-hosting-core
llm-agentspythonv1.0.0
Install
5.9s avg
Import
1556ms
Disk
49MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.940 runs
installs and imports cleanly · install 0.0s · import 1.621s · 50.1MB
glibc
py 3.103.940 runs
installs and imports cleanly · install 5.9s · import 1.491s · 51MB
49MB installed
● package 49MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AgentApplication
from microsoft_agents.hosting import AgentApplication
from microsoft_agents import AgentApplication

This quickstart demonstrates how to create a simple 'Echo Agent' using `microsoft-agents-hosting-core` and host it with `aiohttp`. It utilizes the `AgentApplication` class, which is the recommended modern API for building agents, replacing the older `ActivityHandler`. The example shows how to define an activity handler for 'message' activities, echoing back the user's input. It also includes boilerplate for authentication configuration, though it can run anonymously if environment variables for `TENANT_ID`, `CLIENT_ID`, and `CLIENT_SECRET` are not set. The `start_agent_process` function from `microsoft-agents-hosting-aiohttp` is used to launch the web server.

import os from aiohttp.web import Request, Response, Application from microsoft_agents.hosting.core import AgentApplication, AgentAuthConfiguration, TurnContext from microsoft_agents.hosting.aiohttp import ( start_agent_process, jwt_authorization_middleware, CloudAdapter, ) from microsoft_agents.activity import Activity # Define the Echo Agent using AgentApplication agent_app = AgentApplication() @agent_app.activity("message") async def message_activity_handler(turn_context: TurnContext): await turn_context.send_activity(Activity(text=f"Echo: {turn_context.activity.text}")) async def main(): # Example of setting up auth configuration (for non-anonymous hosting) # Use os.environ.get for dynamic configuration auth_config = AgentAuthConfiguration( TENANT_ID=os.environ.get('TENANT_ID', ''), CLIENT_ID=os.environ.get('CLIENT_ID', ''), CLIENT_SECRET=os.environ.get('CLIENT_SECRET', ''), # Add other auth parameters as needed ) # Start the agent using aiohttp, defaulting to anonymous if no client_id is set await start_agent_process( agent_app, CloudAdapter(), auth_config if auth_config.CLIENT_ID else None, # Pass auth_config only if credentials are provided middlewares=[jwt_authorization_middleware] if auth_config.CLIENT_ID else [], port=3978 # Default port for agents ) if __name__ == "__main__": import asyncio asyncio.run(main())
Debug
Known issues
breakingThe import structure for all packages within the Microsoft 365 Agents SDK for Python changed from `microsoft.agents` (using dots) to `microsoft_agents` (using underscores).
fix
Update all import statements from `from microsoft.agents...` to `from microsoft_agents...`.
affects: All versions prior to the change, including initial beta releases. Users migrating from early versions must update.
breakingThe broader Microsoft Agent Framework (of which `microsoft-agents-hosting-core` is a part) underwent a significant architectural shift in its 1.0.0 release. This moved from a 'project-centric agent setup' to a 'provider-leading client design', emphasizing `FoundryAgent` and separating provider implementations (e.g., OpenAI, Azure AI Foundry) into dedicated, lighter-weight packages.
fix
Refactor agent implementations to use `AgentApplication` and explicitly integrate with provider-specific packages like `agent-framework-openai` or `agent-framework-foundry`. The core library is now more abstract, focusing on middleware and telemetry.
affects: Users of `microsoft-agents-hosting-core` who previously relied on tightly integrated OpenAI/Azure AI components, especially in versions before the framework's 1.0.0 release.
breakingPersisted checkpoint deserialization is now restricted by default for security, only permitting a built-in set of safe Python types and framework types. If your application stores custom types in checkpoints, loading them will raise a `WorkflowCheckpointException`.
fix
Pass the 'module:qualname' identifiers of your custom types via the new `allowed_checkpoint_types` constructor parameter when configuring checkpoint storage. Refer to the 'Security Considerations' documentation for details.
affects: microsoft-agent-framework versions 1.0.0 and later.
deprecatedThe `ActivityHandler` class, while still functional, has been superseded by `AgentApplication` as the recommended, modern, and fluent API for building agents. `AgentApplication` offers decorator-based routing and built-in state management.
fix
Migrate new agent development to use `AgentApplication` for improved developer experience and integration with AI capabilities. Existing `ActivityHandler` implementations will continue to work but may not leverage the latest features.
affects: All versions where `AgentApplication` is available (0.5.0+).
gotchaAuthentication configuration for agents can be complex. While the quickstart demonstrates anonymous mode, production deployments will require proper `AgentAuthConfiguration` with `TENANT_ID`, `CLIENT_ID`, `CLIENT_SECRET` (or certificate-based auth), and potentially `SCOPES` or `AUTHORITY`.
fix
Thoroughly review the authentication documentation for Microsoft Agents SDK and secure your `TENANT_ID`, `CLIENT_ID`, and `CLIENT_SECRET` (or certificate files) using environment variables or a secure configuration management system. Avoid hardcoding sensitive credentials.
affects: All versions requiring authentication.
Upgrade
Version history
1.0.0latest on PyPI · released May 22, 2026
Audit
Dependencies
microsoft-agents-activityrequiredProvides core activity models and handling, essential for agent interactions.
python-dotenvoptionalOften used for managing environment variables, such as API keys, in development.
pyjwtrequiredUsed for JSON Web Token (JWT) authorization.
isodaterequiredLikely used for parsing and handling ISO 8601 formatted dates and times within activities or state.
azure-corerequiredProvides core Azure functionalities, potentially for shared utilities or authentication.
aiohttpoptionalRequired for hosting agents via HTTP endpoints using the microsoft-agents-hosting-aiohttp package.
fastapioptionalRequired for hosting agents via HTTP endpoints using the microsoft-agents-hosting-fastapi package (not explicitly mentioned as a dependency for 'core' but is a common hosting option).
Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
microsoft-agents-hosting-core — pip install microsoft-agents-hosting-core · libregistry