Merge branch 'main' into danfiedler/pin-actions

Author: rbrighenti

docs/integrating-with-existing-opentelemetry.md

@@ -93,10 +93,15 @@ The SDK produces three core span kinds. Your backend should show them in this ty
 | `gen_ai.operation.name` | Produced by                                       | Typical parent | Span name (default) | Notes |
 |-------------------------|---------------------------------------------------|----------------|---------------------|-------|
 | `invoke_agent`          | `InvokeAgentScope` (one per user turn)            | (root or app)  | `invoke_agent <agent_name>` when set, else `invoke_agent` | |
-| (varies — see notes) | `InferenceScope` (one per LLM call) | `invoke_agent` | `<operation> <model>` | **Manual instrumentation** uses `InferenceOperationType.value` (currently `Chat` / `TextCompletion` / `GenerateContent`, capitalized). **Auto-instrumentation** (e.g. `OpenAIAgentsTraceInstrumentor`) uses lowercase per the [OTel GenAI semconv](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/) (e.g. `chat`). The two are inconsistent today. |
+| `chat` / `text_completion` / `generate_content` | `InferenceScope` (one per LLM call) | `invoke_agent` | `<operation> <model>` | Manual inference scopes use canonical lowercase [OTel GenAI operation names](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/), matching auto-instrumentation for the corresponding operation. |
 | `execute_tool`          | `ExecuteToolScope` (one per tool invocation)      | `invoke_agent` | `execute_tool <tool_name>` (always includes the tool name) | Records tool name, args, and result. |
 
-Filter your backend by the `gen_ai.operation.name` attribute or by span name. Note that `inference` is *not* the literal attribute value — manual instrumentation produces `Chat` / `TextCompletion` / `GenerateContent` (the `InferenceOperationType.value`), while auto-instrumentation extension packages produce the lowercase OTel-spec form (e.g. `chat`). This casing discrepancy is tracked as an SDK issue.
+Filter your backend by the `gen_ai.operation.name` attribute or by span name.
+`InferenceScope` emits `chat`, `text_completion`, or `generate_content` according
+to the selected `InferenceOperationType`, with span names such as `chat gpt-4`.
+`inference` is not a literal operation value. When upgrading, update case-sensitive
+filters that matched the previous `Chat`, `TextCompletion`, or `GenerateContent`
+values and span-name prefixes, or compare case-insensitively.
 
 ## Verifying the integration
 
@@ -110,7 +115,11 @@ from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExport
 trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
 ```
 
-Run a single turn. If you see `invoke_agent` / `Chat` (or `chat`) / `execute_tool` JSON dumps on stdout, the SDK is producing spans correctly — the issue is in your backend exporter (network, auth, sampling). If you don't see them, the integration itself is wrong; check the pitfalls below.
+Run a single turn. If you see `invoke_agent`, the inference operation
+(`chat`, `text_completion`, or `generate_content`), and any invoked `execute_tool`
+spans as JSON dumps on stdout, the SDK is producing spans correctly - investigate
+your backend exporter (network, auth, sampling). If expected spans are missing
+from stdout too, check the integration pitfalls below.
 
 ## Common pitfalls
 

libraries/microsoft-agents-a365-notifications/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog — microsoft-agents-a365-notifications
+
+All notable changes to this package will be documented in this file.
+
+## [2.0.0] - 2026-10-20
+
+### Breaking Changes
+
+- **`AgentLifecycleEvent.USERDELETED` value changed** — it is now
+  `"agenticuserdeleted"` (previously `"agenticuseridentitydeleted"`), so
+  `on_user_deleted()` handlers match the new event name. Update any code that
+  compares against the raw string value.
+
+### Added
+
+- New lifecycle events and handler decorators on `AgentNotification`:
+  - `USERUNDELETED` — `on_user_undeleted()`
+  - `USERUPDATED` — `on_user_updated()`
+  - `USERMANAGERUPDATED` — `on_user_manager_updated()`
+  - `USERENABLED` — `on_user_enabled()`
+  - `USERDISABLED` — `on_user_disabled()`
+
+### Security
+
+- Raised the minimum `PyJWT` version to `>= 2.14.0`.

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

@@ -2,7 +2,7 @@
 
 All notable changes to this package will be documented in this file.
 
-## [Unreleased]
+## [2.0.0] - 2026-10-20
 
 ### Breaking Changes
 
@@ -17,6 +17,59 @@ All notable changes to this package will be documented in this file.
   failures fail export without an HTTP request or delegated fallback. The
   exporter invokes the resolver on every export batch/identity group, so
   resolvers must cache the acquired token and refresh only near expiry.
+- **Manual inference operation names and span-name prefixes now use canonical
+  OpenTelemetry values** — `Chat`, `TextCompletion`, and `GenerateContent`
+  become `chat`, `text_completion`, and `generate_content`, respectively.
+  For example, `Chat gpt-4` becomes `chat gpt-4`. The Agent 365 exporter
+  recognizes the canonical names (the legacy `Chat` value is still accepted),
+  so text-completion and generate-content spans that were previously filtered
+  out are now exported to Agent 365.
+- **`InferenceCallDetails` now validates model identity during construction** —
+  `model` and `responseModel` are stripped and whitespace-only values are
+  treated as `None`. If both are missing, empty, or whitespace-only,
+  construction raises `ValueError`. Previously these values were accepted
+  without validation. This happens before an `InferenceScope` is created.
+- **Message payloads serialize as a plain JSON array** — `gen_ai.input.messages`
+  and `gen_ai.output.messages` are now serialized per the OpenTelemetry GenAI
+  semantic conventions as `[{"role": ..., "parts": [...]}]` instead of the
+  `{"version": "0.1.0", "messages": [...]}` wrapper. The
+  `A365_MESSAGE_SCHEMA_VERSION` constant and the `version` field on
+  `InputMessages`/`OutputMessages` are removed, and `OutputMessage.finish_reason`
+  now defaults to `"stop"` instead of `None`.
+
+### Added
+
+- **`ApplyGuardrailScope`** for tracing security guardrail evaluations
+  (`apply_guardrail` operation), with supporting `GuardrailDetails`,
+  `GuardrailFinding`, `GuardrailDecisionType`, `GuardrailRiskSeverity`, and
+  `GuardrailTargetType` types and `microsoft.guardian.*` /
+  `microsoft.security.*` attribute constants. `apply_guardrail` spans are
+  exported to Agent 365.
+- **`AgentDetails.agent_type`** and **`BaggageBuilder.agent_type()`** emit
+  `gen_ai.agent.type`. Both accept an `AgentType` enum member or a string;
+  enum members are emitted as their string `.value`. The new dataclass field is
+  appended after existing fields, preserving positional-argument compatibility.
+- **`InferenceCallDetails.responseModel`**, **`cacheReadInputTokens`**, and
+  **`cacheWriteInputTokens`** emit `gen_ai.response.model`,
+  `gen_ai.usage.cache_read.input_tokens`, and
+  `gen_ai.usage.cache_write.input_tokens`. `model` is now optional when
+  `responseModel` is supplied. The new fields are appended after existing
+  fields, preserving positional-argument compatibility.
+- **`InferenceScope.record_cache_read_input_tokens()`** and
+  **`record_cache_write_input_tokens()`**.
+- **`InferenceOperationType.canonical_name`** returns the canonical lowercase
+  OpenTelemetry operation name.
+
+### Changed
+
+- `InferenceScope` emits `server.port` as an integer instead of a string.
+
+### Fixed
+
+- Scopes and the Agent 365 exporter no longer raise `AttributeError` when the
+  tracer returns a `NonRecordingSpan` (for example, when the token resolver
+  returns `None` on the first turn); span context is read via
+  `get_span_context()`.
 
 ### Migration
 
@@ -28,8 +81,17 @@ All notable changes to this package will be documented in this file.
   `idtyp` other than `app`; when `idtyp` is absent, accept only a non-empty
   `roles` array or a non-empty `oid` equal to `sub`; verify `aud` is the OBS
   resource and the token is not expired.
-
-## [0.3.0]
+- Update case-sensitive operation-name and span-name filters, dashboards, and
+  alerts to the canonical values above, or compare case-insensitively.
+- Supply a non-blank `model` or `responseModel` when constructing
+  `InferenceCallDetails`; validate optional configuration before constructing
+  the telemetry object so missing model identity does not interrupt a request.
+- Update consumers that parse `gen_ai.input.messages` /
+  `gen_ai.output.messages` to expect a JSON array rather than a
+  `{version, messages}` object, and remove references to
+  `A365_MESSAGE_SCHEMA_VERSION`.
+
+## [1.0.0] - 2026-05-01
 
 ### Breaking Changes
 

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

@@ -121,13 +121,23 @@ with InvokeAgentScope.start(
 Traces LLM/AI model inference calls:
 
 ```python
-from microsoft_agents_a365.observability.core import InferenceScope, InferenceCallDetails, Request
+from microsoft_agents_a365.observability.core import (
+    InferenceCallDetails,
+    InferenceOperationType,
+    InferenceScope,
+    Request,
+    ServiceEndpoint,
+)
 
 with InferenceScope.start(
     request=Request(content="Hello"),
     details=InferenceCallDetails(
-        model_name="gpt-4",
-        provider="openai"
+        operationName=InferenceOperationType.CHAT,
+        model="gpt-4",
+        providerName="openai",
+        responseModel="gpt-4-2025-04-14",
+        cacheReadInputTokens=20,
+        endpoint=ServiceEndpoint(hostname="models.example.com", port=443),
     ),
     agent_details=agent_details,
 ) as scope:
@@ -276,9 +286,9 @@ class AgentDetails:
     agent_auid: str | None        # Agent unique identifier
     agent_email: str | None       # Agent email address
     agent_blueprint_id: str | None
-    agent_type: AgentType | None
     tenant_id: str | None
     icon_uri: str | None
+    agent_type: AgentType | str | None  # appended last for positional compat
 ```
 
 ### UserDetails
@@ -317,11 +327,27 @@ class SpanDetails:
 ```python
 @dataclass
 class InferenceCallDetails:
-    model_name: str | None
-    provider: str | None
-    # Additional inference metadata
+    operationName: InferenceOperationType
+    model: str | None
+    providerName: str
+    inputTokens: int | None
+    outputTokens: int | None
+    finishReasons: list[str] | None
+    thoughtProcess: str | None
+    endpoint: ServiceEndpoint | None
+    responseModel: str | None            # appended last for positional compat
+    cacheReadInputTokens: int | None     # appended last for positional compat
+    cacheWriteInputTokens: int | None    # appended last for positional compat
 ```
 
+At least one of `model` or `responseModel` must be present (whitespace-only
+values are normalized to `None`). The `gen_ai.operation.name` attribute and the
+span name prefix are derived from `operationName` via its canonical lowercase
+form (`InferenceOperationType.CHAT` -> `chat`, `TEXT_COMPLETION` ->
+`text_completion`, `GENERATE_CONTENT` -> `generate_content`), matching the
+OpenTelemetry GenAI semantic conventions and the Agent365 model observation
+pipeline. Endpoint ports and token counts are emitted as integers.
+
 ### ToolCallDetails
 
 ```python

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

@@ -2,7 +2,9 @@
 # Licensed under the MIT License.
 
 from dataclasses import dataclass
-from typing import Optional
+from typing import Optional, Union
+
+from .models.agent_type import AgentType
 
 
 @dataclass
@@ -41,3 +43,10 @@ class AgentDetails:
 
     agent_version: Optional[str] = None
     """Optional version of the agent (e.g., "1.0.0", "2025-05-01")."""
+
+    # NOTE: Appended after all pre-existing fields (rather than inserted in the
+    # middle) to preserve positional-argument compatibility for existing callers.
+    agent_type: Optional[Union[AgentType, str]] = None
+    """Type classification for the agent. Accepts an `AgentType` enum member or
+    a raw string; enum members are normalized to their string `.value` when
+    emitted as a span attribute or baggage entry."""

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

@@ -37,6 +37,7 @@
 GEN_AI_RESPONSE_MODEL_KEY = "gen_ai.response.model"
 GEN_AI_RESPONSE_ID_KEY = "gen_ai.response.id"
 GEN_AI_AGENT_ID_KEY = "gen_ai.agent.id"
+GEN_AI_AGENT_TYPE_KEY = "gen_ai.agent.type"
 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"
@@ -47,6 +48,8 @@
 GEN_AI_TOKEN_TYPE_KEY = "gen_ai.token.type"
 GEN_AI_USAGE_INPUT_TOKENS_KEY = "gen_ai.usage.input_tokens"
 GEN_AI_USAGE_OUTPUT_TOKENS_KEY = "gen_ai.usage.output_tokens"
+GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS_KEY = "gen_ai.usage.cache_read.input_tokens"
+GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS_KEY = "gen_ai.usage.cache_write.input_tokens"
 GEN_AI_CHOICE = "gen_ai.choice"
 GEN_AI_PROVIDER_NAME_KEY = "gen_ai.provider.name"
 

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/exporters/utils.py

@@ -34,6 +34,12 @@
 # Operation names that identify a span as eligible for export to the Agent 365
 # observability ingest service. Only spans whose gen_ai.operation.name matches
 # one of these values are included; all other spans are filtered out.
+#
+# Inference spans now emit the canonical lowercase operation name for their
+# InferenceOperationType (e.g. "chat", "text_completion", "generate_content" -
+# see InferenceOperationType.canonical_name), so all three are recognized here.
+# The legacy PascalCase "Chat" value is kept for back-compat with any
+# previously-emitted/non-Python spans that still use the raw enum value.
 GEN_AI_OPERATION_NAMES: frozenset[str] = frozenset(
     {
         INVOKE_AGENT_OPERATION_NAME,
@@ -42,6 +48,9 @@
         APPLY_GUARDRAIL_OPERATION_NAME,
         CHAT_OPERATION_NAME,
         InferenceOperationType.CHAT.value,
+        InferenceOperationType.CHAT.canonical_name,
+        InferenceOperationType.TEXT_COMPLETION.canonical_name,
+        InferenceOperationType.GENERATE_CONTENT.canonical_name,
     }
 )
 

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

@@ -12,10 +12,30 @@ class InferenceCallDetails:
     """Details of an inference call for generative AI operations."""
 
     operationName: InferenceOperationType
-    model: str
+    model: str | None
     providerName: str
     inputTokens: int | None = None
     outputTokens: int | None = None
     finishReasons: list[str] | None = None
     thoughtProcess: str | None = None
     endpoint: ServiceEndpoint | None = None
+    # NOTE: Appended after all pre-existing fields (rather than inserted in the
+    # middle) to preserve positional-argument compatibility for existing callers.
+    responseModel: str | None = None
+    cacheReadInputTokens: int | None = None
+    cacheWriteInputTokens: int | None = None
+
+    def __post_init__(self) -> None:
+        """Normalize and validate required model identity.
+
+        Whitespace-only `model`/`responseModel` values are normalized to
+        `None` so that validation and downstream consumers (e.g.
+        `InferenceScope`) never treat a blank string as a present model.
+        """
+        if self.model is not None:
+            self.model = self.model.strip() or None
+        if self.responseModel is not None:
+            self.responseModel = self.responseModel.strip() or None
+
+        if not self.model and not self.responseModel:
+            raise ValueError("At least one of model or responseModel must be provided")

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

@@ -10,3 +10,12 @@ class InferenceOperationType(Enum):
     CHAT = "Chat"
     TEXT_COMPLETION = "TextCompletion"
     GENERATE_CONTENT = "GenerateContent"
+
+    @property
+    def canonical_name(self) -> str:
+        """The canonical lowercase operation name per the OpenTelemetry GenAI
+        semantic conventions (e.g. ``chat``, ``text_completion``,
+        ``generate_content``). Used for both the span name prefix and the
+        ``gen_ai.operation.name`` attribute.
+        """
+        return self.name.lower()