npm / @microsoft/agents-a365-observability
@microsoft/agents-a365-observability
What changed in @microsoft/agents-a365-observability 1 to 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-20.
41 breaking1 deprecations28 new APIs and options5 behavior and defaults1 tooling4 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@microsoft/agents-a365-observability 233 changes
Breaking changes 10
The export is removed and replaced by DEFAULT_FINISH_REASON.
Both export modes require an app-only resolver configured with withTokenResolver(...) or exporterOptions.tokenResolver; builder configuration takes precedence, and runWithExportToken/updateExportToken are no longer read.
InferenceScope now rejects non-integer ports and ports outside 1-65535.
A resolver is required; missing resolvers fail configuration, while empty tokens or acquisition failures fail export without delegated fallback. The resolver is invoked on every export batch and must cache and refresh tokens near expiry.
gen_ai.input.messages and gen_ai.output.messages are emitted as plain OTel JSON arrays instead of versioned envelopes; consumers parsing these attributes must handle the new shape.
LangChain no longer uses response_metadata.model_name as a fallback for gen_ai.request.model; that value is reported only via gen_ai.response.model.
OpenAI response spans report the served model via gen_ai.response.model and omit gen_ai.request.model; Chat Completions/generation spans report the served model while retaining the requested alias in gen_ai.request.model.
providerName is required; InferenceScope.start() and ScopeUtils.populateInferenceScopeFromTurnContext throw if it is missing or blank.
The TurnContext/Authorization overload is removed in favor of RefreshObservabilityToken(agentId, tenantId, tokenResolver); acquisition failures throw.
The option is deprecated and ignored, even when false; OBS exports always use /observabilityService and no longer select or fall back to /observability.
New APIs and options 14
Adds agentType, mapped to gen_ai.agent.type.
Adds a scope for tracing security guardrail evaluations, with recordDecision(), recordContentOutput(), and recordFinding(), plus guardrail contracts and related microsoft.security.* / microsoft.guardian.* constants. apply_guardrail spans are accepted by the Agent365 exporter.
Adds the GENERATE_CONTENT_OPERATION_NAME constant.
Adds cacheReadInputTokens, mapped to gen_ai.usage.cache_read.input_tokens.
Adds cacheWriteInputTokens, mapped to gen_ai.usage.cache_write.input_tokens.
Adds responseModel, mapped to gen_ai.response.model.
Exports the app-only resolver signature accepted by RefreshObservabilityToken.
Adds an agentic user disabled lifecycle notification handler.
Adds an agentic user enabled lifecycle notification handler.
Adds an agentic user manager updated lifecycle notification handler.
Adds an agentic user undeleted lifecycle notification handler.
Adds an agentic user updated lifecycle notification handler.
Adds the TEXT_COMPLETION_OPERATION_NAME constant.
Exports the exporter token resolver signature.
Behavior and default changes 4
Output messages created from plain strings now default finish_reason to "stop".
InferenceScope maps operationName to its canonical lowercase semantic convention value instead of always emitting chat; the span-name prefix also reflects the operation type.
model is optional, but at least one of model or responseModel must be a non-blank string; blank values are treated as absent.
Inference spans now record server.port when endpoint.port is 443, which was previously omitted as an implicit default.
Tooling 1
Declared as a dependency instead of relying on a transitive install.
Fixes and other changes 4
Uses channelData.productContext for the channel link when activity.channelIdSubChannel is missing or blank.
Reads the server list from the mcpServers field of the tooling gateway response instead of returning an empty list.
ObservabilityManager.start(options) now forwards options.exporterOptions.
Declared as a dependency because the exporter imports it at runtime; this prevents MODULE_NOT_FOUND when another copy is not hoisted.
@microsoft/agents-a365-observability 147 changes
Breaking changes 31
EnhancedAgentDetails is merged into AgentDetails to unify agent detail typing across scopes and middleware.
The agentUPN property is renamed to agentEmail.
Replaced by Request; executionType and the separate InferenceRequest, ToolRequest, and OutputRequest interfaces are removed.
Renamed from BaggageBuilder.agentUpn.
Renamed from BaggageBuilder.serviceName as the fluent setter for the service name baggage value.
Renamed from BaggageBuilder.callerUpn.
Renamed from BaggageBuilder.callerId.
Renamed from BaggageBuilder.callerName.
Replaces SourceMetadata as the exported interface for invocation channel information; the request property is now channel.
No longer needed as an environment variable for recordAttributes, setTagMaybe, and addBaggage.
No longer needed as an environment variable for recordAttributes, setTagMaybe, and addBaggage.
Now takes request, details, agent details, optional user details, and optional span details; tenant ID is required on AgentDetails.
Renamed from extractTraceContext.
Replaces GEN_AI_AGENT_UPN_KEY and uses the microsoft.agent.user.email key.
Replaces GEN_AI_CALLER_AGENT_UPN_KEY and uses the microsoft.a365.caller.agent.user.email key.
Input messages are now recorded in JSON array format instead of comma-separated strings.
Now takes request, details, agent details, optional user details, and optional span details; tenant ID is required on AgentDetails.
Renamed from injectTraceContext.
Input messages are now recorded in JSON array format instead of comma-separated strings.
Now takes request, invoke-scope details, agent details, optional caller details, and optional span details; tenant ID is required on AgentDetails.
Replaces InvokeAgentDetails and contains only scope-level configuration such as endpoint; agent identity is now supplied separately.
messages now accepts OutputMessagesParam, allowing plain string arrays or a versioned OutputMessages wrapper with richer message data.
Now takes request, response, agent details, optional user details, and optional span details; tenant ID is required on AgentDetails.
Replaces AgentRequest and unifies request context across scopes with conversationId, channel, content, and sessionId.
The sourceMetadata property is renamed to channel.
Removed from all scope start methods; tenant ID is now required on AgentDetails, and scopes throw if it is missing.
Replaces GEN_AI_CALLER_UPN_KEY and uses the user.email semantic-convention key.
Replaces GEN_AI_CALLER_ID_KEY and uses the user.id semantic-convention key.
Replaces GEN_AI_CALLER_NAME_KEY and uses the user.name semantic-convention key.
Replaces CallerDetails as the type representing the human caller identity; its properties are userId, userEmail, and userName.
The callerId property is renamed to userId.
Deprecations 1
Now an alias of AgentDetails and marked deprecated; existing imports continue to work.
New APIs and options 14
Adds a per-HTTP-request backend timeout option defaulting to 30 seconds, distinct from the overall exporter timeout.
Sets server address and optional port baggage values; port is recorded only when different from 443 and stale port entries are cleared when omitted or 443.
Wraps userDetails and callerAgentDetails for InvokeAgentScope.
Accepts InputMessagesParam, a string array or versioned InputMessages wrapper; plain strings are auto-wrapped to OTEL gen-ai format.
Accepts OutputMessagesParam, a string array or versioned OutputMessages wrapper; plain strings are auto-wrapped to OTEL gen-ai format.
Versioned wrapper for input messages.
New discriminated union for OTEL Gen-AI message parts, including text, tool-call, reasoning, blob, file, URI, server-tool, and generic parts.
New OTEL Gen-AI message-format type.
Configures the service.namespace resource attribute.
Constant for the cancellation error type value.
Records a cancellation event on the span with error.type set to TaskCanceledException.
Versioned wrapper for output messages.
Groups parentContext, startTime, endTime, and spanKind for scope construction.
Scope classes accept span links through SpanDetails.spanLinks to establish causal relationships to other spans.
Behavior and default changes 1
The default increases from 30 seconds to 90 seconds to allow retries across multiple identity groups within one export cycle.