Merge branch 'main' into users/akjind/addUserMessageToHeader

Author: gwharris7

.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)
 

docs/design.md

@@ -81,21 +81,23 @@ The foundation for distributed tracing in agent applications. Built on OpenTelem
 
 | Class | Purpose |
 |-------|---------|
-| `InvokeAgentDetails` | Agent endpoint, session ID, and invocation metadata |
+| `InvokeAgentScopeDetails` | Agent endpoint and invocation metadata |
 | `AgentDetails` | Agent identification and metadata |
-| `TenantDetails` | Tenant identification for multi-tenant scenarios |
+| `UserDetails` | Human caller identification (user ID, email, name, IP) |
+| `CallerDetails` | Wrapper for user details and/or caller agent details |
+| `SpanDetails` | Parent context, timing, and span kind for custom spans |
 | `InferenceCallDetails` | Model name, tokens, provider information |
 | `ToolCallDetails` | Tool name, arguments, endpoint |
-| `Request` | Execution context and correlation ID |
+| `Request` | Content, correlation ID, and conversation ID |
 
 **Usage Example:**
 
 ```python
 from microsoft_agents_a365.observability.core import (
     configure,
     InvokeAgentScope,
-    InvokeAgentDetails,
-    TenantDetails,
+    InvokeAgentScopeDetails,
+    AgentDetails,
     Request,
     BaggageBuilder,
 )
@@ -112,9 +114,9 @@ configure(
 with BaggageBuilder().tenant_id(tenant_id).agent_id(agent_id).build():
     # Trace agent invocation
     with InvokeAgentScope.start(
-        invoke_agent_details=InvokeAgentDetails(...),
-        tenant_details=TenantDetails(...),
-        request=Request(...)
+        request=Request(content="Hello"),
+        invoke_scope_details=InvokeAgentScopeDetails(...),
+        agent_details=AgentDetails(...),
     ) as scope:
         # Agent logic here
         scope.record_response("result")

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

@@ -0,0 +1,30 @@
+# Changelog — microsoft-agents-a365-observability-core
+
+All notable changes to this package will be documented in this file.
+
+## [Unreleased]
+
+### Breaking Changes
+
+- **`InvokeAgentDetails` renamed to `InvokeAgentScopeDetails`** — Now contains only scope-level config (`endpoint`). Agent identity (`AgentDetails`) is a separate parameter. `session_id` moved to `Request`.
+- **`InvokeAgentScope.start()`**: New signature `start(request, invoke_scope_details, agent_details, caller_details?, span_details?)`. `request` is required.
+- **`InferenceScope.start()`**: New signature `start(request, details, agent_details, user_details?, span_details?)`. `request` is required.
+- **`ExecuteToolScope.start()`**: New signature `start(request, details, agent_details, user_details?, span_details?)`. Same pattern as `InferenceScope`.
+- **`OutputScope.start()`**: New signature `start(request, response, agent_details, user_details?, span_details?)`. Same pattern.
+- **`CallerDetails` renamed to `UserDetails`** — Fields renamed: `caller_id` → `user_id`, `caller_upn` → `user_email`, `caller_name` → `user_name`, `caller_client_ip` → `user_client_ip`.
+- **`CallerDetails` is now a composite wrapper** — Groups `user_details: UserDetails` and `caller_agent_details: AgentDetails` for A2A scenarios.
+- **`TenantDetails` removed** — `tenant_id` is now on `AgentDetails.tenant_id`. Removed from all scope `start()` methods.
+- **`ExecutionType` enum removed** — Removed from `Request`. `GEN_AI_EXECUTION_TYPE_KEY` constant also removed.
+- **`AgentDetails` fields renamed** — `agent_auid` → `agentic_user_id`, `agent_upn` → `agentic_user_email`. `conversation_id` moved to `Request`.
+- **`Request` model updated** — Removed `execution_type`. Added `conversation_id`. `content` is now optional.
+- **`BaggageBuilder` methods renamed** — `agent_upn()` → `agentic_user_email()`, `agent_auid()` → `agentic_user_id()`, `caller_id()` → `user_id()`, `caller_name()` → `user_name()`, `caller_upn()` → `user_email()`, `caller_client_ip()` → `user_client_ip()`.
+
+### Added
+
+- **`SpanDetails`** — Groups `span_kind`, `parent_context`, `start_time`, `end_time` for scope construction.
+- **`UserDetails`** — Human caller identity with `user_id`, `user_email`, `user_name`, `user_client_ip`.
+- **`CallerDetails`** (new wrapper) — Groups `user_details` and `caller_agent_details` for A2A scenarios.
+- **`InvokeAgentScopeDetails`** — Scope-level config with `endpoint` only.
+- **`Request.conversation_id`** — Conversation ID field on the unified `Request` model.
+- **`ERROR_TYPE_CANCELLED`** constant — `"TaskCanceledException"`, used by `record_cancellation()`.
+- **`OutputScope`** now exported from `microsoft_agents_a365.observability.core`.

libraries/microsoft-agents-a365-observability-core/docs/design.md

@@ -65,10 +65,10 @@ configure(
 class OpenTelemetryScope:
     """Base class for OpenTelemetry tracing scopes."""
 
-    def __init__(self, kind, operation_name, activity_name, agent_details, tenant_details):
+    def __init__(self, kind, operation_name, activity_name, agent_details):
         # Creates span with given parameters
         # Sets common attributes (gen_ai.system, operation name)
-        # Sets agent/tenant details as span attributes
+        # Sets agent details as span attributes
 
     def __enter__(self):
         # Makes span active in current context
@@ -96,29 +96,23 @@ Traces agent invocation operations (entry point for agent requests):
 ```python
 from microsoft_agents_a365.observability.core import (
     InvokeAgentScope,
-    InvokeAgentDetails,
-    TenantDetails,
+    InvokeAgentScopeDetails,
     AgentDetails,
+    Request,
 )
 
 with InvokeAgentScope.start(
-    invoke_agent_details=InvokeAgentDetails(
-        endpoint=parsed_url,
-        session_id="session-123",
-        details=AgentDetails(agent_id="agent-456", agent_name="MyAgent")
-    ),
-    tenant_details=TenantDetails(tenant_id="tenant-789"),
-    request=Request(content="Hello", execution_type=ExecutionType.CHAT),
+    request=Request(content="Hello"),
+    invoke_scope_details=InvokeAgentScopeDetails(endpoint=parsed_url),
+    agent_details=AgentDetails(agent_id="agent-456", agent_name="MyAgent"),
 ) as scope:
     # Agent processing
     scope.record_response("Agent response")
 ```
 
 **Span attributes recorded:**
 - Server address and port
-- Session ID
 - Execution source metadata
-- Execution type
 - Input/output messages
 - Caller details (if provided)
 
@@ -127,15 +121,15 @@ with InvokeAgentScope.start(
 Traces LLM/AI model inference calls:
 
 ```python
-from microsoft_agents_a365.observability.core import InferenceScope, InferenceCallDetails
+from microsoft_agents_a365.observability.core import InferenceScope, InferenceCallDetails, Request
 
 with InferenceScope.start(
-    inference_call_details=InferenceCallDetails(
+    request=Request(content="Hello"),
+    details=InferenceCallDetails(
         model_name="gpt-4",
         provider="openai"
     ),
     agent_details=agent_details,
-    tenant_details=tenant_details,
 ) as scope:
     # LLM call
     scope.record_input_tokens(100)
@@ -148,15 +142,15 @@ with InferenceScope.start(
 Traces tool execution operations:
 
 ```python
-from microsoft_agents_a365.observability.core import ExecuteToolScope, ToolCallDetails
+from microsoft_agents_a365.observability.core import ExecuteToolScope, ToolCallDetails, Request
 
 with ExecuteToolScope.start(
-    tool_call_details=ToolCallDetails(
+    request=Request(content="search for weather"),
+    details=ToolCallDetails(
         tool_name="search",
         tool_arguments={"query": "weather"}
     ),
     agent_details=agent_details,
-    tenant_details=tenant_details,
 ) as scope:
     # Tool execution
     scope.record_response("Tool result")
@@ -174,7 +168,7 @@ with BaggageBuilder() \
     .tenant_id("tenant-123") \
     .agent_id("agent-456") \
     .correlation_id("corr-789") \
-    .caller_id("user-abc") \
+    .user_id("user-abc") \
     .session_id("session-xyz") \
     .build():
     # All child spans inherit this baggage
@@ -195,9 +189,11 @@ with BaggageBuilder.set_request_context(
 | `tenant_id(value)` | `tenant_id` |
 | `agent_id(value)` | `gen_ai.agent.id` |
 | `agent_auid(value)` | `gen_ai.agent.auid` |
-| `agent_upn(value)` | `gen_ai.agent.upn` |
+| `agent_email(value)` | `gen_ai.agent.upn` |
 | `correlation_id(value)` | `correlation_id` |
-| `caller_id(value)` | `gen_ai.caller.id` |
+| `user_id(value)` | `gen_ai.caller.id` |
+| `user_name(value)` | `gen_ai.caller.name` |
+| `user_email(value)` | `gen_ai.caller.upn` |
 | `session_id(value)` | `session_id` |
 | `conversation_id(value)` | `gen_ai.conversation.id` |
 | `channel_name(value)` | `gen_ai.execution.source.name` |
@@ -246,14 +242,12 @@ options = Agent365ExporterOptions(
 
 ## Data Classes
 
-### InvokeAgentDetails
+### InvokeAgentScopeDetails
 
 ```python
 @dataclass
-class InvokeAgentDetails:
+class InvokeAgentScopeDetails:
     endpoint: ParseResult | None  # Parsed URL of the agent endpoint
-    session_id: str | None        # Session identifier
-    details: AgentDetails         # Agent metadata
 ```
 
 ### AgentDetails
@@ -265,20 +259,42 @@ class AgentDetails:
     agent_name: str | None
     agent_description: str | None
     agent_auid: str | None        # Agent unique identifier
-    agent_upn: str | None         # User principal name
+    agent_email: str | None       # Agent email address
     agent_blueprint_id: str | None
     agent_type: AgentType | None
     tenant_id: str | None
-    conversation_id: str | None
     icon_uri: str | None
 ```
 
-### TenantDetails
+### UserDetails
 
 ```python
 @dataclass
-class TenantDetails:
-    tenant_id: str | None
+class UserDetails:
+    user_id: str | None
+    user_email: str | None
+    user_name: str | None
+    caller_client_ip: str | None
+```
+
+### CallerDetails
+
+```python
+@dataclass
+class CallerDetails:
+    user_details: UserDetails | None
+    caller_agent_details: AgentDetails | None
+```
+
+### SpanDetails
+
+```python
+@dataclass
+class SpanDetails:
+    parent_context: Context | None
+    start_time: int | None
+    end_time: int | None
+    span_kind: SpanKind | None
 ```
 
 ### InferenceCallDetails
@@ -358,14 +374,15 @@ microsoft_agents_a365/observability/core/
 ├── invoke_agent_scope.py          # Agent invocation tracing
 ├── inference_scope.py             # LLM inference tracing
 ├── execute_tool_scope.py          # Tool execution tracing
+├── output_scope.py                # Output tracing
 ├── agent_details.py               # AgentDetails dataclass
-├── tenant_details.py              # TenantDetails dataclass
-├── invoke_agent_details.py        # InvokeAgentDetails dataclass
+├── invoke_agent_scope_details.py   # InvokeAgentScopeDetails dataclass
+├── user_details.py                # UserDetails dataclass
+├── span_details.py                # SpanDetails dataclass
 ├── inference_call_details.py      # InferenceCallDetails dataclass
 ├── tool_call_details.py           # ToolCallDetails dataclass
 ├── request.py                     # Request dataclass
 ├── source_metadata.py             # SourceMetadata dataclass
-├── execution_type.py              # ExecutionType enum
 ├── inference_operation_type.py    # InferenceOperationType enum
 ├── tool_type.py                   # ToolType enum
 ├── constants.py                   # Attribute key constants