Registry /
llm-agents / microsoft-agents-hosting-core
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
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 1.621s · 50.1MB
glibcpy 3.10–3.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).fixUpdate 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.fixRefactor 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`.fixPass 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.fixMigrate 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`.fixThoroughly 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).