feat: add azure-ai-agentserver-activity package (Activity Protocol) (#47489)

* feat: add azure-ai-agentserver-activity package (Activity Protocol host)

Initial release of the Activity Protocol host package for Azure AI
Foundry hosted agents. Provides Starlette-based HTTP endpoints for
Activity Protocol traffic with M365 Agents SDK integration.

Package (azure-ai-agentserver-activity 1.0.0b1):
- ActivityAgentServerHost with POST /activity/messages
- Custom handler support for full M365 SDK control
- Auto-initialization of M365 SDK from environment variables
- MSAL auth patches for Foundry container MAIB auth (apply_msal_patches)
- Session ID resolution (query param, header, config, UUID fallback)
- Activity/session ID sanitization for header injection defense
- OpenTelemetry distributed tracing and W3C Baggage propagation
- Error-source classification (x-platform-error-source)

Author: Hameedkunkanoor

sdk/agentserver/azure-ai-agentserver-activity/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Release History
+
+## 1.0.0b1 (Unreleased)
+
+### Features Added
+
+- Initial preview release of `azure-ai-agentserver-activity`.
+- `ActivityAgentServerHost` — Starlette-based host for Activity Protocol traffic.
+- `POST /activity/messages` and `POST /api/messages` endpoints with the Foundry platform header contract.
+- Simple Teams agent path: `ActivityAgentServerHost()` builds the M365 Agents SDK stack eagerly during construction and exposes the built `AgentApplication` as the `host.agent_app` property. Register handlers with `@host.agent_app.activity(...)` / `@host.agent_app.error`, and reach the rest of the M365 surface (`message` / `proactive` / `auth`) the same way. The adapter is available via `host.adapter`.
+- Custom handler support: `ActivityAgentServerHost(request_handler=fn)` for full request/response control without the M365 SDK.
+- Pre-built injection: `ActivityAgentServerHost(agent_app=app)`, plus build options on the default constructor (`digital_worker`, `storage`, `connection_manager`, `adapter`, `authorization`, `connection_config`).
+- Container protocol version `2.0.0` support: reads `x-agent-user-id` and `x-agent-foundry-call-id` from inbound requests and binds them to the request-scoped platform context so the per-request call ID is forwarded on outbound Foundry 1P calls (`x-agent-user-id` is not forwarded to 1P). Values are available to handler and tool code via `azure.ai.agentserver.core.get_request_context()`.
+- Module-level `get_hosted_agent_env(*, digital_worker=False)` helper that returns a config mapping (`os.environ` overlaid with the derived `CONNECTIONS__*` settings from the Foundry-native `FOUNDRY_AGENT_*` env vars) **without mutating the process environment**.
+- MSAL auth patches for Foundry container MAIB auth (applied internally for the digital-worker model).
+- Session ID resolution (query param → header → config → UUID fallback).
+- Activity ID and session ID sanitization for header-injection defense.
+- OpenTelemetry distributed tracing and W3C Baggage propagation.
+- Error-source classification (`x-platform-error-source`) on all error responses.
+
+### Other Changes
+
+- Requires `azure-ai-agentserver-core>=2.0.0b7`.
+

sdk/agentserver/azure-ai-agentserver-activity/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sdk/agentserver/azure-ai-agentserver-activity/MANIFEST.in

@@ -0,0 +1,8 @@
+include *.md
+include LICENSE
+recursive-include tests *.py
+recursive-include samples *.py *.md
+include azure/__init__.py
+include azure/ai/__init__.py
+include azure/ai/agentserver/__init__.py
+include azure/ai/agentserver/activity/py.typed

sdk/agentserver/azure-ai-agentserver-activity/README.md

@@ -0,0 +1,164 @@
+# Azure AI Agent Server Activity client library for Python
+
+The `azure-ai-agentserver-activity` package provides the Foundry container integration host for Activity Protocol traffic in Azure AI Hosted Agent containers. It plugs into [`azure-ai-agentserver-core`](https://pypi.org/project/azure-ai-agentserver-core/) and exposes a protocol endpoint with Foundry-required header, tracing, and error behavior.
+
+## Getting started
+
+### Install the package
+
+```bash
+pip install azure-ai-agentserver-activity
+```
+
+### Prerequisites
+
+- Python 3.10 or later
+
+## Key concepts
+
+### ActivityAgentServerHost
+
+`ActivityAgentServerHost` is an `AgentServerHost` subclass for Activity Protocol traffic. It provides:
+
+- `POST /activity/messages` (and the `POST /api/messages` alias) for inbound activities.
+
+### Usage patterns
+
+**Build the M365 stack (default)** — register handlers on the host's `agent_app`:
+
+```python
+from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+host = ActivityAgentServerHost()
+app = host.agent_app
+
+@app.activity("message")
+async def on_message(context, state):
+    await context.send_activity(f"Echo: {context.activity.text}")
+
+@app.error
+async def on_error(context, error):
+    await context.send_activity(f"Error: {error}")
+
+host.run()
+```
+
+**Build the M365 stack, with overrides** — same default path, but override any
+components you want to control (the host builds the rest from the environment):
+
+```python
+from microsoft_agents.hosting.core import MemoryStorage
+from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+# Override just the storage backend; connection manager / adapter / authorization
+# / config are still built for you. Add digital_worker=True for the blueprint model.
+app = ActivityAgentServerHost(storage=MemoryStorage())
+```
+
+**Inject a pre-built `AgentApplication`** — host an M365 `AgentApplication` you built yourself:
+
+```python
+from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+# agent_app: a fully-built microsoft_agents AgentApplication (with an adapter)
+host = ActivityAgentServerHost(agent_app=agent_app)
+host.run()
+```
+
+**Custom handler** — you own the request pipeline (the M365 SDK is not initialized):
+
+```python
+from starlette.responses import Response
+
+from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+async def handle(request):
+    activity = request.state.activity  # parsed dict
+    # Custom processing...
+    return Response(status_code=202)
+
+host = ActivityAgentServerHost(request_handler=handle)
+host.run()
+```
+
+### Request header contract
+
+`POST /activity/messages` consumes:
+
+- `agent_session_id` query parameter (highest-precedence session source), then
+  the `x-agent-session-id` header, then config, then a generated UUID fallback
+- `x-agent-conversation-id`
+- `x-agent-user-id` (per-user identity) and `x-agent-foundry-call-id` (per-request call ID, container protocol `2.0.0`)
+- `traceparent`, `tracestate`, and `baggage`
+
+### Public API
+
+- `ActivityAgentServerHost` — the host class. Constructed directly, it builds the
+  M365 stack and exposes the built `AgentApplication` as the `agent_app` property:
+  register handlers on it (`host.agent_app.activity`/`error`/`message`/`proactive`/`auth`
+  ...). Optional keyword overrides: `digital_worker`, `storage`,
+  `connection_manager`, `adapter`, `authorization`, `connection_config`.
+- `ActivityAgentServerHost(agent_app=agent_app)` — host a pre-built
+  M365 `AgentApplication` (the adapter is taken from `agent_app.adapter`).
+- `ActivityAgentServerHost(request_handler=handler)` — host a custom async
+  request handler; the M365 SDK is not initialized.
+- `get_hosted_agent_env(*, digital_worker=False)` — return a config mapping
+  (`os.environ` overlaid with the derived `CONNECTIONS__*` settings from the
+  Foundry-native `FOUNDRY_AGENT_*` env) **without mutating the environment**. The
+  default constructor derives this for you; call it yourself only when you build
+  the `MsalConnectionManager` (or a pre-built `AgentApplication`) manually — see
+  the `03-self-hosted-app` sample.
+- `ActivityAgentServerHost.agent_app` — the underlying M365 `AgentApplication`
+  (available when the host builds or is given one).
+- `ActivityAgentServerHost.adapter` — the channel adapter for the underlying
+  `AgentApplication`.
+
+## Examples
+
+See the [samples directory](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/agentserver/azure-ai-agentserver-activity/samples) for runnable scenarios, ordered as a learning path:
+
+- `01-echo` — the simplest agent: the host builds the M365 stack and you register handlers directly on it to echo the user's message back.
+- `02-custom-components` — override one or more M365 components (storage, connection manager, adapter, authorization, config) while the host builds the rest.
+- `03-self-hosted-app` — build the M365 `AgentApplication` yourself and host it by passing `agent_app=`.
+- `04-custom-handler` — own the request pipeline with `request_handler=` (the M365 SDK is not initialized).
+- `05-multi-protocol` — compose the Activity and Invocations protocols on a single server.
+
+## Troubleshooting
+
+### `ImportError`: M365 Agents SDK not installed
+
+The M365 Agents SDK ships as a dependency of this package, so a standard
+`pip install azure-ai-agentserver-activity` covers the default
+`ActivityAgentServerHost()` path. If you have deliberately trimmed the M365
+packages from your environment, reinstall them:
+
+```bash
+pip install microsoft-agents-hosting-core microsoft-agents-authentication-msal microsoft-agents-activity azure-identity
+```
+
+Alternatively, use `ActivityAgentServerHost(request_handler=...)`, which does
+not initialize the M365 SDK.
+
+### `TypeError`: handler must be an async function
+
+`request_handler=...` requires an `async def` handler
+(`async def handle(request) -> Response`). A plain `def` is rejected.
+
+### `AttributeError` when accessing `agent_app`
+
+`host.agent_app` (and handler registration via `@host.agent_app.activity(...)` /
+`@host.agent_app.error`) is only available when the host builds or is given an M365
+`AgentApplication` (the default constructor or `agent_app=`). A host
+created with `request_handler=...` does not expose the M365 surface.
+
+## Next steps
+
+- Check the [`azure-ai-agentserver-core`](https://pypi.org/project/azure-ai-agentserver-core/) package for base host functionality
+
+## Contributing
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [https://cla.microsoft.com](https://cla.microsoft.com).
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

sdk/agentserver/azure-ai-agentserver-activity/api.md

@@ -0,0 +1,99 @@
+```py
+namespace azure.ai.agentserver.activity
+
+    def azure.ai.agentserver.activity.get_hosted_agent_env(*, digital_worker: bool = False) -> dict[str, str]: ...
+
+
+    class azure.ai.agentserver.activity.ActivityAgentServerHost(AgentServerHost):
+        property adapter: Optional[HttpAdapterBase]    # Read-only
+        property agent_app: AgentApplication    # Read-only
+        property connection_config: Optional[Mapping[str, str]]    # Read-only
+        property routes: list[BaseRoute]    # Read-only
+
+        async def __call__(
+                self, 
+                scope: Scope, 
+                receive: Receive, 
+                send: Send
+            ) -> None: ...
+
+        def __init__(
+                self, 
+                *, 
+                adapter: Optional[HttpAdapterBase] = ..., 
+                agent_app: Optional[AgentApplication] = ..., 
+                authorization: Optional[Authorization] = ..., 
+                connection_config: Optional[Mapping[str, str]] = ..., 
+                connection_manager: Optional[MsalConnectionManager] = ..., 
+                digital_worker: bool = False, 
+                request_handler: Optional[Callable[[Request], Awaitable[Response]]] = ..., 
+                storage: Optional[Storage] = ..., 
+                **kwargs: Any
+            ) -> None: ...
+
+        def add_exception_handler(
+                self, 
+                exc_class_or_status_code: int | type[Exception], 
+                handler: ExceptionHandler
+            ) -> None: ...
+
+        def add_middleware(
+                self, 
+                middleware_class: _MiddlewareFactory[P], 
+                *args: args, 
+                **kwargs: kwargs
+            ) -> None: ...
+
+        def add_route(
+                self, 
+                path: str, 
+                route: Callable[[Request], Awaitable[Response] | Response], 
+                methods: list[str] | None = None, 
+                name: str | None = None, 
+                include_in_schema: bool = True
+            ) -> None: ...
+
+        def build_middleware_stack(self) -> ASGIApp: ...
+
+        def host(
+                self, 
+                host: str, 
+                app: ASGIApp, 
+                name: str | None = None
+            ) -> None: ...
+
+        def mount(
+                self, 
+                path: str, 
+                app: ASGIApp, 
+                name: str | None = None
+            ) -> None: ...
+
+        def register_server_version(self, version_segment: str) -> None: ...
+
+        def run(
+                self, 
+                host: str = "0.0.0.0", 
+                port: Optional[int] = None
+            ) -> None: ...
+
+        async def run_async(
+                self, 
+                host: str = "0.0.0.0", 
+                port: Optional[int] = None
+            ) -> None: ...
+
+        def shutdown_handler(self, fn: Callable[[], Awaitable[None]]) -> Callable[[], Awaitable[None]]: ...
+
+        @staticmethod
+        async def sse_keepalive_stream(iterator: AsyncIterable[_Content], interval: int) -> AsyncIterator[_Content]: ...
+
+        def url_path_for(
+                self, 
+                name: str, 
+                /, 
+                **path_params: Any
+            ) -> URLPath: ...
+
+
+```

sdk/agentserver/azure-ai-agentserver-activity/api.metadata.yml

@@ -0,0 +1,3 @@
+apiMdSha256: f24092853feea2b3351388b925ce0d4363ef8a6b14249bb48e6c065884c1d5dd
+parserVersion: 0.3.30
+pythonVersion: 3.12.10

sdk/agentserver/azure-ai-agentserver-activity/azure/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

sdk/agentserver/azure-ai-agentserver-activity/azure/ai/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

sdk/agentserver/azure-ai-agentserver-activity/azure/ai/agentserver/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

sdk/agentserver/azure-ai-agentserver-activity/azure/ai/agentserver/activity/__init__.py

@@ -0,0 +1,65 @@
+# ---------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# ---------------------------------------------------------
+"""Activity protocol host for Azure AI Hosted Agents.
+
+This package provides an activity protocol host as a subclass of
+:class:`~azure.ai.agentserver.core.AgentServerHost`.
+
+Default usage — the M365 Agents SDK is initialized during construction and the
+built ``AgentApplication`` is exposed as the ``agent_app`` property (register
+handlers on it and reach the full M365 surface)::
+
+    from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+    host = ActivityAgentServerHost()
+    app = host.agent_app
+
+    @app.activity("message")
+    async def on_message(context, state):
+        await context.send_activity(f"Echo: {context.activity.text}")
+
+    host.run()
+
+The default path also accepts optional overrides — pass any of ``storage`` /
+``connection_manager`` / ``adapter`` / ``authorization`` / ``connection_config``
+(or ``digital_worker=True``) and the host builds the rest from the environment::
+
+    from microsoft_agents.hosting.core import MemoryStorage
+
+    # Override just the storage backend; the host builds the rest.
+    host = ActivityAgentServerHost(storage=MemoryStorage())
+    app = host.agent_app
+
+Injected ``AgentApplication`` usage — host a pre-built M365 ``AgentApplication``
+you constructed yourself (the adapter is taken from ``agent_app.adapter``)::
+
+    from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+    # agent_app: a fully-built microsoft_agents AgentApplication (with an adapter)
+    host = ActivityAgentServerHost(agent_app=agent_app)
+    host.run()
+
+Custom handler usage — the M365 SDK is not initialized; you own the pipeline::
+
+    from starlette.responses import Response
+
+    from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+    async def handle(request):
+        activity = request.state.activity
+        # Custom processing...
+        return Response(status_code=202)
+
+    host = ActivityAgentServerHost(request_handler=handle)
+    host.run()
+"""
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+
+from ._activity import ActivityAgentServerHost
+from ._config import get_hosted_agent_env
+from ._version import VERSION
+
+__all__ = ["ActivityAgentServerHost", "get_hosted_agent_env"]
+__version__ = VERSION