{"id":5996,"library":"microsoft-agents-hosting-core","title":"Microsoft Agents Hosting Core","description":"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.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/microsoft/Agents","tags":["microsoft","agents","conversational-ai","sdk","hosting","m365"],"install":[{"cmd":"pip install microsoft-agents-hosting-core","lang":"bash","label":"Install core library"},{"cmd":"pip install microsoft-agents-hosting-aiohttp","lang":"bash","label":"Install with aiohttp for web hosting"}],"dependencies":[{"reason":"Provides core activity models and handling, essential for agent interactions.","package":"microsoft-agents-activity","optional":false},{"reason":"Often used for managing environment variables, such as API keys, in development.","package":"python-dotenv","optional":true},{"reason":"Used for JSON Web Token (JWT) authorization.","package":"pyjwt","optional":false},{"reason":"Likely used for parsing and handling ISO 8601 formatted dates and times within activities or state.","package":"isodate","optional":false},{"reason":"Provides core Azure functionalities, potentially for shared utilities or authentication.","package":"azure-core","optional":false},{"reason":"Required for hosting agents via HTTP endpoints using the microsoft-agents-hosting-aiohttp package.","package":"aiohttp","optional":true},{"reason":"Required 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).","package":"fastapi","optional":true}],"imports":[{"note":"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.","wrong":"from microsoft.agents.hosting.core import AgentApplication","symbol":"AgentApplication","correct":"from microsoft_agents.hosting.core import AgentApplication"},{"note":"The import path changed from dots to underscores across the SDK in a recent breaking change (prior to v0.8.0).","wrong":"from microsoft.agents.hosting.core import AgentAuthConfiguration","symbol":"AgentAuthConfiguration","correct":"from microsoft_agents.hosting.core import AgentAuthConfiguration"},{"note":"The import path changed from dots to underscores across the SDK in a recent breaking change (prior to v0.8.0).","wrong":"from microsoft.agents.hosting.core import TurnContext","symbol":"TurnContext","correct":"from microsoft_agents.hosting.core import TurnContext"},{"note":"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.","wrong":"from microsoft.agents.hosting.core import ActivityHandler","symbol":"ActivityHandler","correct":"from microsoft_agents.hosting.core import ActivityHandler"},{"note":"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.","wrong":"from microsoft.agents.hosting.aiohttp import start_agent_process","symbol":"start_agent_process","correct":"from microsoft_agents.hosting.aiohttp import start_agent_process"}],"quickstart":{"code":"import os\nfrom aiohttp.web import Request, Response, Application\nfrom microsoft_agents.hosting.core import AgentApplication, AgentAuthConfiguration, TurnContext\nfrom microsoft_agents.hosting.aiohttp import (\n    start_agent_process,\n    jwt_authorization_middleware,\n    CloudAdapter,\n)\nfrom microsoft_agents.activity import Activity\n\n# Define the Echo Agent using AgentApplication\nagent_app = AgentApplication()\n\n@agent_app.activity(\"message\")\nasync def message_activity_handler(turn_context: TurnContext):\n    await turn_context.send_activity(Activity(text=f\"Echo: {turn_context.activity.text}\"))\n\nasync def main():\n    # Example of setting up auth configuration (for non-anonymous hosting)\n    # Use os.environ.get for dynamic configuration\n    auth_config = AgentAuthConfiguration(\n        TENANT_ID=os.environ.get('TENANT_ID', ''),\n        CLIENT_ID=os.environ.get('CLIENT_ID', ''),\n        CLIENT_SECRET=os.environ.get('CLIENT_SECRET', ''),\n        # Add other auth parameters as needed\n    )\n\n    # Start the agent using aiohttp, defaulting to anonymous if no client_id is set\n    await start_agent_process(\n        agent_app,\n        CloudAdapter(),\n        auth_config if auth_config.CLIENT_ID else None, # Pass auth_config only if credentials are provided\n        middlewares=[jwt_authorization_middleware] if auth_config.CLIENT_ID else [],\n        port=3978 # Default port for agents\n    )\n\nif __name__ == \"__main__\":\n    import asyncio\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Update all import statements from `from microsoft.agents...` to `from microsoft_agents...`.","message":"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).","severity":"breaking","affected_versions":"All versions prior to the change, including initial beta releases. Users migrating from early versions must update."},{"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.","message":"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.","severity":"breaking","affected_versions":"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."},{"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.","message":"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`.","severity":"breaking","affected_versions":"microsoft-agent-framework versions 1.0.0 and later."},{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions where `AgentApplication` is available (0.5.0+)."},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions requiring authentication."}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}