Microsoft Agents Hosting Core

0.8.0 · active · verified Tue Apr 14

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.

Warnings

breaking The 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...`.
breaking The 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.
breaking Persisted 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.
deprecated The `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.
gotcha Authentication 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.

Install

pip install microsoft-agents-hosting-core Install core library
pip install microsoft-agents-hosting-aiohttp Install with aiohttp for web hosting

Imports

AgentApplication
```
from microsoft_agents.hosting.core import AgentApplication
```
The import path changed from dots to underscores across the SDK in a recent breaking change (prior to v0.8.0). `AgentApplication` is the modern, fluent API for building agents, replacing the inheritance-based `ActivityHandler` for new agent development.
AgentAuthConfiguration
```
from microsoft_agents.hosting.core import AgentAuthConfiguration
```
The import path changed from dots to underscores across the SDK in a recent breaking change (prior to v0.8.0).
TurnContext
```
from microsoft_agents.hosting.core import TurnContext
```
The import path changed from dots to underscores across the SDK in a recent breaking change (prior to v0.8.0).
ActivityHandler
```
from microsoft_agents.hosting.core import ActivityHandler
```
The import path changed from dots to underscores across the SDK in a recent breaking change (prior to v0.8.0). While still available, `AgentApplication` is the recommended approach for new agents.
start_agent_process
```
from microsoft_agents.hosting.aiohttp import start_agent_process
```
The `start_agent_process` function for aiohttp hosting is part of `microsoft-agents-hosting-aiohttp`, a separate package, and its import path also follows the underscore convention.

Quickstart

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())

view raw JSON →