From 8cead866ff6a067b5fca4ac476c334fd37fbc707 Mon Sep 17 00:00:00 2001 From: abdulsaboor Date: Fri, 11 Sep 2026 00:48:45 -0500 Subject: [PATCH 1/3] [Agents] Add Voice diagnostics changelog --- ...6-09-12-voice-diagnostics-turn-metrics.mdx | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 src/content/changelog/agents/2026-09-12-voice-diagnostics-turn-metrics.mdx diff --git a/src/content/changelog/agents/2026-09-12-voice-diagnostics-turn-metrics.mdx b/src/content/changelog/agents/2026-09-12-voice-diagnostics-turn-metrics.mdx new file mode 100644 index 00000000000..2a6af93ddd3 --- /dev/null +++ b/src/content/changelog/agents/2026-09-12-voice-diagnostics-turn-metrics.mdx @@ -0,0 +1,76 @@ +--- +title: Inspect Voice Agent turn latency and outcomes +description: "@cloudflare/voice v0.4.0 adds per-turn metrics and browser diagnostics for Voice Agents." +products: + - agents +date: 2026-09-12 +--- + +import { PackageManagers, TypeScriptExample } from "~/components"; + +`@cloudflare/voice` v0.4.0 now lets you inspect where each Voice Agent turn spends time and how it ends. + +```ts +client.addEventListener("turnmetrics", (turn) => { + console.log(turn.outcome, turn.turnTotalMs); +}); +``` + +### What is the Voice package? + +The `@cloudflare/voice` package lets you build real-time voice agents with Cloudflare Agents. It streams microphone audio to an Agent over WebSocket, transcribes speech, runs your model through `onTurn()`, converts the response to speech, and streams audio back to the caller. + +A turn moves through several stages: + +```txt +User speaks -> speech-to-text -> model -> text-to-speech -> audio +``` + +Previously, the package's four aggregate metrics covered successful, non-empty speech turns. They did not show how failed, aborted, empty, or text turns ended. + +### What is new? + +Each speech or text turn now produces a typed `VoiceTurnMetrics` summary with: + +- A `turnId` for correlating events from the same turn. +- A terminal outcome such as `completed`, `no_output`, `output_limit`, `content_filtered`, `model_error`, `tts_error`, or `aborted`. +- Timings for important stages, including speech-to-final-transcript, model-to-first-text, TTS-to-first-audio, and total turn duration. + +These timings can overlap and are not additive. Timings for stages that a turn did not reach are omitted. + +The latest summary is available through `VoiceClient`, `useVoiceAgent()`, and `useVoiceInput()`. Voice input includes only the speech and transcription timings it can measure. + +If an agent produces no audio, you can now distinguish between the model returning no output, reaching an output limit, encountering content filtering, or failing. + +### Additional diagnostics + +For local debugging, server lifecycle events can be forwarded to the browser console: + + + +```ts +import { Agent } from "agents"; +import { withVoice } from "@cloudflare/voice"; + +const VoiceAgent = withVoice(Agent, { + diagnostics: { + browserConsole: true, + }, +}); +``` + + + +The browser console combines server events with local microphone, connection, and playback events. These events show landmarks such as model start, first model text, first audio, and playback start. + +Diagnostic event names and fields can change. The SDK removes known content fields and does not read arbitrary provider responses. Do not put sensitive data in custom error messages. + +`VoiceClient` also exposes typed events for speech-to-text failures, connection errors, and model outcomes. Continuous speech-to-text providers can now report readiness and fatal errors, so a call does not appear ready before its provider connection opens. + +Browser diagnostics are off by default. Existing status values and pipeline metrics continue to work. + +Install the release with a compatible Agents SDK version: + + + +Refer to the [Voice pipeline metrics](/agents/communication-channels/voice/#pipeline-metrics) and [Voice Agent example](https://github.com/cloudflare/agents/tree/main/examples/voice-agent) to get started. From a22907bb8a0ad6db44d10d828d88a355f49d3e33 Mon Sep 17 00:00:00 2001 From: abdulsaboor Date: Fri, 11 Sep 2026 07:39:35 -0500 Subject: [PATCH 2/3] [Agents] Address Voice changelog review --- ....mdx => 2026-09-11-voice-diagnostics-turn-metrics.mdx} | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) rename src/content/changelog/agents/{2026-09-12-voice-diagnostics-turn-metrics.mdx => 2026-09-11-voice-diagnostics-turn-metrics.mdx} (95%) diff --git a/src/content/changelog/agents/2026-09-12-voice-diagnostics-turn-metrics.mdx b/src/content/changelog/agents/2026-09-11-voice-diagnostics-turn-metrics.mdx similarity index 95% rename from src/content/changelog/agents/2026-09-12-voice-diagnostics-turn-metrics.mdx rename to src/content/changelog/agents/2026-09-11-voice-diagnostics-turn-metrics.mdx index 2a6af93ddd3..e80855b3a8f 100644 --- a/src/content/changelog/agents/2026-09-12-voice-diagnostics-turn-metrics.mdx +++ b/src/content/changelog/agents/2026-09-11-voice-diagnostics-turn-metrics.mdx @@ -3,7 +3,7 @@ title: Inspect Voice Agent turn latency and outcomes description: "@cloudflare/voice v0.4.0 adds per-turn metrics and browser diagnostics for Voice Agents." products: - agents -date: 2026-09-12 +date: 2026-09-11 --- import { PackageManagers, TypeScriptExample } from "~/components"; @@ -16,7 +16,7 @@ client.addEventListener("turnmetrics", (turn) => { }); ``` -### What is the Voice package? +### About the Voice package The `@cloudflare/voice` package lets you build real-time voice agents with Cloudflare Agents. It streams microphone audio to an Agent over WebSocket, transcribes speech, runs your model through `onTurn()`, converts the response to speech, and streams audio back to the caller. @@ -28,7 +28,7 @@ User speaks -> speech-to-text -> model -> text-to-speech -> audio Previously, the package's four aggregate metrics covered successful, non-empty speech turns. They did not show how failed, aborted, empty, or text turns ended. -### What is new? +### Turn metrics Each speech or text turn now produces a typed `VoiceTurnMetrics` summary with: @@ -44,7 +44,7 @@ If an agent produces no audio, you can now distinguish between the model returni ### Additional diagnostics -For local debugging, server lifecycle events can be forwarded to the browser console: +For local debugging, you can forward server lifecycle events to the browser console: From 56f8393de76d6403eb68e66c374ca95e67578088 Mon Sep 17 00:00:00 2001 From: abdulsaboor Date: Fri, 11 Sep 2026 10:59:47 -0500 Subject: [PATCH 3/3] [Agents] Tighten Voice diagnostics copy --- .../agents/2026-09-11-voice-diagnostics-turn-metrics.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/content/changelog/agents/2026-09-11-voice-diagnostics-turn-metrics.mdx b/src/content/changelog/agents/2026-09-11-voice-diagnostics-turn-metrics.mdx index e80855b3a8f..57b60631e2b 100644 --- a/src/content/changelog/agents/2026-09-11-voice-diagnostics-turn-metrics.mdx +++ b/src/content/changelog/agents/2026-09-11-voice-diagnostics-turn-metrics.mdx @@ -61,13 +61,9 @@ const VoiceAgent = withVoice(Agent, { -The browser console combines server events with local microphone, connection, and playback events. These events show landmarks such as model start, first model text, first audio, and playback start. +The browser console combines server lifecycle events with local microphone, connection, and playback events, including model start, first model text, first audio, and playback start. Diagnostics are off by default, and their event names and fields can change. -Diagnostic event names and fields can change. The SDK removes known content fields and does not read arbitrary provider responses. Do not put sensitive data in custom error messages. - -`VoiceClient` also exposes typed events for speech-to-text failures, connection errors, and model outcomes. Continuous speech-to-text providers can now report readiness and fatal errors, so a call does not appear ready before its provider connection opens. - -Browser diagnostics are off by default. Existing status values and pipeline metrics continue to work. +`VoiceClient` also exposes typed events for speech-to-text failures, connection errors, and model outcomes. The SDK removes known content fields and does not read arbitrary provider responses, but custom error messages must not contain sensitive data. Install the release with a compatible Agents SDK version: