Cloudflare visar varför röstagenten tystnar – logga utfall och svarstid per tur

Vad Cloudflare ändrade i 0.4.0

I changeloggen Inspect Voice Agent turn latency and outcomes från den 11 september 2026 beskriver Cloudflare en ny typad VoiceTurnMetrics-sammanfattning för varje tal- eller texttur. Tidigare fanns fyra aggregerade pipelinemått för lyckade, icke-tomma talade turer. De kunde visa att något tog lång tid, men inte hur en misslyckad, tom, avbruten eller textbaserad tur slutade.

Den nya sammanfattningen innehåller ett turnId för korrelation, ett terminalt utfall och varaktigheter för de steg som faktiskt nåddes. Installationsparet i changeloggen är:

npm i @cloudflare/voice@^0.4.0 agents@^0.22.0

Caret-intervallen kan ge en senare kompatibel version. Spara därför de faktiskt installerade versionerna från låsfilen i varje testkörning. Om fälten ändras efter 0.4.0 ska loggkontraktet och provets facit granskas igen, inte bara kompilatorfelet rättas.

Logga turens slut, inte samtalet

Cloudflares officiella typdefinition har fyra obligatoriska fält: turnId, source, outcome och turnTotalMs. source är speech eller text. Den fullständiga utfallsunionen i källkoden för den kontrollerade versionen har nio värden:

Loggradens nyckel ska vara ett eget test-id plus turnId. Ett praktiskt test-id kan vara voice-20260912-03; det säger vilken körning raden tillhör utan att avslöja vem som talade. Lägg inte telefonnummer, konto-id eller sessionsnamn i nyckeln om de inte behövs för ett uttryckligt, granskat ändamål.

client.addEventListener("turnmetrics", (turn) => {
  const safeTurn = {
    schema: "voice-turn-v1",
    testId: currentTestId,
    voiceVersion: installedVoiceVersion,
    agentsVersion: installedAgentsVersion,
    turnId: turn.turnId,
    source: turn.source,
    outcome: turn.outcome,
    turnTotalMs: turn.turnTotalMs,
    speechStartToFinalMs: turn.speechStartToFinalMs ?? null,
    modelToFirstTextMs: turn.modelToFirstTextMs ?? null,
    ttsToFirstAudioMs: turn.ttsToFirstAudioMs ?? null,
    finalInputToFirstAudioMs: turn.finalInputToFirstAudioMs ?? null
  };

  console.info("voice_turn", safeTurn);
});

Exemplet plockar bara ut fält på en tillåten lista. Att först serialisera hela händelsen och rensa efteråt är en sämre kontroll: ett nytt innehållsfält kan då hinna nå loggsystemet innan filtret uppdateras. Samma princip används i AI-kreatörs guide om känsliga data i AI-arbete: bestäm vad som får lämna processen och bygg representationen från den listan.

Tolka tiderna utan att summera dem

VoiceTurnMetrics har tio valfria varaktigheter. Bland dem finns tid från talstart till första preliminära respektive slutliga transkript, tid i afterTranscribe, tid från modellstart till första text, streamkonsumtion, tid till första serverljud samt TTS-väggtid och TTS-arbete. Ett valfritt fält saknas när turen inte nådde den livscykelpunkten.

Fältet modelToFirstTextMs svarar på en annan fråga än modelStreamConsumptionMs. Det första hjälper dig hitta väntan före den första icke-tomma textdelen; det andra sträcker sig över konsumtionen av den normaliserade modellströmmen. På samma sätt är ttsToFirstAudioMs en startlatens, medan ttsWallMs omfattar TTS-arbetets väggtid. För en baslinje räcker fyra värden ofta: slutligt transkript, första modelltext, första serverljud och total tur.

Webbläsarens uppspelning ingår inte. Cloudflares typkommentar förklarar att webbläsare och Worker använder oberoende klockor. Om utfallet är completed och servern har ett värde för första ljud, men användaren hör inget, har mätningen flyttat gränsen: fortsätt på klientsidan med anslutning, mottagna ljudbytes, uppspelningsstart, vald utdataenhet och webbläsarens fel. Påstå inte att TTS fungerade hela vägen till högtalaren.

Prova sju vägar till tystnad

Kör proven i en testmiljö med syntetiska fraser. Använd samma agentversion, samma modellkonfiguration och samma korta text där provet tillåter det. Ett prov ändrar en sak i taget och sparar förväntat utfall före körningen. Det följer arbetsformen i AI-kreatörs guide om testning av AI-genererad kod: kriteriet måste mäta samma sak som provet beställer.

Lägg till ett åttonde lokalt kontrollfall om problemet bara syns i en webbläsare: låt servervägen slutföras men gör utdataenheten otillgänglig eller stoppa uppspelningen i testklienten. Förväntningen är fortfarande att servermåttet och klientobservationen kan säga olika saker. Det är poängen med att inte pressa in uppspelningsfel i tts_error.

Håll tre diagnostikströmmar isär

Turnmetrics är den stabila terminala sammanfattningen. Cloudflare beskriver dessutom typade klienthändelser för STT-fel, anslutningsfel och modellutfall. Fånga dem i separata poster med samma lokala test-id och, när den installerade typdefinitionen faktiskt erbjuder det, samma turnId. Hitta inte på en koppling när ett anslutningsfel inträffar innan någon tur har skapats.

Den tredje strömmen är browser console-diagnostik. Den aktiveras på serversidan för lokal felsökning:

const VoiceAgent = withVoice(Agent, {
  diagnostics: {
    browserConsole: true
  }
});

Cloudflare säger att funktionen är avstängd som standard och att dess händelsenamn och fält kan ändras. Använd den därför för en avgränsad lokal reproduktion, stäng av den efter provet och bygg inga produktionslarm på dess interna namn. Ett enkelt godkännandekriterium är att applikationens permanenta logg fungerar utan browser console-diagnostik.

Cloudflare uppger också att SDK:t tar bort kända innehållsfält och inte läser godtyckliga provider-svar. Det är inte ett frikort för egna feltexter. Ett meddelande som byggs av "TTS failed for " + transcript har redan gjort loggen känslig. Normalisera i stället till egna koder som stt_unavailable, connection_closed eller model_failed och spara högst steg, kod och om felet enligt den typade händelsen kan försökas igen.

Godkänn först när beviset går att läsa baklänges

Välj tre till fem syntetiska testfraser och kör hela matrisen efter varje versionsändring. För varje körning ska en granskare kunna börja i ett rapporterat tyst svar, hitta test-id och turnId, se terminalutfallet, se vilka tidsfält som saknas och därefter öppna rätt separata felström. Rådata ska samtidigt vara oanvändbar för att återskapa vad personen sade eller vad modellen svarade.

Om teamet behöver en bredare metod för att formulera hypotes och ändra en variabel i taget finns den i guiden Felsökning med AI: förstå innan du fixar. Här är stoppregeln mer specifik: uppgradera inte fler röstagentmiljöer förrän matrisen kan skilja modell, TTS, avbrott, anslutning och lokal uppspelning utan att samtalsinnehåll hamnar i loggen.