.NET: [Breaking Change] Auto-wire ChatClient with OpenTelemetryChatClient in OpenTelemetryAgent

[Copilot]

Motivation and Context

OpenTelemetryAgent instrumented only the agent-level invoke_agent span; the underlying IChatClient was untouched, so model-level chat spans, usage metrics, and Azure Monitor traces never flowed unless callers manually wrapped every chat client. End result: telemetry silently absent in Foundry/hosted agent samples even with an exporter configured.

Description

OpenTelemetryAgent now auto-wraps the inner ChatClientAgent's IChatClient with OpenTelemetryChatClient on each invocation, so chat-level telemetry flows alongside invoke_agent.

• OpenTelemetryAgent ctors — the original OpenTelemetryAgent(AIAgent innerAgent, string? sourceName = null) constructor signature is preserved (binary-compatible) and delegates with auto-wiring enabled. A new overload OpenTelemetryAgent(AIAgent innerAgent, string? sourceName, bool autoWireChatClient) adds the opt-out. The sourceName is normalized once in the constructor (empty string is treated as OpenTelemetryConsts.DefaultSourceName) and reused by both the outer OpenTelemetryChatClient and the auto-wired inner OpenTelemetryChatClient, so agent-level and chat-level spans always land on the same ActivitySource. The opt-out flag lives only on the constructor (not on the AIAgentBuilder extension), keeping chat-client terminology out of the abstract builder surface.
• Per-invocation wiring — ForwardingChatClient.GetResponseAsync / GetStreamingResponseAsync route the AgentRunOptions through a new GetRunOptionsWithChatClientWiring helper that:
  1. Short-circuits when auto-wire is disabled.
  2. Resolves the nested ChatClientAgent via InnerAgent.GetService<ChatClientAgent>() (no type assumption on InnerAgent; wrapping agents that surface a nested ChatClientAgent through GetService are supported). No-ops when the result is null.
  3. No-ops when chatClientAgent.GetService<ChatClientAgentOptions>()?.UseProvidedChatClientAsIs is true (respects the user's explicit opt-out on the chat client pipeline; ChatClientAgent.GetService already exposes ChatClientAgentOptions).
  4. No-ops when chatClientAgent.GetService<IChatClient>()?.GetService<OpenTelemetryChatClient>() is already non-null (avoids double-wrap).
  5. Otherwise clones the caller's ChatClientAgentRunOptions (or, when the caller passes a plain AgentRunOptions, creates one and copies the base properties: ContinuationToken, AllowBackgroundResponses, AdditionalProperties, ResponseFormat) and sets ChatClientFactory to chain onto any user-supplied factory rather than replacing it. The factory step also inspects the post-user-factory result via GetService(typeof(OpenTelemetryChatClient)) and skips wrapping when the chat client is already instrumented, so a user factory that itself calls UseOpenTelemetry(...) does not produce duplicate chat spans.
• UseOpenTelemetry extension — unchanged public surface; the existing extension simply constructs an OpenTelemetryAgent (with auto-wiring on by default), so telemetry now flows automatically for existing call sites.
• Tests — full coverage of every wiring branch in GetRunOptionsWithChatClientWiring and WrapIfNeeded: default-on (sync + streaming), explicit opt-out via the constructor (sync + streaming), UseProvidedChatClientAsIs opt-out, non-ChatClientAgent no-op, no-double-wrap when the underlying chat client is pre-instrumented, chaining of a user-supplied ChatClientFactory, no-double-wrap when the user factory itself returns an OpenTelemetry-instrumented client, plain AgentRunOptions propagation of AllowBackgroundResponses / AdditionalProperties / ResponseFormat and (separately) ContinuationToken, ChatClientAgentRunOptions clone path with no user factory (asserts ChatOptions are preserved and the caller's instance is not mutated), and null / empty sourceName normalization (Theory: both produce spans on OpenTelemetryConsts.DefaultSourceName).

Behavioral breaking change

This PR introduces a behavioral (not API) change. Existing call sites of new OpenTelemetryAgent(innerAgent) and AIAgentBuilder.UseOpenTelemetry(...) will now begin emitting an additional chat span per invocation when the inner agent is (or surfaces) a ChatClientAgent whose IChatClient is not already wrapped with OpenTelemetryChatClient.

Impact is limited to a specific subset of users:

• Users who previously wrapped both the agent and the chat client themselves are unaffected: the chat-client OTel wrapper is detected and the auto-wire path no-ops.
• Users who wrapped only the agent (the original silent-telemetry case this PR fixes) will start receiving the missing chat-level spans, metrics, and Azure Monitor traces. This is the intended new default.
• Users who do not want the new chat-level spans can opt out either:
  • On the constructor: new OpenTelemetryAgent(innerAgent, sourceName: null, autoWireChatClient: false)
  • On the ChatClientAgent itself: new ChatClientAgent(chatClient, new ChatClientAgentOptions { UseProvidedChatClientAsIs = true })

Source compatibility, binary compatibility, and the UseOpenTelemetry extension surface are all preserved. Only the runtime telemetry shape changes, and only in the direction of emitting strictly more (and previously missing) signal.

Opt-out (constructor-only)

var otelAgent = new OpenTelemetryAgent(innerAgent, sourceName: null, autoWireChatClient: false);

Or via ChatClientAgentOptions:

new ChatClientAgent(chatClient, new ChatClientAgentOptions { UseProvidedChatClientAsIs = true });

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? Behavioral breaking change documented above. Not source/binary breaking.