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

eng/ignore-links.txt

@@ -6,3 +6,6 @@ http://localhost:8000/samples/pyodide_integration
 https://pypi.org/project/azure-mynewpackage/
 https://aka.ms/azsdk/python/migrate/my-new-package
 https://github.com/Azure/azure-sdk-for-python/compare/main..
+https://aka.ms/azsdk/foundry/hosted-agents
+https://aka.ms/azsdk/foundry/activity-protocol
+https://aka.ms/azsdk/foundry/quickstarts

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,117 @@
+# 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)
+
+## 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:
+
+- `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
+
+## Troubleshooting
+
+### 403 Forbidden from Teams Developer Portal
+
+When configuring blueprint backend, ensure you have the correct Azure authentication scope:
+
+```bash
+az login --scope https://dev.teams.microsoft.com/.default
+```
+
+If using `configure-blueprint-backend.ps1`, load environment variables from your `.azure` directory before running the script.
+
+### Missing environment variables
+
+Ensure all required azd environment variables are set before running scripts:
+
+```bash
+azd env get-values
+```
+
+## Next steps
+
+- Review the [Azure AI Hosted Agent documentation](https://aka.ms/azsdk/foundry/hosted-agents)
+- Explore the [Activity Protocol specification](https://aka.ms/azsdk/foundry/activity-protocol)
+- Check the [`azure-ai-agentserver-core`](https://pypi.org/project/azure-ai-agentserver-core/) package for base host functionality
+- Learn about deployment patterns in [Foundry quickstarts](https://aka.ms/azsdk/foundry/quickstarts)
+
+## 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/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