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

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

@@ -0,0 +1,17 @@
+# Release History
+
+## 1.0.0b1 (2026-06-09)
+
+### 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 Foundry platform header contract.
+- Decorator API: `@app.activity(type)` and `@app.error` for zero-config handler registration.
+- Custom handler support: `ActivityAgentServerHost(handler=fn)` for full M365 SDK control.
+- Auto-initialization of M365 Agents SDK from environment variables (decorator mode).
+- MSAL auth patches for Foundry container MAIB auth (`apply_msal_patches()`).
+- 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.

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,82 @@
+# 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` for inbound activities.
+
+### Usage patterns
+
+**Decorator-based (recommended)** — zero SDK wiring:
+
+```python
+from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+app = ActivityAgentServerHost()
+
+@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}")
+
+app.run()
+```
+
+**Custom handler** — full control over the M365 SDK pipeline:
+
+```python
+from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+async def handle(request):
+    activity = request.state.activity  # parsed dict
+    # Custom processing...
+    return Response(status_code=202)
+
+app = ActivityAgentServerHost(handler=handle)
+app.run()
+```
+
+### Request header contract
+
+`POST /activity/messages` consumes:
+
+- `x-agent-session-id` (preferred session source)
+- `x-agent-conversation-id`
+- `x-agent-user-isolation-key` and `x-agent-chat-isolation-key`
+- `traceparent`, `tracestate`, and `baggage`
+
+### Public API
+
+- `ActivityAgentServerHost` — the host class
+- `apply_msal_patches()` — patches M365 SDK MSAL auth for Foundry containers (UserManagedIdentity with fmi_path)
+
+## Samples
+
+See [samples/README.md](samples/README.md) for runnable scenarios:
+
+- `simple_activity_agent` — echo bot with welcome, invoke, installation events
+- `streaming_activity_agent` — Azure OpenAI streaming via `context.streaming_response`
+- `cards_activity_agent` — Adaptive Cards, Hero, Thumbnail, Receipt cards
+- `auto_signin_activity_agent` — OAuth auto sign-in with Graph and GitHub
+- `semantic_kernel_activity_agent` — Semantic Kernel agent with tools and multi-turn
+- `suggested_actions_activity_agent` — quick-reply buttons

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,40 @@
+# ---------------------------------------------------------
+# 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`.
+
+Decorator-based usage (recommended)::
+
+    from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+    app = ActivityAgentServerHost()
+
+    @app.activity("message")
+    async def on_message(context, state):
+        await context.send_activity(f"Echo: {context.activity.text}")
+
+    app.run()
+
+Custom handler usage::
+
+    from azure.ai.agentserver.activity import ActivityAgentServerHost
+
+    async def handle(request):
+        activity = request.state.activity
+        # Custom processing...
+        return Response(status_code=202)
+
+    app = ActivityAgentServerHost(handler=handle)
+    app.run()
+"""
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+
+from ._activity import ActivityAgentServerHost
+from ._m365_bridge import _apply_msal_patches as apply_msal_patches
+from ._version import VERSION
+
+__all__ = ["ActivityAgentServerHost", "apply_msal_patches"]
+__version__ = VERSION