Telemetry parity with Python SDK, sample and docs alignment

Author: Xiting Zhang

sdk/voicelive/azure-ai-voicelive/CHANGELOG.md

@@ -7,10 +7,12 @@
 - Added built-in OpenTelemetry tracing support for voice sessions following GenAI Semantic Conventions:
   - `VoiceLiveClientBuilder.openTelemetry(OpenTelemetry)` method for providing a custom OpenTelemetry instance
   - Defaults to `GlobalOpenTelemetry.getOrNoop()` for automatic Java agent detection with zero-cost no-op fallback
-  - Emits spans for `connect`, `send`, `recv`, and `close` operations with voice-specific attributes
-  - Session-level counters: turn count, interruption count, audio bytes sent/received, first token latency
-  - Per-message attributes: token usage, event types, error details
-  - Content recording controlled via `enableContentRecording(boolean)` or `AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED` environment variable
+  - Emits spans for `connect`, `send`, `recv`, and `close` operations with Python-aligned VoiceLive telemetry semantics
+  - Session-level counters: turn count, interruption count, audio bytes sent/received, first token latency, MCP call/list-tools counts
+  - Tracks response and item hierarchy IDs (`response_id`, `conversation_id`, `item_id`, `call_id`, `previous_item_id`, `output_index`) on send/recv spans
+  - Captures agent/session config attributes on connect spans (`gen_ai.agent.*`, `gen_ai.system_instructions`, `gen_ai.request.*`)
+  - Adds OpenTelemetry metrics (`gen_ai.client.operation.duration`, `gen_ai.client.token.usage`) with provider/server/model dimensions
+  - Content recording controlled via `enableContentRecording(boolean)` or `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` (with legacy `AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED` fallback)
 - Added `TelemetrySample.java` demonstrating OpenTelemetry integration patterns
 
 ### Breaking Changes

sdk/voicelive/azure-ai-voicelive/README.md

@@ -126,6 +126,8 @@ The following sections provide code snippets for common scenarios:
 * [Handle event types](#handle-event-types)
 * [Voice configuration](#voice-configuration)
 * [Function calling](#function-calling)
+* [MCP tool integration](#mcp-tool-integration)
+* [Azure AI Foundry agent session](#azure-ai-foundry-agent-session)
 * [Telemetry and tracing](#telemetry-and-tracing)
 * [Complete voice assistant with microphone](#complete-voice-assistant-with-microphone)
 
@@ -173,6 +175,19 @@ For easier learning, explore these focused samples in order:
    - Span structure and session-level attributes
    - Azure Monitor integration example
 
+8. **MCPSample.java** - Model Context Protocol (MCP) tool integration
+   - Configure MCP servers for external tool access
+   - Handle MCP call events and tool execution
+   - Handle MCP approval requests for tool calls
+   - Process MCP call results and continue conversations
+
+9. **AgentV2Sample.java** - Azure AI Foundry agent session
+   - Connect directly to an Azure AI Foundry agent via AgentSessionConfig
+   - Real-time audio capture and playback
+   - Sequence number based audio for interrupt handling
+   - Azure noise suppression and echo cancellation
+   - Conversation logging to file
+
 > **Note:** To run audio samples (AudioPlaybackSample, MicrophoneInputSample, VoiceAssistantSample, FunctionCallingSample):
 > ```bash
 > mvn exec:java -Dexec.mainClass=com.azure.ai.voicelive.FunctionCallingSample -Dexec.classpathScope=test
@@ -404,6 +419,66 @@ client.startSession("gpt-4o-realtime-preview")
 * Results are sent back to continue the conversation
 * See `FunctionCallingSample.java` for a complete working example
 
+### MCP tool integration
+
+Use [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers to give the AI access to external tools during a voice session. The service calls the MCP server directly — your code only needs to handle approval requests when required:
+
+```java com.azure.ai.voicelive.mcp
+// Configure MCP servers as tools
+MCPServer mcpServer = new MCPServer("deepwiki", "https://mcp.deepwiki.com/mcp")
+    .setRequireApproval(BinaryData.fromObject(MCPApprovalType.ALWAYS));
+
+VoiceLiveSessionOptions options = new VoiceLiveSessionOptions()
+    .setTools(Arrays.asList(mcpServer))
+    .setInstructions("You have access to external tools via MCP. Use them when asked.");
+
+// Handle MCP approval requests in your event loop
+session.receiveEvents().subscribe(event -> {
+    if (event instanceof SessionUpdateResponseOutputItemDone) {
+        SessionUpdateResponseOutputItemDone itemDone = (SessionUpdateResponseOutputItemDone) event;
+        SessionResponseItem item = itemDone.getItem();
+
+        if (item instanceof ResponseMCPApprovalRequestItem) {
+            // Approve the tool call
+            ResponseMCPApprovalRequestItem approvalRequest = (ResponseMCPApprovalRequestItem) item;
+            MCPApprovalResponseRequestItem approval = new MCPApprovalResponseRequestItem(
+                approvalRequest.getId(), true);
+            ClientEventConversationItemCreate createItem = new ClientEventConversationItemCreate()
+                .setItem(approval);
+            session.sendEvent(createItem).subscribe();
+            session.sendEvent(new ClientEventResponseCreate()).subscribe();
+        }
+    }
+});
+```
+
+> See `MCPSample.java` for a complete working example with MCP server configuration.
+
+### Azure AI Foundry agent session
+
+Connect directly to an Azure AI Foundry agent using `AgentSessionConfig`. The agent becomes the primary responder for the voice session:
+
+```java com.azure.ai.voicelive.agentsession
+// Configure agent connection
+AgentSessionConfig agentConfig = new AgentSessionConfig("my-agent", "my-project")
+    .setAgentVersion("1.0");
+
+// Start session with agent config (uses DefaultAzureCredential)
+VoiceLiveAsyncClient client = new VoiceLiveClientBuilder()
+    .endpoint(endpoint)
+    .credential(new DefaultAzureCredentialBuilder().build())
+    .buildAsyncClient();
+
+client.startSession(agentConfig)
+    .flatMap(session -> {
+        session.receiveEvents().subscribe(event -> handleEvent(event));
+        return Mono.just(session);
+    })
+    .block();
+```
+
+> See `AgentV2Sample.java` for a full implementation with audio capture, playback, and conversation logging.
+
 ### Telemetry and tracing
 
 The SDK has built-in [OpenTelemetry](https://opentelemetry.io/) tracing that emits spans for every WebSocket operation. When no OpenTelemetry SDK is present, all tracing calls are automatically no-op with zero performance impact.
@@ -448,29 +523,58 @@ connect gpt-4o-realtime-preview        ← session lifetime span
 
 **Session-level attributes** (on the connect span):
 - `gen_ai.system` — `az.ai.voicelive`
+- `gen_ai.provider.name` — `microsoft.foundry`
 - `gen_ai.request.model` — Model name (e.g., `gpt-4o-realtime-preview`)
 - `server.address` — Service endpoint
 - `gen_ai.voice.session_id` — Voice session ID
+- `gen_ai.conversation.id` — Conversation ID
+- `gen_ai.response.id` — Latest response ID
+- `gen_ai.response.finish_reasons` — Response status list (e.g. `[`"completed"`]`)
+- `gen_ai.agent.name` / `gen_ai.agent.id` / `gen_ai.agent.thread_id` — Agent metadata when using agent sessions
+- `gen_ai.system_instructions` / `gen_ai.request.temperature` / `gen_ai.request.max_output_tokens` / `gen_ai.request.tools` — Session config tracked from `session.update`
 - `gen_ai.voice.turn_count` — Completed response turns
 - `gen_ai.voice.interruption_count` — User interruptions
 - `gen_ai.voice.audio_bytes_sent` / `gen_ai.voice.audio_bytes_received` — Audio payload bytes
 - `gen_ai.voice.first_token_latency_ms` — Time to first audio response
+- `gen_ai.voice.mcp.call_count` / `gen_ai.voice.mcp.list_tools_count` — MCP operation counters
 
 #### Content recording
 
 By default, message payloads are not recorded in spans for privacy. Enable content recording via the builder or environment variable:
 
-```java
-// Via builder
-new VoiceLiveClientBuilder()
+```java com.azure.ai.voicelive.tracing.contentrecording
+// Enable content recording to capture full JSON payloads in span events
+VoiceLiveAsyncClient client = new VoiceLiveClientBuilder()
+    .endpoint(endpoint)
+    .credential(new AzureKeyCredential(apiKey))
+    .openTelemetry(otel)
     .enableContentRecording(true)
-    // ...
+    .buildAsyncClient();
 
-// Or via environment variable
-// AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED=true
+// Or via environment variables (no code changes needed):
+// OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+// (legacy fallback) AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED=true
 ```
 
 > See `TelemetrySample.java` for complete tracing examples including Azure Monitor integration.
+>
+> **Run the telemetry sample** to see tracing in action:
+> ```bash
+> # Tracing only (prints span names and attributes):
+> mvn exec:java -Dexec.mainClass="com.azure.ai.voicelive.TelemetrySample" -Dexec.classpathScope=test -Dexec.args="--enable-tracing"
+>
+> # Tracing + content recording (also prints full JSON payloads):
+> mvn exec:java -Dexec.mainClass="com.azure.ai.voicelive.TelemetrySample" -Dexec.classpathScope=test -Dexec.args="--enable-tracing --enable-recording"
+> ```
+>
+> Sample output with `--enable-tracing`:
+> ```
+> 'send session.update' : {gen_ai.operation.name=send, gen_ai.voice.event_type=session.update, ...}
+> 'recv session.created' : {gen_ai.operation.name=recv, gen_ai.voice.event_type=session.created, ...}
+> 'recv response.done'   : {gen_ai.usage.input_tokens=100, gen_ai.usage.output_tokens=50, ...}
+> 'close'                : {gen_ai.operation.name=close, ...}
+> 'connect gpt-4o-realtime-preview' : {gen_ai.voice.session_id=..., gen_ai.voice.turn_count=1, ...}
+> ```
 
 ### Complete voice assistant with microphone
 
@@ -517,7 +621,7 @@ client.startSession("gpt-4o-realtime-preview")
         // Subscribe to receive server events
         session.receiveEvents()
             .subscribe(
-                event -> handleEvent(event, session),
+                event -> handleEvent(event),
                 error -> System.err.println("Error: " + error.getMessage())
             );
 

sdk/voicelive/azure-ai-voicelive/checkstyle-suppressions.xml

@@ -14,6 +14,7 @@
   <suppress files="com.azure.ai.voicelive.ReadmeSamples.java" checks="IllegalImportCheck" />
   <suppress files="com.azure.ai.voicelive.TelemetrySample.java" checks="IllegalImportCheck" />
   <suppress files="com.azure.ai.voicelive.VoiceAssistantSample.java" checks="IllegalImportCheck" />
+  <suppress files="com.azure.ai.voicelive.telemetry.VoiceLiveTelemetryAttributeKeys.java" checks="IllegalImportCheck" />
 
   <suppress files="com.azure.ai.voicelive.models.AssistantMessageItem.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
   <suppress files="com.azure.ai.voicelive.models.MessageItem.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />

sdk/voicelive/azure-ai-voicelive/src/main/java/com/azure/ai/voicelive/VoiceLiveAsyncClient.java

@@ -18,6 +18,7 @@
 import com.azure.core.http.HttpHeaderName;
 import com.azure.core.http.HttpHeaders;
 import com.azure.core.util.logging.ClientLogger;
+import io.opentelemetry.api.metrics.Meter;
 import io.opentelemetry.api.trace.Tracer;
 
 import reactor.core.publisher.Mono;
@@ -36,6 +37,7 @@ public final class VoiceLiveAsyncClient {
     private final String apiVersion;
     private final HttpHeaders additionalHeaders;
     private final Tracer tracer;
+    private final Meter meter;
     private final Boolean enableContentRecording;
 
     /**
@@ -62,12 +64,18 @@ public final class VoiceLiveAsyncClient {
      */
     VoiceLiveAsyncClient(URI endpoint, KeyCredential keyCredential, String apiVersion, HttpHeaders additionalHeaders,
         Tracer tracer, Boolean enableContentRecording) {
+        this(endpoint, keyCredential, apiVersion, additionalHeaders, tracer, null, enableContentRecording);
+    }
+
+    VoiceLiveAsyncClient(URI endpoint, KeyCredential keyCredential, String apiVersion, HttpHeaders additionalHeaders,
+        Tracer tracer, Meter meter, Boolean enableContentRecording) {
         this.endpoint = Objects.requireNonNull(endpoint, "'endpoint' cannot be null");
         this.keyCredential = Objects.requireNonNull(keyCredential, "'keyCredential' cannot be null");
         this.tokenCredential = null;
         this.apiVersion = Objects.requireNonNull(apiVersion, "'apiVersion' cannot be null");
         this.additionalHeaders = additionalHeaders != null ? additionalHeaders : new HttpHeaders();
         this.tracer = tracer;
+        this.meter = meter;
         this.enableContentRecording = enableContentRecording;
     }
 
@@ -96,12 +104,18 @@ public final class VoiceLiveAsyncClient {
      */
     VoiceLiveAsyncClient(URI endpoint, TokenCredential tokenCredential, String apiVersion,
         HttpHeaders additionalHeaders, Tracer tracer, Boolean enableContentRecording) {
+        this(endpoint, tokenCredential, apiVersion, additionalHeaders, tracer, null, enableContentRecording);
+    }
+
+    VoiceLiveAsyncClient(URI endpoint, TokenCredential tokenCredential, String apiVersion,
+        HttpHeaders additionalHeaders, Tracer tracer, Meter meter, Boolean enableContentRecording) {
         this.endpoint = Objects.requireNonNull(endpoint, "'endpoint' cannot be null");
         this.keyCredential = null;
         this.tokenCredential = Objects.requireNonNull(tokenCredential, "'tokenCredential' cannot be null");
         this.apiVersion = Objects.requireNonNull(apiVersion, "'apiVersion' cannot be null");
         this.additionalHeaders = additionalHeaders != null ? additionalHeaders : new HttpHeaders();
         this.tracer = tracer;
+        this.meter = meter;
         this.enableContentRecording = enableContentRecording;
     }
 
@@ -116,7 +130,7 @@ public Mono<VoiceLiveSessionAsyncClient> startSession(String model) {
         Objects.requireNonNull(model, "'model' cannot be null");
 
         return Mono.fromCallable(() -> convertToWebSocketEndpoint(endpoint, model)).flatMap(wsEndpoint -> {
-            VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, model);
+            VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, model, null);
             return session.connect(additionalHeaders).thenReturn(session);
         });
     }
@@ -129,7 +143,7 @@ public Mono<VoiceLiveSessionAsyncClient> startSession(String model) {
      */
     public Mono<VoiceLiveSessionAsyncClient> startSession() {
         return Mono.fromCallable(() -> convertToWebSocketEndpoint(endpoint, null)).flatMap(wsEndpoint -> {
-            VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, null);
+            VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, null, null);
             return session.connect(additionalHeaders).thenReturn(session);
         });
     }
@@ -149,7 +163,7 @@ public Mono<VoiceLiveSessionAsyncClient> startSession(String model, VoiceLiveReq
         return Mono
             .fromCallable(() -> convertToWebSocketEndpoint(endpoint, model, requestOptions.getCustomQueryParameters()))
             .flatMap(wsEndpoint -> {
-                VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, model);
+                VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, model, null);
                 // Merge additional headers with custom headers from requestOptions
                 HttpHeaders mergedHeaders = mergeHeaders(additionalHeaders, requestOptions.getCustomHeaders());
                 return session.connect(mergedHeaders).thenReturn(session);
@@ -170,7 +184,7 @@ public Mono<VoiceLiveSessionAsyncClient> startSession(VoiceLiveRequestOptions re
         return Mono
             .fromCallable(() -> convertToWebSocketEndpoint(endpoint, null, requestOptions.getCustomQueryParameters()))
             .flatMap(wsEndpoint -> {
-                VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, null);
+                VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, null, null);
                 // Merge additional headers with custom headers from requestOptions
                 HttpHeaders mergedHeaders = mergeHeaders(additionalHeaders, requestOptions.getCustomHeaders());
                 return session.connect(mergedHeaders).thenReturn(session);
@@ -193,7 +207,7 @@ public Mono<VoiceLiveSessionAsyncClient> startSession(AgentSessionConfig agentCo
 
         return Mono.fromCallable(() -> convertToWebSocketEndpoint(endpoint, null, agentConfig.toQueryParameters()))
             .flatMap(wsEndpoint -> {
-                VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, null);
+                VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, null, agentConfig);
                 return session.connect(additionalHeaders).thenReturn(session);
             });
     }
@@ -223,7 +237,7 @@ public Mono<VoiceLiveSessionAsyncClient> startSession(AgentSessionConfig agentCo
         }
 
         return Mono.fromCallable(() -> convertToWebSocketEndpoint(endpoint, null, mergedParams)).flatMap(wsEndpoint -> {
-            VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, null);
+            VoiceLiveSessionAsyncClient session = createSessionClient(wsEndpoint, null, agentConfig);
             // Merge additional headers with custom headers from requestOptions
             HttpHeaders mergedHeaders = mergeHeaders(additionalHeaders, requestOptions.getCustomHeaders());
             return session.connect(mergedHeaders).thenReturn(session);
@@ -237,11 +251,14 @@ public Mono<VoiceLiveSessionAsyncClient> startSession(AgentSessionConfig agentCo
      * @param model The model name, used for tracing span names.
      * @return A new VoiceLiveSessionAsyncClient instance.
      */
-    private VoiceLiveSessionAsyncClient createSessionClient(URI wsEndpoint, String model) {
+    private VoiceLiveSessionAsyncClient createSessionClient(URI wsEndpoint, String model,
+        AgentSessionConfig agentSessionConfig) {
         if (keyCredential != null) {
-            return new VoiceLiveSessionAsyncClient(wsEndpoint, keyCredential, tracer, model, enableContentRecording);
+            return new VoiceLiveSessionAsyncClient(wsEndpoint, keyCredential, tracer, meter, model,
+                enableContentRecording, agentSessionConfig);
         } else {
-            return new VoiceLiveSessionAsyncClient(wsEndpoint, tokenCredential, tracer, model, enableContentRecording);
+            return new VoiceLiveSessionAsyncClient(wsEndpoint, tokenCredential, tracer, meter, model,
+                enableContentRecording, agentSessionConfig);
         }
     }