Merge branch 'main' into copilot/fix-docstring-formatting

Author: JimDaly

.github/workflows/ci.yml

@@ -85,6 +85,8 @@ jobs:
     defaults:
       run:
         working-directory: ./
+    env:
+      PYTHONPATH: ${{ github.workspace }}/versioning/helper
 
     strategy:
       matrix:
@@ -107,15 +109,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 +124,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
@@ -194,6 +219,18 @@ Place it before imports with one blank line after.
 - **Never** use the keyword "Kairo" in code - it's a legacy reference that must be removed/replaced
 - If found during code review, flag for removal
 
+### Observability Export Configuration — Coordinated Review Required
+
+The following three constants must stay in sync. If a PR changes **any one** of them, the reviewer (human or Copilot) **must** ask the author to confirm the other two are still correct:
+
+| Constant | Location |
+|---|---|
+| `PROD_OBSERVABILITY_SCOPE` | `libraries/microsoft-agents-a365-runtime/microsoft_agents_a365/runtime/environment_utils.py` |
+| `DEFAULT_ENDPOINT_URL` | `libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/exporters/agent365_exporter.py` |
+| Export URL path pattern | `build_export_url()` in `libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/exporters/utils.py` |
+
+Snapshot tests in `tests/observability/core/test_export_config_consistency.py` will fail if any value drifts, but the developer must also verify the values are correct for the target environment — the tests only catch accidental drift, not intentional-but-incomplete updates.
+
 ### Python Conventions
 
 - Type hints required on all function parameters and return types
@@ -241,7 +278,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,6 @@
 [build-system]
-requires = ["setuptools>=68", "wheel", "tzdata"]
-build-backend = "setuptools.build_meta"
+requires = ["setuptools>=68", "wheel", "tzdata", "tomlkit", "packaging"]
+build-backend = "build_backend"
 
 [project]
 name = "microsoft-agents-a365-notifications"

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

@@ -0,0 +1,68 @@
+# Changelog — microsoft-agents-a365-observability-core
+
+All notable changes to this package will be documented in this file.
+
+## [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
+
+- **`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`.