[nodejs]Update message format to align with OTel spec by fpfp100 · Pull Request #256 · microsoft/Agent365-nodejs

fpfp100 · 2026-05-21T21:10:53Z

Summary

Remove the versioned { version: "0.1.0", messages: [...] } envelope from message serialization — messages now serialize as a plain JSON array [...] per OTel gen-ai semantic conventions
Default finish_reason to "stop" on output messages created from plain strings via toOutputMessages/normalizeOutputMessages
Tighten isWrappedMessages type guard with Array.isArray check to prevent false positives

Test plan

All 1270 unit tests pass
Build succeeds (CJS + ESM)
Lint clean
Verify integration tests pass in CI

🤖 Generated with Claude Code

Remove the versioned wrapper `{ version, messages }` envelope from message serialization. Messages now serialize as a plain JSON array per OTel gen-ai semantic conventions. Output messages default finish_reason to "stop" when created from plain strings via toOutputMessages/normalizeOutputMessages. Port of microsoft/Agent365-dotnet#253. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

This PR updates the observability message serialization format to match OpenTelemetry gen-ai semantic conventions by removing the versioned { version, messages } envelope and emitting a plain JSON array of messages, while also defaulting finish_reason to "stop" for output messages created from plain strings and tightening wrapper detection.

Changes:

Serialize gen_ai.{input,output}.messages as a plain JSON array instead of a versioned wrapper object.
Default finish_reason to "stop" for output messages produced from string / string[] inputs.
Update wrapper type guards, contracts, exporter truncation logic, and tests to reflect the new format.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/observability/tracing/message-utils.test.ts	Updates unit tests for wrapper detection, normalization, and array-based serialization; adds finish_reason expectations.
tests/observability/integration/openai-agent-instrument.test.ts	Adjusts integration assertions to expect JSON arrays for input/output message attributes.
tests/observability/integration/langchain-agent-instrument.test.ts	Adjusts integration assertions to expect JSON arrays for input/output message attributes.
tests/observability/integration/helpers/span-validators.ts	Updates span validators to treat message attributes as arrays (not `{version,messages}`).
tests/observability/extension/openai/OpenAIMessageContract.test.ts	Updates OpenAI extension contract tests to index into the serialized array.
tests/observability/extension/openai/OpenAIAgentsTraceProcessor.test.ts	Updates processor tests to validate array serialization and indexing.
tests/observability/extension/langchain/LangChainObservabilityAttributes.test.ts	Updates LangChain extension attribute assertions to expect array JSON.
tests/observability/extension/langchain/LangChainMessageContract.test.ts	Updates LangChain message contract tests for array JSON format.
tests/observability/extension/hosting/scope-utils.test.ts	Updates hosting scope tests to expect array serialization for input messages.
tests/observability/extension/hosting/output-logging-middleware.test.ts	Updates middleware tests to expect array output messages plus default finish_reason.
tests/observability/extension/helpers/message-schema-validator.ts	Updates shared validator to validate “plain array of messages” payloads.
tests/observability/core/scopes.test.ts	Updates core scope tests to validate array-based attributes and finish_reason defaults.
tests/observability/core/scope-messages.test.ts	Updates scope message recording tests for array format and finish_reason defaults.
tests/observability/core/output-scope.test.ts	Updates OutputScope tests to validate array output messages and finish_reason defaults.
tests/observability/core/agent365-exporter.test.ts	Updates exporter truncation tests to validate array-based message attributes.
packages/agents-a365-observability/src/tracing/scopes/OutputScope.ts	Removes versioned wrapping and refines raw-dict detection for output message recording.
packages/agents-a365-observability/src/tracing/message-utils.ts	Implements array serialization, default finish_reason, and tighter wrapper guard.
packages/agents-a365-observability/src/tracing/exporter/utils.ts	Updates truncation logic to parse/flush message attributes as arrays and adjust overflow sentinel generation.
packages/agents-a365-observability/src/tracing/contracts.ts	Removes `version` from message wrapper contracts and introduces `DEFAULT_FINISH_REASON`.
packages/agents-a365-observability/src/index.ts	Updates public exports to expose `DEFAULT_FINISH_REASON` instead of the schema version constant.
packages/agents-a365-observability-extensions-openai/src/Utils.ts	Updates OpenAI extension helpers to build wrappers without version and default finish_reason for assistant.
packages/agents-a365-observability-extensions-langchain/src/Utils.ts	Updates LangChain extension to wrap messages without version before serializing.

- Remove unused DEFAULT_FINISH_REASON import from test file - Remove finish_reason from serialization fallback and overflow sentinel (finish_reason is output-only per OTel spec, sentinels are used for both input and output attributes) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The "validate error.type on failing tool" test was flaky because it used waitForSpans with a generic count of 2, which could resolve before the tool span was emitted. Now polls specifically for the execute_tool span by name with a 15s timeout. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

* Update message format to align with OTel spec Remove the versioned `{ version, messages }` envelope from message serialization. Messages now serialize as a plain JSON array per OTel gen-ai semantic conventions. Output messages default finish_reason to "stop" when created from plain strings via toOutputMessages/normalizeOutputMessages. Tighten isWrappedMessages type guard with Array.isArray check. Port of microsoft/Agent365-nodejs#256. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix lint: remove unused InputMessages import from scopes test Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Peng Fan <pefan@microsoft.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 1 comment.

+  expect(Array.isArray(parsed)).toBe(true);
+  expect(parsed.length).toBeGreaterThan(0);
  return parsed;


Copilot AI review requested due to automatic review settings May 21, 2026 21:10

fpfp100 requested a review from a team as a code owner May 21, 2026 21:10

Copilot started reviewing on behalf of fpfp100 May 21, 2026 21:11 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

jsl517 and others added 2 commits May 21, 2026 15:35

Copilot AI review requested due to automatic review settings May 21, 2026 23:07

Copilot started reviewing on behalf of fpfp100 May 21, 2026 23:08 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

Comment thread packages/agents-a365-observability/src/tracing/message-utils.ts

Comment thread packages/agents-a365-observability/src/tracing/scopes/OutputScope.ts

Comment thread packages/agents-a365-observability-extensions-openai/src/Utils.ts

fpfp100 changed the title ~~Update message format to align with OTel spec~~ [nodejs]Update message format to align with OTel spec May 26, 2026

nikhilNava approved these changes May 26, 2026

View reviewed changes

juliomenendez approved these changes May 26, 2026

View reviewed changes

Merge branch 'main' into users/pefan/otel-message-format

1259740

fpfp100 mentioned this pull request May 27, 2026

Update message format to align with OTel spec microsoft/opentelemetry-distro-javascript#155

Merged

4 tasks

Merge branch 'main' into users/pefan/otel-message-format

80f76ef

Copilot AI review requested due to automatic review settings June 8, 2026 18:13

Copilot started reviewing on behalf of gwharris7 June 8, 2026 18:14 View session

gwharris7 enabled auto-merge (squash) June 8, 2026 18:14

gwharris7 merged commit c393d5f into main Jun 8, 2026
8 checks passed

gwharris7 deleted the users/pefan/otel-message-format branch June 8, 2026 18:18

Copilot AI reviewed Jun 8, 2026

View reviewed changes

Comment thread tests/observability/extension/helpers/message-schema-validator.ts

Comment on lines +10 to 12

expect(Array.isArray(parsed)).toBe(true);

expect(parsed.length).toBeGreaterThan(0);

return parsed;

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[nodejs]Update message format to align with OTel spec#256

[nodejs]Update message format to align with OTel spec#256
gwharris7 merged 5 commits into
mainfrom
users/pefan/otel-message-format

fpfp100 commented May 21, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

fpfp100 commented May 21, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants