Merge remote-tracking branch 'origin/main' into pmohapatra-MCP-V1-V2-python

Author: biswapm

.github/workflows/ci.yml

@@ -107,15 +107,13 @@ jobs:
       run: uv lock && uv sync --locked --all-extras --dev
 
     - name: Verify centralized version constraints
-      run: python scripts/verify_constraints.py
+      run: uv run --frozen tox -e verify-constraints
 
     - name: Check linting
-      run: |
-        uv run --frozen ruff check . --preview
+      run: uv run --frozen tox -e lint
 
     - name: Check formatting
-      run: |
-        uv run --frozen ruff format --check .
+      run: uv run --frozen tox -e format
 
     - name: Build package
       run: |
@@ -124,14 +122,12 @@ jobs:
         AGENT365_PYTHON_SDK_PACKAGE_VERSION: ${{ needs.version-number.outputs.PACKAGE_VERSION }}
 
     - name: Run unit tests
-      run: |
-        uv run --frozen pytest tests/ -v --tb=short -m "not integration"
+      run: uv run --frozen tox -e py3${{ matrix.python-version == '3.11' && '11' || '12' }}
 
     - name: Run integration tests
       # Only run integration tests if secrets are available
       if: ${{ vars.RUN_INTEGRATION_TESTS == 'true' }}
-      run: |
-        uv run --frozen pytest -m integration -v --tb=short
+      run: uv run --frozen tox -e integration
       env:
         AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
         AZURE_OPENAI_ENDPOINT: ${{ vars.AZURE_OPENAI_ENDPOINT }}

.gitignore

@@ -72,6 +72,7 @@ dist/
 build/
 .eggs/
 .pytest_cache/
+.tox/
 _version.py
 
 # Test coverage and reports

CLAUDE.md

@@ -61,6 +61,31 @@ pytest tests/ --cov=libraries --cov-report=html -v
 - `unit`: Fast, mocked tests (default)
 - `integration`: Slow tests requiring real services/API keys
 
+### Running with tox
+
+```bash
+# Run all default environments (lint, format, unit tests on 3.11 + 3.12)
+uv run tox
+
+# Run a specific environment
+uv run tox -e lint
+uv run tox -e format
+uv run tox -e py311
+uv run tox -e py312
+
+# Run integration tests (requires env vars)
+uv run tox -e integration
+
+# Verify centralized dependency constraints
+uv run tox -e verify-constraints
+
+# Pass extra args to pytest
+uv run tox -e py311 -- -k "environment"
+
+# List all available environments
+uv run tox list
+```
+
 ### Linting and Formatting
 
 ```bash
@@ -241,7 +266,8 @@ Place it before imports with one blank line after.
 The `.github/workflows/ci.yml` pipeline:
 - Runs on pushes to `main` and `release/*` branches
 - Tests both Python 3.11 and 3.12
-- Executes: lint check → format check → build → unit tests → integration tests (if secrets available)
+- Uses **tox** (via `uv run --frozen tox -e <env>`) to run lint, format, test, and constraint verification steps
+- Executes: verify-constraints → lint → format → build → unit tests → integration tests (if secrets available)
 - Only publishes packages on `release/*` branches when SDK changes detected
 - Uses git-based versioning (tags on release branches = official versions, others = dev versions)
 

libraries/microsoft-agents-a365-notifications/pyproject.toml

@@ -1,6 +1,7 @@
 [build-system]
-requires = ["setuptools>=68", "wheel", "tzdata"]
-build-backend = "setuptools.build_meta"
+requires = ["setuptools>=68", "wheel", "tzdata", "tomlkit", "packaging"]
+build-backend = "build_backend"
+backend-path = ["../../versioning/helper"]
 
 [project]
 name = "microsoft-agents-a365-notifications"

libraries/microsoft-agents-a365-observability-core/CHANGELOG.md

@@ -2,7 +2,45 @@
 
 All notable changes to this package will be documented in this file.
 
-## [Unreleased]
+## [0.3.0]
+
+### Breaking Changes
+
+- **New permission required: `Agent365.Observability.OtelWrite`** — The observability exporter now requires this scope as both a delegated and application permission on your agent blueprint. See [Upgrade Instructions](#upgrade-instructions-observability-permission-for-existing-agents) below.
+
+---
+
+### Upgrade Instructions: Observability Permission for Existing Agents
+
+Existing agent blueprints need `Agent365.Observability.OtelWrite` granted as both a **delegated permission** and an **application permission**. Choose either option below.
+
+#### Option A — Agent 365 CLI (requires both config files)
+
+Requires `a365.config.json` and `a365.generated.config.json` in your config directory, a Global Administrator account, and [Agent 365 CLI v1.1.139-preview](https://www.nuget.org/packages/Microsoft.Agents.A365.DevTools.Cli/1.1.139-preview) or later.
+
+```
+a365 setup admin --config-dir "<path-to-config-dir>"
+```
+
+This grants all missing permissions including the new Observability scopes.
+
+#### Option B — Entra Portal (no config files required)
+
+Requires Global Administrator access to the blueprint app registration.
+
+1. Go to **Entra portal** > **App registrations** > select your Blueprint app
+2. Go to **API permissions** > **Add a permission** > **APIs my organization uses** > search for `9b975845-388f-4429-889e-eab1ef63949c`
+3. Select **Delegated permissions** > check `Agent365.Observability.OtelWrite` > **Add permissions**
+4. Repeat step 2–3, this time select **Application permissions** > check `Agent365.Observability.OtelWrite` > **Add permissions**
+5. Click **Grant admin consent** and confirm
+
+Both `Agent365.Observability.OtelWrite` (Delegated) and `Agent365.Observability.OtelWrite` (Application) should show **Granted** status.
+
+> **Note:** If your agent is autonomous, you only need the **Application permission**. The delegated permission is required for agents that authenticate via a user session.
+
+---
+
+## [0.2.1.dev46]
 
 ### Breaking Changes
 

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/__init__.py

@@ -19,13 +19,37 @@
     unregister_span_enricher,
 )
 from .exporters.spectra_exporter_options import SpectraExporterOptions
-from .inference_call_details import InferenceCallDetails, ServiceEndpoint
+from .inference_call_details import InferenceCallDetails
+from .models.service_endpoint import ServiceEndpoint
 from .inference_operation_type import InferenceOperationType
 from .inference_scope import InferenceScope
 from .invoke_agent_details import InvokeAgentScopeDetails
 from .invoke_agent_scope import InvokeAgentScope
 from .middleware.baggage_builder import BaggageBuilder
 from .models.caller_details import CallerDetails
+from .models.messages import (
+    BlobPart,
+    ChatMessage,
+    FilePart,
+    FinishReason,
+    GenericPart,
+    InputMessages,
+    InputMessagesParam,
+    MessagePart,
+    MessageRole,
+    Modality,
+    OutputMessage,
+    OutputMessages,
+    OutputMessagesParam,
+    ReasoningPart,
+    ServerToolCallPart,
+    ServerToolCallResponsePart,
+    TextPart,
+    ToolCallRequestPart,
+    ToolCallResponsePart,
+    UriPart,
+)
+from .models.response import Response
 from .models.user_details import UserDetails
 from .opentelemetry_scope import OpenTelemetryScope
 from .request import Request
@@ -70,12 +94,34 @@
     "ToolCallDetails",
     "Channel",
     "Request",
+    "Response",
     "SpanDetails",
     "InferenceCallDetails",
     "ServiceEndpoint",
     # Enums
     "InferenceOperationType",
     "ToolType",
+    # OTEL gen-ai message format types
+    "MessageRole",
+    "FinishReason",
+    "Modality",
+    "TextPart",
+    "ToolCallRequestPart",
+    "ToolCallResponsePart",
+    "ReasoningPart",
+    "BlobPart",
+    "FilePart",
+    "UriPart",
+    "ServerToolCallPart",
+    "ServerToolCallResponsePart",
+    "GenericPart",
+    "MessagePart",
+    "ChatMessage",
+    "OutputMessage",
+    "InputMessages",
+    "OutputMessages",
+    "InputMessagesParam",
+    "OutputMessagesParam",
     # Utility functions
     "extract_context_from_headers",
     "get_traceparent",

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/agent_details.py

@@ -38,3 +38,6 @@ class AgentDetails:
 
     provider_name: Optional[str] = None
     """The provider name (e.g., openai, anthropic)."""
+
+    agent_version: Optional[str] = None
+    """Optional version of the agent (e.g., "1.0.0", "2025-05-01")."""

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/constants.py

@@ -38,6 +38,7 @@
 GEN_AI_AGENT_ID_KEY = "gen_ai.agent.id"
 GEN_AI_AGENT_NAME_KEY = "gen_ai.agent.name"
 GEN_AI_AGENT_DESCRIPTION_KEY = "gen_ai.agent.description"
+GEN_AI_AGENT_VERSION_KEY = "gen_ai.agent.version"
 GEN_AI_AGENT_PLATFORM_ID_KEY = "microsoft.a365.agent.platform.id"
 GEN_AI_AGENT_THOUGHT_PROCESS_KEY = "microsoft.a365.agent.thought.process"
 GEN_AI_CONVERSATION_ID_KEY = "gen_ai.conversation.id"
@@ -73,6 +74,7 @@
 GEN_AI_CALLER_AGENT_ID_KEY = "microsoft.a365.caller.agent.id"
 GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY = "microsoft.a365.caller.agent.blueprint.id"
 GEN_AI_CALLER_AGENT_PLATFORM_ID_KEY = "microsoft.a365.caller.agent.platform.id"
+GEN_AI_CALLER_AGENT_VERSION_KEY = "microsoft.a365.caller.agent.version"
 
 # Agent-specific dimensions
 AGENT_ID_KEY = "gen_ai.agent.id"

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/execute_tool_scope.py

@@ -12,6 +12,7 @@
     GEN_AI_CONVERSATION_ID_KEY,
     GEN_AI_TOOL_ARGS_KEY,
     GEN_AI_TOOL_CALL_ID_KEY,
+    GEN_AI_TOOL_CALL_RESULT_KEY,
     GEN_AI_TOOL_DESCRIPTION_KEY,
     GEN_AI_TOOL_NAME_KEY,
     GEN_AI_TOOL_TYPE_KEY,
@@ -21,12 +22,12 @@
     USER_ID_KEY,
     USER_NAME_KEY,
 )
+from .utils import safe_json_dumps, validate_and_normalize_ip
 from .models.user_details import UserDetails
 from .opentelemetry_scope import OpenTelemetryScope
 from .request import Request
 from .span_details import SpanDetails
 from .tool_call_details import ToolCallDetails
-from .utils import validate_and_normalize_ip
 
 
 class ExecuteToolScope(OpenTelemetryScope):
@@ -77,25 +78,26 @@ def __init__(
             user_details: Optional human user details
             span_details: Optional span configuration (parent context, timing, kind)
         """
-        kind = SpanKind.INTERNAL
-        parent_context = None
-        start_time = None
-        end_time = None
-        if span_details is not None:
-            if span_details.span_kind is not None:
-                kind = span_details.span_kind
-            parent_context = span_details.parent_context
-            start_time = span_details.start_time
-            end_time = span_details.end_time
+        # spanKind defaults to INTERNAL; allow override via span_details
+        resolved_span_details = (
+            SpanDetails(
+                span_kind=span_details.span_kind
+                if span_details and span_details.span_kind
+                else SpanKind.INTERNAL,
+                parent_context=span_details.parent_context if span_details else None,
+                start_time=span_details.start_time if span_details else None,
+                end_time=span_details.end_time if span_details else None,
+                span_links=span_details.span_links if span_details else None,
+            )
+            if span_details
+            else SpanDetails(span_kind=SpanKind.INTERNAL)
+        )
 
         super().__init__(
-            kind=kind,
             operation_name=EXECUTE_TOOL_OPERATION_NAME,
             activity_name=f"{EXECUTE_TOOL_OPERATION_NAME} {details.tool_name}",
             agent_details=agent_details,
-            parent_context=parent_context,
-            start_time=start_time,
-            end_time=end_time,
+            span_details=resolved_span_details,
         )
 
         # Extract details
@@ -107,7 +109,9 @@ def __init__(
         endpoint = details.endpoint
 
         self.set_tag_maybe(GEN_AI_TOOL_NAME_KEY, tool_name)
-        self.set_tag_maybe(GEN_AI_TOOL_ARGS_KEY, arguments)
+        if arguments is not None:
+            serialized = safe_json_dumps(arguments) if isinstance(arguments, dict) else arguments
+            self.set_tag_maybe(GEN_AI_TOOL_ARGS_KEY, serialized)
         self.set_tag_maybe(GEN_AI_TOOL_TYPE_KEY, tool_type)
         self.set_tag_maybe(GEN_AI_TOOL_CALL_ID_KEY, tool_call_id)
         self.set_tag_maybe(GEN_AI_TOOL_DESCRIPTION_KEY, description)
@@ -133,13 +137,15 @@ def __init__(
                 validate_and_normalize_ip(user_details.user_client_ip),
             )
 
-    def record_response(self, response: str) -> None:
-        """Records response information for telemetry tracking.
+    def record_response(self, result: dict[str, object] | str) -> None:
+        """Record the tool call result for telemetry tracking.
 
-        Note: This method is intentionally a no-op as GEN_AI_EVENT_CONTENT was removed.
-        The method is kept for interface compatibility.
+        Per OTEL spec, the result is expected to be an object. If a string
+        is provided, it is recorded as-is (JSON string fallback). If a dict
+        is provided, it is serialized to JSON.
 
         Args:
-            response: The response to record
+            result: Tool call result as a structured dict or JSON string
         """
-        pass
+        serialized = safe_json_dumps(result) if isinstance(result, dict) else result
+        self.set_tag_maybe(GEN_AI_TOOL_CALL_RESULT_KEY, serialized)