fix: fix speech to speech model transitions (#545)

* fix: fix transition logic for realtime providers

* chore: run formatter

* chore: generate SDK and fix other realtime providers

* fix: fix ultravox node transitions

api/services/configuration/options/azure.py

@@ -1,6 +1,10 @@
 AZURE_MODELS = ["gpt-4.1-mini"]
 
-AZURE_REALTIME_MODELS = ["gpt-4o-realtime-preview"]
+AZURE_REALTIME_MODELS = [
+    "gpt-realtime",
+    "gpt-realtime-1.5",
+    "gpt-realtime-mini",
+]
 AZURE_REALTIME_VOICES = [
     "alloy",
     "ash",
@@ -12,6 +16,7 @@ AZURE_REALTIME_VOICES = [
     "verse",
 ]
 AZURE_REALTIME_API_VERSIONS = [
+    "v1",
     "2025-04-01-preview",
     "2024-10-01-preview",
     "2024-12-17",

api/services/configuration/registry.py

@@ -621,7 +621,7 @@ class OpenAIRealtimeLLMConfiguration(BaseLLMConfiguration):
 
 
 GROK_REALTIME_MODELS = ["grok-voice-think-fast-1.0"]
-GROK_REALTIME_VOICES = ["Ara", "Rex", "Sal", "Eve", "Leo"]
+GROK_REALTIME_VOICES = ["ara", "rex", "sal", "eve", "leo"]
 ULTRAVOX_REALTIME_MODELS = ["ultravox-v0.7", "fixie-ai/ultravox"]
 
 
@@ -638,7 +638,7 @@ class GrokRealtimeLLMConfiguration(BaseLLMConfiguration):
         },
     )
     voice: str = Field(
-        default="Ara",
+        default="ara",
         description="Voice the model speaks in.",
         json_schema_extra={
             "examples": GROK_REALTIME_VOICES,
@@ -756,7 +756,7 @@ class AzureRealtimeLLMConfiguration(BaseLLMConfiguration):
     model_config = AZURE_REALTIME_PROVIDER_MODEL_CONFIG
     provider: Literal[ServiceProviders.AZURE_REALTIME] = ServiceProviders.AZURE_REALTIME
     model: str = Field(
-        default="gpt-4o-realtime-preview",
+        default="gpt-realtime",
         description="Azure OpenAI realtime deployment name.",
         json_schema_extra={
             "examples": AZURE_REALTIME_MODELS,
@@ -775,8 +775,11 @@ class AzureRealtimeLLMConfiguration(BaseLLMConfiguration):
         },
     )
     api_version: str = Field(
-        default="2025-04-01-preview",
-        description="Azure OpenAI API version.",
+        default="v1",
+        description=(
+            "Azure OpenAI Realtime protocol version. Use 'v1' for the GA API; "
+            "date-based versions select the deprecated preview endpoint."
+        ),
         json_schema_extra={
             "examples": AZURE_REALTIME_API_VERSIONS,
         },

api/services/integrations/paygent/__init__.py

@@ -10,6 +10,7 @@ Provides:
 - ``create_runtime_sessions`` – live-call observer that accumulates usage data
 - ``run_completion`` – post-call REST delivery to the Paygent API
 """
+
 from __future__ import annotations
 
 from api.services.integrations.base import IntegrationPackageSpec

api/services/integrations/paygent/client.py

@@ -5,13 +5,13 @@ coroutine used by the completion handler.  The individual tracker functions
 (session, STT, TTS, LLM, STS, indicator) mirror the exact shape of the
 Paygent REST API documented in ``paygent_sdk/voice_client.py``.
 """
+
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Any
 
 import httpx
-from loguru import logger
 from pydantic import BaseModel, field_validator
 
 _DEFAULT_BASE_URL = "https://cp-api.withpaygent.com"
@@ -169,7 +169,6 @@ async def deliver(
     errors: list[str] = []
 
     async with httpx.AsyncClient(timeout=_REQUEST_TIMEOUT) as client:
-
         # 1. Initialize voice session ----------------------------------------
         try:
             await _post(
@@ -256,8 +255,14 @@ async def deliver(
             metadata = snapshot.sts_usage_metadata or {}
             # Only append connection minutes if we don't already have a rich token payload
             # (e.g. from OpenAI Realtime or Gemini Live)
-            if "connection" not in metadata and "prompt_tokens" not in metadata and "input" not in metadata:
-                metadata["connection"] = {"minutes": snapshot.total_duration_seconds / 60.0}
+            if (
+                "connection" not in metadata
+                and "prompt_tokens" not in metadata
+                and "input" not in metadata
+            ):
+                metadata["connection"] = {
+                    "minutes": snapshot.total_duration_seconds / 60.0
+                }
 
             try:
                 await _post(

api/services/integrations/paygent/collector.py

@@ -10,6 +10,7 @@ Design mirrors ``api/services/integrations/tuner/collector.py`` exactly:
 - Build a serialisable snapshot in ``build_snapshot``
 - Return it from ``on_call_finished`` so it lands in ``workflow_run.logs``
 """
+
 from __future__ import annotations
 
 import time
@@ -43,15 +44,22 @@ def _detect_provider(name: str, fallback: str = "unknown") -> str:
     if "gemini" in clean_name:
         return "google"
     suffixes = [
-        "service", "multimodallive", "realtime",
-        "vertex", "llm", "tts", "stt", "helper", "transport"
+        "service",
+        "multimodallive",
+        "realtime",
+        "vertex",
+        "llm",
+        "tts",
+        "stt",
+        "helper",
+        "transport",
     ]
     changed = True
     while changed:
         changed = False
         for suffix in suffixes:
             if clean_name.endswith(suffix):
-                clean_name = clean_name[:-len(suffix)].rstrip("_").rstrip("-")
+                clean_name = clean_name[: -len(suffix)].rstrip("_").rstrip("-")
                 changed = True
                 break
     return clean_name or fallback
@@ -81,13 +89,13 @@ class _UsageAccumulator:
     call_end_abs_ns: int | None = None
     # STT: timestamp of when user started speaking; None when not speaking
     _user_started_speaking_ns: int | None = field(default=None, repr=False)
-    
+
     @property
     def total_duration_seconds(self) -> int:
         if self.call_end_abs_ns is None:
             return int((time.time_ns() - self.call_start_abs_ns) / 1_000_000_000)
         return int((self.call_end_abs_ns - self.call_start_abs_ns) / 1_000_000_000)
-        
+
     def get_stt_audio_seconds(self) -> float:
         """Return measured STT audio seconds accumulated from the pipeline.
 
@@ -109,7 +117,7 @@ class _UsageAccumulator:
         if not self._has_tts_metrics:
             self._has_tts_metrics = True
             self.tts_characters = 0  # Ignore manual count if metrics emit natively
-        
+
         # Extremely robust extraction
         val = 0
         if isinstance(data, (int, float)):
@@ -120,11 +128,13 @@ class _UsageAccumulator:
             val = getattr(data, "characters", 0) or 0
         elif isinstance(data, dict):
             val = data.get("value") or data.get("characters") or 0
-            
+
         try:
             self.tts_characters += int(val or 0)
         except Exception as exc:
-            logger.warning("[paygent] Failed to accumulate TTS characters (val={!r}): {}", val, exc)
+            logger.warning(
+                "[paygent] Failed to accumulate TTS characters (val={!r}): {}", val, exc
+            )
 
     def add_tts_manual(self, text: str) -> None:
         if not self._has_tts_metrics:
@@ -138,7 +148,9 @@ class _UsageAccumulator:
     def on_user_stopped_speaking(self) -> None:
         """Accumulate the completed utterance duration into stt_audio_seconds."""
         if self._user_started_speaking_ns is not None:
-            elapsed_s = (time.time_ns() - self._user_started_speaking_ns) / 1_000_000_000
+            elapsed_s = (
+                time.time_ns() - self._user_started_speaking_ns
+            ) / 1_000_000_000
             self.stt_audio_seconds += elapsed_s
             self._user_started_speaking_ns = None
 
@@ -162,9 +174,11 @@ def _google_live_usage_to_sts_metadata(usage: Dict[str, Any]) -> Dict[str, Any]:
             return None
         for k in keys:
             if isinstance(obj, dict):
-                if k in obj: return obj[k]
+                if k in obj:
+                    return obj[k]
             else:
-                if hasattr(obj, k): return getattr(obj, k)
+                if hasattr(obj, k):
+                    return getattr(obj, k)
         return None
 
     def _get_list(obj, *keys):
@@ -202,20 +216,36 @@ def _google_live_usage_to_sts_metadata(usage: Dict[str, Any]) -> Dict[str, Any]:
         return total
 
     prompt_details = _get_list(usage, "prompt_tokens_details", "promptTokensDetails")
-    response_details = _get_list(usage, "response_tokens_details", "responseTokensDetails")
-    tool_details = _get_list(usage, "tool_use_prompt_tokens_details", "toolUsePromptTokensDetails")
+    response_details = _get_list(
+        usage, "response_tokens_details", "responseTokensDetails"
+    )
+    tool_details = _get_list(
+        usage, "tool_use_prompt_tokens_details", "toolUsePromptTokensDetails"
+    )
     cache_details = _get_list(usage, "cache_tokens_details", "cacheTokensDetails")
 
     # input side: TEXT + DOCUMENT + AUDIO + IMAGE + VIDEO
-    text_in = _modality_token_count(prompt_details, "TEXT") + _modality_token_count(tool_details, "TEXT")
-    audio_in = _modality_token_count(prompt_details, "AUDIO") + _modality_token_count(tool_details, "AUDIO")
-    image_in = _modality_token_count(prompt_details, "IMAGE") + _modality_token_count(tool_details, "IMAGE")
-    video_in = _modality_token_count(prompt_details, "VIDEO") + _modality_token_count(tool_details, "VIDEO")
-    doc_as_text = _modality_token_count(prompt_details, "DOCUMENT") + _modality_token_count(tool_details, "DOCUMENT")
+    text_in = _modality_token_count(prompt_details, "TEXT") + _modality_token_count(
+        tool_details, "TEXT"
+    )
+    audio_in = _modality_token_count(prompt_details, "AUDIO") + _modality_token_count(
+        tool_details, "AUDIO"
+    )
+    image_in = _modality_token_count(prompt_details, "IMAGE") + _modality_token_count(
+        tool_details, "IMAGE"
+    )
+    video_in = _modality_token_count(prompt_details, "VIDEO") + _modality_token_count(
+        tool_details, "VIDEO"
+    )
+    doc_as_text = _modality_token_count(
+        prompt_details, "DOCUMENT"
+    ) + _modality_token_count(tool_details, "DOCUMENT")
     text_in += doc_as_text
 
     # fallback aggregate mapping
-    tutc = _optional_int(usage, "tool_use_prompt_token_count", "toolUsePromptTokenCount")
+    tutc = _optional_int(
+        usage, "tool_use_prompt_token_count", "toolUsePromptTokenCount"
+    )
     if tutc is not None and not tool_details:
         text_in += int(tutc)
 
@@ -224,8 +254,12 @@ def _google_live_usage_to_sts_metadata(usage: Dict[str, Any]) -> Dict[str, Any]:
         text_in += int(ptc)
 
     # output side: TEXT + DOCUMENT + AUDIO + VIDEO + THINKING
-    text_out = _modality_token_count(response_details, "TEXT") + _modality_token_count(response_details, "DOCUMENT")
-    audio_out = _modality_token_count(response_details, "AUDIO") + _modality_token_count(response_details, "VIDEO")
+    text_out = _modality_token_count(response_details, "TEXT") + _modality_token_count(
+        response_details, "DOCUMENT"
+    )
+    audio_out = _modality_token_count(
+        response_details, "AUDIO"
+    ) + _modality_token_count(response_details, "VIDEO")
 
     rtc = _optional_int(usage, "response_token_count", "responseTokenCount")
     if text_out == 0 and audio_out == 0 and rtc is not None:
@@ -234,35 +268,55 @@ def _google_live_usage_to_sts_metadata(usage: Dict[str, Any]) -> Dict[str, Any]:
 
     # Thinking / reasoning tokens (Gemini 2.5+ thinking models).
     # Emitted as a separate output modality so Paygent has full billing visibility.
-    thinking_tokens = _optional_int(
-        usage,
-        "thoughts_token_count", "thoughtsTokenCount",
-        "thinking_token_count", "thinkingTokenCount",
-    ) or 0
+    thinking_tokens = (
+        _optional_int(
+            usage,
+            "thoughts_token_count",
+            "thoughtsTokenCount",
+            "thinking_token_count",
+            "thinkingTokenCount",
+        )
+        or 0
+    )
 
     # Cache breakdowns
-    cached_text = _modality_token_count(cache_details, "TEXT") + _modality_token_count(cache_details, "DOCUMENT")
-    cached_audio = _modality_token_count(cache_details, "AUDIO") + _modality_token_count(cache_details, "VIDEO")
+    cached_text = _modality_token_count(cache_details, "TEXT") + _modality_token_count(
+        cache_details, "DOCUMENT"
+    )
+    cached_audio = _modality_token_count(
+        cache_details, "AUDIO"
+    ) + _modality_token_count(cache_details, "VIDEO")
     cached_image = _modality_token_count(cache_details, "IMAGE")
-    cached_legacy = _optional_int(usage, "cached_content_token_count", "cachedContentTokenCount")
+    cached_legacy = _optional_int(
+        usage, "cached_content_token_count", "cachedContentTokenCount"
+    )
 
     # Build response payload
     out = {"schemaVersion": 1}
 
     # Input Side
     inp = {}
-    if text_in > 0: inp["text"] = {"tokens": text_in}
-    if audio_in > 0: inp["audio"] = {"tokens": audio_in}
-    if image_in > 0: inp["image"] = {"tokens": image_in}
-    if video_in > 0: inp["video"] = {"tokens": video_in}
-    if inp: out["input"] = inp
+    if text_in > 0:
+        inp["text"] = {"tokens": text_in}
+    if audio_in > 0:
+        inp["audio"] = {"tokens": audio_in}
+    if image_in > 0:
+        inp["image"] = {"tokens": image_in}
+    if video_in > 0:
+        inp["video"] = {"tokens": video_in}
+    if inp:
+        out["input"] = inp
 
     # Output Side
     o = {}
-    if text_out > 0: o["text"] = {"tokens": text_out}
-    if audio_out > 0: o["audio"] = {"tokens": audio_out}
-    if thinking_tokens > 0: o["thinking"] = {"tokens": thinking_tokens}
-    if o: out["output"] = o
+    if text_out > 0:
+        o["text"] = {"tokens": text_out}
+    if audio_out > 0:
+        o["audio"] = {"tokens": audio_out}
+    if thinking_tokens > 0:
+        o["thinking"] = {"tokens": thinking_tokens}
+    if o:
+        out["output"] = o
 
     # Cached breakdown
     has_split = bool(cached_text or cached_audio or cached_image)
@@ -270,15 +324,18 @@ def _google_live_usage_to_sts_metadata(usage: Dict[str, Any]) -> Dict[str, Any]:
         out["cached"] = {"tokens": int(cached_legacy)}
     elif has_split:
         cd = {}
-        if cached_text > 0: cd["text"] = {"tokens": cached_text}
-        if cached_audio > 0: cd["audio"] = {"tokens": cached_audio}
-        if cached_image > 0: cd["image"] = {"tokens": cached_image}
-        if cd: out["cached"] = cd
+        if cached_text > 0:
+            cd["text"] = {"tokens": cached_text}
+        if cached_audio > 0:
+            cd["audio"] = {"tokens": cached_audio}
+        if cached_image > 0:
+            cd["image"] = {"tokens": cached_image}
+        if cd:
+            out["cached"] = cd
 
     return out
 
 
-
 def _openai_realtime_usage_to_sts_metadata(usage: Dict[str, Any]) -> Dict[str, Any]:
     """
     Pure Python translation of OpenAI Realtime usage_metadata to
@@ -292,9 +349,11 @@ def _openai_realtime_usage_to_sts_metadata(usage: Dict[str, Any]) -> Dict[str, A
             return None
         for k in keys:
             if isinstance(obj, dict):
-                if k in obj: return obj[k]
+                if k in obj:
+                    return obj[k]
             else:
-                if hasattr(obj, k): return getattr(obj, k)
+                if hasattr(obj, k):
+                    return getattr(obj, k)
         return None
 
     total_in = int(_get_val(usage, "input_tokens", "inputTokens") or 0)
@@ -307,17 +366,29 @@ def _openai_realtime_usage_to_sts_metadata(usage: Dict[str, Any]) -> Dict[str, A
     text_in = int(_get_val(in_details, "text_tokens", "textTokens") or 0)
     image_in = int(_get_val(in_details, "image_tokens", "imageTokens") or 0)
 
-    cached_total = int(_get_val(usage, "cached_tokens", "cachedTokens") or _get_val(in_details, "cached_tokens", "cachedTokens") or 0)
+    cached_total = int(
+        _get_val(usage, "cached_tokens", "cachedTokens")
+        or _get_val(in_details, "cached_tokens", "cachedTokens")
+        or 0
+    )
 
-    cached_details = _get_val(in_details, "cached_tokens_details", "cachedTokensDetails") or {}
+    cached_details = (
+        _get_val(in_details, "cached_tokens_details", "cachedTokensDetails") or {}
+    )
     cached_audio = int(_get_val(cached_details, "audio_tokens", "audioTokens") or 0)
     cached_text = int(_get_val(cached_details, "text_tokens", "textTokens") or 0)
     cached_image = int(_get_val(cached_details, "image_tokens", "imageTokens") or 0)
 
     if not (cached_audio or cached_text or cached_image):
-        cached_audio = int(_get_val(in_details, "cached_audio_tokens", "cachedAudioTokens") or 0)
-        cached_text = int(_get_val(in_details, "cached_text_tokens", "cachedTextTokens") or 0)
-        cached_image = int(_get_val(in_details, "cached_image_tokens", "cachedImageTokens") or 0)
+        cached_audio = int(
+            _get_val(in_details, "cached_audio_tokens", "cachedAudioTokens") or 0
+        )
+        cached_text = int(
+            _get_val(in_details, "cached_text_tokens", "cachedTextTokens") or 0
+        )
+        cached_image = int(
+            _get_val(in_details, "cached_image_tokens", "cachedImageTokens") or 0
+        )
 
     audio_out = int(_get_val(out_details, "audio_tokens", "audioTokens") or 0)
     text_out = int(_get_val(out_details, "text_tokens", "textTokens") or 0)
@@ -327,25 +398,36 @@ def _openai_realtime_usage_to_sts_metadata(usage: Dict[str, Any]) -> Dict[str, A
 
     out = {"schemaVersion": 1}
     inp = {}
-    if text_in > 0: inp["text"] = {"tokens": text_in}
-    if audio_in > 0: inp["audio"] = {"tokens": audio_in}
-    if image_in > 0: inp["image"] = {"tokens": image_in}
-    if inp: out["input"] = inp
+    if text_in > 0:
+        inp["text"] = {"tokens": text_in}
+    if audio_in > 0:
+        inp["audio"] = {"tokens": audio_in}
+    if image_in > 0:
+        inp["image"] = {"tokens": image_in}
+    if inp:
+        out["input"] = inp
 
     o = {}
-    if text_out > 0: o["text"] = {"tokens": text_out}
-    if audio_out > 0: o["audio"] = {"tokens": audio_out}
-    if o: out["output"] = o
+    if text_out > 0:
+        o["text"] = {"tokens": text_out}
+    if audio_out > 0:
+        o["audio"] = {"tokens": audio_out}
+    if o:
+        out["output"] = o
 
     has_split = bool(cached_text or cached_audio or cached_image)
     if cached_total > 0 and not has_split:
         out["cached"] = {"tokens": int(cached_total)}
     elif has_split:
         cd = {}
-        if cached_text > 0: cd["text"] = {"tokens": cached_text}
-        if cached_audio > 0: cd["audio"] = {"tokens": cached_audio}
-        if cached_image > 0: cd["image"] = {"tokens": cached_image}
-        if cd: out["cached"] = cd
+        if cached_text > 0:
+            cd["text"] = {"tokens": cached_text}
+        if cached_audio > 0:
+            cd["audio"] = {"tokens": cached_audio}
+        if cached_image > 0:
+            cd["image"] = {"tokens": cached_image}
+        if cd:
+            out["cached"] = cd
 
     return out
 
@@ -359,14 +441,18 @@ def _merge_sts_metadata(existing: dict, new: dict) -> dict:
         n_val = new.get(key, {})
         if not e_val and not n_val:
             continue
-        
+
         merged_cat: dict = {}
 
         # Prefer per-modality merge when either side has per-modality detail.
         # Only use the flat aggregate{"tokens": N} form when neither side has
         # any per-modality breakdown at all (e.g. legacy schema).
-        e_has_modalities = any(m in e_val for m in ("text", "audio", "image", "video", "thinking"))
-        n_has_modalities = any(m in n_val for m in ("text", "audio", "image", "video", "thinking"))
+        e_has_modalities = any(
+            m in e_val for m in ("text", "audio", "image", "video", "thinking")
+        )
+        n_has_modalities = any(
+            m in n_val for m in ("text", "audio", "image", "video", "thinking")
+        )
 
         if e_has_modalities or n_has_modalities:
             for modality in ("text", "audio", "image", "video", "thinking"):
@@ -388,20 +474,25 @@ def _merge_sts_metadata(existing: dict, new: dict) -> dict:
 
         if merged_cat:
             out[key] = merged_cat
-            
+
     # retain any other keys, summing up numeric ones to keep metadata consistent
     for k, v in existing.items():
         if k not in ("schemaVersion", "input", "output", "cached"):
             out[k] = v
     for k, v in new.items():
         if k not in ("schemaVersion", "input", "output", "cached"):
-            if k in out and isinstance(out[k], (int, float)) and isinstance(v, (int, float)):
+            if (
+                k in out
+                and isinstance(out[k], (int, float))
+                and isinstance(v, (int, float))
+            ):
                 out[k] = out[k] + v
             else:
                 out[k] = v
-            
+
     return out
 
+
 class PaygentCollector(BaseObserver):
     """Pipecat observer that accumulates usage data for a single call.
 
@@ -514,37 +605,65 @@ class PaygentCollector(BaseObserver):
                         if is_sts_frame:
                             # Normalise the raw provider slug so that variants like
                             # "openai_realtime", "azure_realtime", etc. route correctly.
-                            raw_provider = (
-                                getattr(self, "_sts_provider", "") or getattr(self, "_llm_provider", "")
+                            raw_provider = getattr(
+                                self, "_sts_provider", ""
+                            ) or getattr(self, "_llm_provider", "")
+                            provider = (
+                                _detect_provider(raw_provider)
+                                if raw_provider
+                                else "unknown"
                             )
-                            provider = _detect_provider(raw_provider) if raw_provider else "unknown"
                             if provider not in ("grok", "ultravox"):
                                 usage = item.value
-                                raw_metadata = getattr(usage, "raw_usage_metadata", None)
+                                raw_metadata = getattr(
+                                    usage, "raw_usage_metadata", None
+                                )
                                 if raw_metadata:
                                     # OpenAI Realtime and Azure Realtime (azure→openai via _detect_provider)
                                     # share the same wire format.
                                     if provider in ("openai", "azure"):
-                                        new_meta = _openai_realtime_usage_to_sts_metadata(raw_metadata)
+                                        new_meta = (
+                                            _openai_realtime_usage_to_sts_metadata(
+                                                raw_metadata
+                                            )
+                                        )
                                     else:
-                                        new_meta = _google_live_usage_to_sts_metadata(raw_metadata)
+                                        new_meta = _google_live_usage_to_sts_metadata(
+                                            raw_metadata
+                                        )
                                 else:
-                                    prompt_tokens = getattr(usage, "prompt_tokens", 0) or 0
-                                    completion_tokens = getattr(usage, "completion_tokens", 0) or 0
-                                    cached_tokens = (getattr(usage, "cache_read_input_tokens", 0) or getattr(usage, "cached_tokens", 0) or 0)
+                                    prompt_tokens = (
+                                        getattr(usage, "prompt_tokens", 0) or 0
+                                    )
+                                    completion_tokens = (
+                                        getattr(usage, "completion_tokens", 0) or 0
+                                    )
+                                    cached_tokens = (
+                                        getattr(usage, "cache_read_input_tokens", 0)
+                                        or getattr(usage, "cached_tokens", 0)
+                                        or 0
+                                    )
                                     new_meta = {"schemaVersion": 1}
                                     if prompt_tokens > 0:
-                                        new_meta.setdefault("input", {})["text"] = {"tokens": prompt_tokens}
+                                        new_meta.setdefault("input", {})["text"] = {
+                                            "tokens": prompt_tokens
+                                        }
                                     if completion_tokens > 0:
-                                        new_meta.setdefault("output", {})["text"] = {"tokens": completion_tokens}
+                                        new_meta.setdefault("output", {})["text"] = {
+                                            "tokens": completion_tokens
+                                        }
                                     if cached_tokens > 0:
                                         new_meta["cached"] = {"tokens": cached_tokens}
-                                    
+
                                     if hasattr(usage, "__dict__"):
                                         for k, v in vars(usage).items():
-                                            if not k.startswith("_") and v is not None and k not in new_meta:
+                                            if (
+                                                not k.startswith("_")
+                                                and v is not None
+                                                and k not in new_meta
+                                            ):
                                                 new_meta[k] = v
-                                
+
                                 self._acc.sts_usage_metadata = _merge_sts_metadata(
                                     self._acc.sts_usage_metadata or {}, new_meta
                                 )
@@ -579,5 +698,7 @@ class PaygentCollector(BaseObserver):
         except Exception as exc:
             logger.warning(
                 "[paygent] Unexpected error processing frame {!r} in collector: {}",
-                type(data.frame).__name__, exc, exc_info=True,
+                type(data.frame).__name__,
+                exc,
+                exc_info=True,
             )

api/services/integrations/paygent/completion.py

@@ -12,6 +12,7 @@ Mirrors ``tuner/completion.py`` exactly:
 - call ``deliver(config, snapshot)``
 - collect results keyed by ``paygent_{node_id}``
 """
+
 from __future__ import annotations
 
 from datetime import UTC, datetime
@@ -38,8 +39,8 @@ def _build_snapshot(
         # snapshot value is never used to override it, preventing billing drift
         # if the log is stale or corrupted.
         session_id=str(workflow_run_id),
-        agent_id=raw.get("agent_id", ""),          # filled from node config below
-        customer_id=raw.get("customer_id", ""),    # filled from node config below
+        agent_id=raw.get("agent_id", ""),  # filled from node config below
+        customer_id=raw.get("customer_id", ""),  # filled from node config below
         is_realtime=raw.get("is_realtime", False),
         stt_provider=raw.get("stt_provider", ""),
         stt_model=raw.get("stt_model", ""),
@@ -90,7 +91,9 @@ async def run_completion(
             continue
 
         # ---- Build typed objects -------------------------------------------
-        snapshot = _build_snapshot(raw_snapshot, workflow_run_id=context.workflow_run_id)
+        snapshot = _build_snapshot(
+            raw_snapshot, workflow_run_id=context.workflow_run_id
+        )
         # Inject node-level credentials into the snapshot
         snapshot.agent_id = (node_data.paygent_agent_id or "").strip()
         snapshot.customer_id = (node_data.paygent_customer_id or "").strip()
@@ -102,7 +105,11 @@ async def run_completion(
             # Only fallback to pipeline-level llm usage if this is NOT a realtime pipeline.
             # In realtime pipelines, the collector properly segregates STS and LLM tokens;
             # falling back here would duplicate the STS tokens into the LLM bucket.
-            if snapshot.llm_prompt_tokens == 0 and snapshot.llm_completion_tokens == 0 and not snapshot.is_realtime:
+            if (
+                snapshot.llm_prompt_tokens == 0
+                and snapshot.llm_completion_tokens == 0
+                and not snapshot.is_realtime
+            ):
                 llm_providers: list[str] = []
                 llm_models: list[str] = []
                 for key, val in usage_info.get("llm", {}).items():
@@ -112,7 +119,9 @@ async def run_completion(
                         continue
                     snapshot.llm_prompt_tokens += val.get("prompt_tokens", 0)
                     snapshot.llm_completion_tokens += val.get("completion_tokens", 0)
-                    snapshot.llm_cached_tokens += val.get("cache_read_input_tokens", 0) + val.get("cache_creation_input_tokens", 0)
+                    snapshot.llm_cached_tokens += val.get(
+                        "cache_read_input_tokens", 0
+                    ) + val.get("cache_creation_input_tokens", 0)
                     parts = key.split("|||")
                     if len(parts) == 2:
                         llm_providers.append(parts[0])
@@ -153,7 +162,11 @@ async def run_completion(
                 # substitute total_duration_seconds — that would overbill wall-clock time
                 # (silence, hold, agent speech) as STT input.
         except Exception as exc:
-            logger.warning("[paygent] Failed to apply usage_info fallback for run {}: {}", context.workflow_run_id, exc)
+            logger.warning(
+                "[paygent] Failed to apply usage_info fallback for run {}: {}",
+                context.workflow_run_id,
+                exc,
+            )
 
         try:
             config = PaygentDeliveryConfig(

api/services/integrations/paygent/runtime.py

@@ -12,11 +12,11 @@ Lifecycle:
      integration framework, which persists it in ``workflow_run.logs`` under
      the key ``"paygent_snapshot"``.
 """
+
 from __future__ import annotations
 
 from typing import Any
 
-from api.services.configuration.registry import ServiceProviders
 from api.services.integrations.base import (
     IntegrationRuntimeContext,
     IntegrationRuntimeSession,
@@ -48,12 +48,12 @@ def _resolve_model_labels(
         llm_provider = getattr(user_config.llm, "provider", "") or ""
         llm_model = getattr(user_config.llm, "model", "") or ""
         return (
-            "",              # stt_provider  (no separate STT in realtime)
-            "",              # stt_model
+            "",  # stt_provider  (no separate STT in realtime)
+            "",  # stt_model
             llm_provider,
             llm_model,
-            "",              # tts_provider  (no separate TTS in realtime)
-            "",              # tts_model
+            "",  # tts_provider  (no separate TTS in realtime)
+            "",  # tts_model
             realtime_provider,
             realtime_model,
         )
@@ -90,9 +90,7 @@ class PaygentRuntimeSession(IntegrationRuntimeSession):
         gathered_context: dict[str, Any],
     ) -> dict[str, Any] | None:
         """Seal the snapshot and hand it to the framework for persistence."""
-        self._collector.set_call_disposition(
-            gathered_context.get("call_disposition")
-        )
+        self._collector.set_call_disposition(gathered_context.get("call_disposition"))
         snapshot = self._collector.build_snapshot()
         return {"paygent_snapshot": snapshot}
 
@@ -109,8 +107,7 @@ def create_runtime_sessions(
     paygent_nodes = [
         node
         for node in context.workflow_graph.nodes.values()
-        if node.node_type == "paygent"
-        and getattr(node.data, "paygent_enabled", True)
+        if node.node_type == "paygent" and getattr(node.data, "paygent_enabled", True)
     ]
     if not paygent_nodes:
         return []

api/services/pipecat/realtime/azure_realtime.py

@@ -1,9 +1,9 @@
 """Dograh subclass of pipecat's Azure OpenAI Realtime LLM service.
 
 Layers Dograh engine integration quirks (mute gating, TTSSpeakFrame greeting
-trigger, LLMMessagesAppendFrame handling, deferred tool calls) onto pipecat's
-AzureRealtimeLLMService, mirroring what DograhOpenAIRealtimeLLMService does
-for the standard OpenAI Realtime endpoint.
+trigger, LLMMessagesAppendFrame handling, workflow-control deferral) onto
+pipecat's AzureRealtimeLLMService, mirroring what
+DograhOpenAIRealtimeLLMService does for the standard OpenAI Realtime endpoint.
 """
 
 import json
@@ -40,7 +40,7 @@ class DograhAzureRealtimeLLMService(AzureRealtimeLLMService):
     - User-mute audio gating
     - TTSSpeakFrame as initial-response trigger
     - One-off LLMMessagesAppendFrame handling
-    - Deferred tool calls until bot finishes speaking
+    - Workflow-control calls deferred until bot finishes speaking
     - finalized=True on TranscriptionFrame for consistency
     """
 
@@ -49,7 +49,7 @@ class DograhAzureRealtimeLLMService(AzureRealtimeLLMService):
         self._user_is_muted: bool = False
         self._handled_initial_context: bool = False
         self._bot_is_speaking: bool = False
-        self._deferred_function_calls: list[FunctionCallFromLLM] = []
+        self._deferred_node_transition_function_calls: list[FunctionCallFromLLM] = []
         self._pending_initial_greeting_text: str | None = None
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
@@ -81,7 +81,7 @@ class DograhAzureRealtimeLLMService(AzureRealtimeLLMService):
             self._bot_is_speaking = True
         elif isinstance(frame, BotStoppedSpeakingFrame):
             self._bot_is_speaking = False
-            await self._run_pending_function_calls()
+            await self._run_pending_node_transition_function_calls()
         await super().process_frame(frame, direction)
 
     async def _handle_messages_append(self, frame: LLMMessagesAppendFrame):
@@ -247,18 +247,19 @@ class DograhAzureRealtimeLLMService(AzureRealtimeLLMService):
             )
         )
 
-    async def _run_pending_function_calls(self):
-        if not self._deferred_function_calls:
+    async def _run_pending_node_transition_function_calls(self):
+        if not self._deferred_node_transition_function_calls:
             return
-        function_calls = self._deferred_function_calls
-        self._deferred_function_calls = []
+        function_calls = self._deferred_node_transition_function_calls
+        self._deferred_node_transition_function_calls = []
         logger.debug(
-            f"{self}: executing {len(function_calls)} deferred function call(s) "
-            "after bot turn ended"
+            f"{self}: executing {len(function_calls)} deferred workflow-control "
+            "call(s) after bot turn ended"
         )
         await self.run_function_calls(function_calls)
 
     async def _handle_evt_function_call_arguments_done(self, evt):
+        """Run ordinary tools immediately and defer workflow-control calls."""
         try:
             args = json.loads(evt.arguments)
 
@@ -275,10 +276,14 @@ class DograhAzureRealtimeLLMService(AzureRealtimeLLMService):
                     )
                 ]
 
-                if self._bot_is_speaking:
-                    self._deferred_function_calls.extend(function_calls)
+                is_node_transition = self._function_is_node_transition(
+                    function_call_item.name
+                )
+                if self._bot_is_speaking and is_node_transition:
+                    self._deferred_node_transition_function_calls.extend(function_calls)
                     logger.debug(
-                        f"{self}: deferring function call {function_call_item.name} "
+                        f"{self}: deferring workflow-control call "
+                        f"{function_call_item.name} "
                         "until bot stops speaking"
                     )
                 else:

api/services/pipecat/realtime/gemini_live.py

@@ -9,8 +9,8 @@ Layers Dograh engine integration quirks onto upstream-pristine
 - **Reconnect on node transitions.** Gemini Live cannot update
   ``system_instruction`` mid-session, so a setting change triggers a
   reconnect (deferred until the bot turn ends if currently responding).
-- **Function-call deferral.** Tool calls emitted mid-turn are queued and run
-  when the bot stops speaking, to avoid racing the turn's audio.
+- **Node-transition deferral.** Node-transition calls emitted mid-turn are
+  queued and run when the bot stops speaking, to avoid cutting off its audio.
 - **User-mute audio gating.** ``UserMuteStarted/StoppedFrame`` from the
   user aggregator gates whether incoming audio is forwarded to Gemini.
 - **TTSSpeakFrame as greeting trigger.** The engine queues a TTSSpeakFrame
@@ -18,6 +18,7 @@ Layers Dograh engine integration quirks onto upstream-pristine
   it and runs the initial-context path.
 """
 
+import asyncio
 from typing import Any
 
 from google.genai.types import Content, Part
@@ -44,6 +45,11 @@ from pipecat.utils.tracing.service_decorators import traced_gemini_live
 class DograhGeminiLiveLLMService(GeminiLiveLLMService):
     """Gemini Live with Dograh engine integration quirks. See module docstring."""
 
+    # Gemini input transcription is delivered independently from tool calls.
+    # Give late transcription messages a small window to arrive before running
+    # a node-transition function and tearing down the current Live connection.
+    _NODE_TRANSITION_TRANSCRIPTION_GRACE_SECONDS = 0.5
+
     # Route tool schemas through Gemini's ``parameters_json_schema`` field so
     # MCP/imported tools that use JSON Schema keywords (``const``, ``not``,
     # nested ``anyOf``) rejected by the strict ``Schema`` model are accepted.
@@ -59,15 +65,19 @@ class DograhGeminiLiveLLMService(GeminiLiveLLMService):
         # Guards initial-response triggering against double-firing across the
         # initial TTSSpeakFrame and any LLMContextFrame that may arrive.
         self._handled_initial_context: bool = False
-        # When a system_instruction change arrives mid-bot-turn, the reconnect
-        # is queued and drained when the turn ends.
-        self._reconnect_pending: bool = False
-        # Function calls emitted by Gemini mid-bot-turn are deferred here and
-        # invoked when the turn ends, so they don't race the turn's audio.
-        self._pending_function_calls: list[FunctionCallFromLLM] = []
+        # Node-transition calls emitted mid-bot-turn are deferred here so the
+        # transition does not tear down Gemini while it is still producing audio.
+        self._pending_node_transition_function_calls: list[FunctionCallFromLLM] = []
         # Text greeting captured from the first TTSSpeakFrame while the Gemini
         # session is still connecting.
         self._pending_initial_greeting_text: str | None = None
+        self._transition_function_call_task: asyncio.Task | None = None
+        # Intentional node changes use a fresh, context-seeded connection rather
+        # than a potentially stale session-resumption handle. The new connection
+        # remains gated until the function-call result has landed in LLMContext.
+        self._awaiting_node_transition_context: bool = False
+        self._node_transition_context_received: bool = False
+        self._node_transition_context_seed_started: bool = False
 
     # ------------------------------------------------------------------
     # Hooks from upstream GeminiLiveLLMService
@@ -78,33 +88,109 @@ class DograhGeminiLiveLLMService(GeminiLiveLLMService):
         # lets pre-call fetch populate template variables first.
         return bool(self._settings.system_instruction)
 
+    def _requires_node_transition_context_aggregation(self) -> bool:
+        # A node transition replaces the current Gemini Live connection and
+        # seeds the new one from our local LLMContext. Wait for the upstream
+        # user aggregator to commit any final TranscriptionFrame before
+        # set_node() changes the prompt and starts that reconnect.
+        return True
+
+    async def cleanup(self) -> None:
+        """Cancel a delayed transition before tearing down the Live session."""
+        if self._transition_function_call_task:
+            await self.cancel_task(self._transition_function_call_task)
+            self._transition_function_call_task = None
+        await super().cleanup()
+
     async def _handle_changed_settings(self, changed: dict[str, Any]) -> set[str]:
         if "system_instruction" not in changed:
             return set()
+
+        # PipecatEngine updates system_instruction only from set_node(). The
+        # first set_node happens before a Live session exists; every later one
+        # is a node transition whose tool call has already been deferred until
+        # the current bot turn finishes.
         if not self._session:
             # First-time setting after deferred-connect.
             await self._connect()
-        elif self._bot_is_responding:
-            # Bot is mid-turn — drain the reconnect when it ends so we don't
-            # cut the bot off mid-utterance.
-            self._reconnect_pending = True
         else:
-            await self._reconnect()
+            await self._reconnect_for_node_transition()
         return {"system_instruction"}
 
     async def _run_or_defer_function_calls(
         self, function_calls_llm: list[FunctionCallFromLLM]
     ):
+        if not self._contains_node_transition(function_calls_llm):
+            await super()._run_or_defer_function_calls(function_calls_llm)
+            return
+
+        # Keep a provider tool-call batch together. Splitting a mixed batch here
+        # would discard Pipecat's shared function-call group and could trigger an
+        # LLM run before every result from the original batch has arrived.
         if self._bot_is_responding:
             # Latest batch wins; Gemini emits tool calls as one batch per
             # tool_call message, so this overwrite is intentional.
-            self._pending_function_calls = function_calls_llm
+            self._pending_node_transition_function_calls = function_calls_llm
             logger.debug(
-                f"{self}: deferring {len(function_calls_llm)} function call(s) "
+                f"{self}: deferring {len(function_calls_llm)} node-transition "
+                "function call(s) "
                 "until bot turn ends"
             )
             return
-        await super()._run_or_defer_function_calls(function_calls_llm)
+
+        self._schedule_node_transition_function_calls(function_calls_llm)
+
+    def _contains_node_transition(
+        self, function_calls_llm: list[FunctionCallFromLLM]
+    ) -> bool:
+        return any(self._is_node_transition(fc) for fc in function_calls_llm)
+
+    def _is_node_transition(self, function_call: FunctionCallFromLLM) -> bool:
+        return self._function_is_node_transition(function_call.function_name)
+
+    def _schedule_node_transition_function_calls(
+        self, function_calls_llm: list[FunctionCallFromLLM]
+    ) -> None:
+        """Run transition calls after late input transcription has settled."""
+        if (
+            self._transition_function_call_task
+            and not self._transition_function_call_task.done()
+        ):
+            logger.warning(
+                f"{self}: node-transition function call already pending; "
+                "ignoring duplicate batch"
+            )
+            return
+
+        async def _run_after_transcription_grace() -> None:
+            try:
+                await asyncio.sleep(self._NODE_TRANSITION_TRANSCRIPTION_GRACE_SECONDS)
+                await self._flush_pending_user_transcription()
+                await self.run_function_calls(function_calls_llm)
+            finally:
+                self._transition_function_call_task = None
+
+        self._transition_function_call_task = self.create_task(
+            _run_after_transcription_grace(),
+            name=f"{self}::node-transition-function-calls",
+        )
+
+    async def _flush_pending_user_transcription(self) -> None:
+        """Publish any punctuationless user transcript before a node handoff."""
+        if self._transcription_timeout_task:
+            if not self._transcription_timeout_task.done():
+                await self.cancel_task(self._transcription_timeout_task)
+            self._transcription_timeout_task = None
+
+        if not self._user_transcription_buffer:
+            return
+
+        text = self._user_transcription_buffer
+        self._user_transcription_buffer = ""
+        logger.debug(
+            f"{self}: flushing pending user transcription before node transition"
+        )
+        await self._push_user_transcription(text, result=None)
 
     # ------------------------------------------------------------------
     # State-transition side effects
@@ -114,22 +200,35 @@ class DograhGeminiLiveLLMService(GeminiLiveLLMService):
         was_responding = self._bot_is_responding
         await super()._set_bot_is_responding(responding)
         if was_responding and not responding:
-            await self._run_pending_function_calls()
-            if self._reconnect_pending:
-                self._reconnect_pending = False
-                await self._reconnect()
+            await self._run_pending_node_transition_function_calls()
 
-    async def _run_pending_function_calls(self):
-        """Run any function calls deferred during the bot's last turn."""
-        if not self._pending_function_calls:
+    async def _run_pending_node_transition_function_calls(self):
+        """Run any node-transition calls deferred during the bot's last turn."""
+        if not self._pending_node_transition_function_calls:
             return
-        fcs = self._pending_function_calls
-        self._pending_function_calls = []
+        fcs = self._pending_node_transition_function_calls
+        self._pending_node_transition_function_calls = []
         logger.debug(
-            f"{self}: executing {len(fcs)} deferred function call(s) "
+            f"{self}: executing {len(fcs)} deferred node-transition call(s) "
             "after bot turn ended"
         )
-        await self.run_function_calls(fcs)
+        self._schedule_node_transition_function_calls(fcs)
+
+    async def _reconnect_for_node_transition(self) -> None:
+        """Start a fresh connection and wait to seed the completed context.
+
+        Gemini can report ``resumable=False`` while generating or executing a
+        function call. A workflow transition happens at exactly that boundary,
+        so using the last (older) resumption handle can omit the triggering user
+        turn. Use the local LLMContext as the source of truth for this intentional
+        handoff instead.
+        """
+        self._awaiting_node_transition_context = True
+        self._node_transition_context_received = False
+        self._node_transition_context_seed_started = False
+        self._session_resumption_handle = None
+        await self._disconnect()
+        await self._connect(session_resumption_handle=None)
 
     # ------------------------------------------------------------------
     # Frame handling: mute, TTSSpeakFrame, BotStoppedSpeakingFrame flush
@@ -165,9 +264,9 @@ class DograhGeminiLiveLLMService(GeminiLiveLLMService):
         if isinstance(frame, BotStoppedSpeakingFrame):
             # Belt-and-suspenders: the main drain happens in
             # _set_bot_is_responding(False), but if Gemini delays turn_complete
-            # past the audible end of the turn, flushing here ensures pending
-            # function calls fire promptly.
-            await self._run_pending_function_calls()
+            # past the audible end of the turn, flushing here ensures a pending
+            # node transition fires promptly.
+            await self._run_pending_node_transition_function_calls()
             # Fall through to super for the actual push.
         await super().process_frame(frame, direction)
 
@@ -185,6 +284,11 @@ class DograhGeminiLiveLLMService(GeminiLiveLLMService):
     # ------------------------------------------------------------------
 
     async def _handle_context(self, context: LLMContext):
+        if self._awaiting_node_transition_context:
+            self._context = context
+            self._node_transition_context_received = True
+            await self._maybe_seed_node_transition_context()
+            return
         if not self._handled_initial_context:
             self._handled_initial_context = True
             self._context = context
@@ -249,6 +353,12 @@ class DograhGeminiLiveLLMService(GeminiLiveLLMService):
             f"In _handle_session_ready self._run_llm_when_session_ready: {self._run_llm_when_session_ready}"
         )
         self._session = session
+        if self._awaiting_node_transition_context:
+            # Do not accept realtime input until the function-call result frame
+            # has updated the shared context and that complete history is seeded.
+            self._ready_for_realtime_input = False
+            await self._maybe_seed_node_transition_context()
+            return
         self._ready_for_realtime_input = True
         if self._run_llm_when_session_ready:
             # Context arrived before session was ready — fulfil the queued
@@ -266,3 +376,25 @@ class DograhGeminiLiveLLMService(GeminiLiveLLMService):
         # a handle (e.g. node transitions before any handle was issued) are
         # followed by a function-call-result LLMContextFrame which feeds the
         # updated-context branch in _handle_context.
+
+    async def _maybe_seed_node_transition_context(self) -> None:
+        if (
+            not self._awaiting_node_transition_context
+            or not self._node_transition_context_received
+            or not self._session
+            or self._node_transition_context_seed_started
+        ):
+            return
+
+        self._node_transition_context_seed_started = True
+        try:
+            # The complete tool result is already present in the history being
+            # seeded, so mark it delivered locally instead of sending a provider
+            # tool response for a call that the fresh session never issued.
+            await self._process_completed_function_calls(send_new_results=False)
+            await self._create_initial_response()
+            self._awaiting_node_transition_context = False
+            self._node_transition_context_received = False
+            await self._drain_pending_tool_results()
+        finally:
+            self._node_transition_context_seed_started = False

api/services/pipecat/realtime/grok_realtime.py

@@ -11,8 +11,9 @@ Adds:
   flow kicks off the bot's first response.
 - **One-off LLMMessagesAppendFrame handling** for ephemeral realtime prompts
   like user-idle checks, without mutating Dograh's local ``LLMContext``.
-- **Function-call deferral** until the bot finishes speaking, to avoid racing
-  tool execution with the active audio turn.
+- **Workflow-control deferral** so node transitions, call termination, and
+  transfers wait for any current bot audio to finish while ordinary tools run
+  immediately.
 - **finalized=True on TranscriptionFrame** for parity with Dograh's other
   realtime providers.
 """
@@ -50,7 +51,7 @@ class DograhGrokRealtimeLLMService(GrokRealtimeLLMService):
         self._user_is_muted: bool = False
         self._handled_initial_context: bool = False
         self._bot_is_speaking: bool = False
-        self._deferred_function_calls: list[FunctionCallFromLLM] = []
+        self._deferred_node_transition_function_calls: list[FunctionCallFromLLM] = []
         self._pending_initial_greeting_text: str | None = None
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
@@ -82,7 +83,7 @@ class DograhGrokRealtimeLLMService(GrokRealtimeLLMService):
             self._bot_is_speaking = True
         elif isinstance(frame, BotStoppedSpeakingFrame):
             self._bot_is_speaking = False
-            await self._run_pending_function_calls()
+            await self._run_pending_node_transition_function_calls()
         await super().process_frame(frame, direction)
 
     async def _handle_messages_append(self, frame: LLMMessagesAppendFrame):
@@ -251,19 +252,19 @@ class DograhGrokRealtimeLLMService(GrokRealtimeLLMService):
             )
         )
 
-    async def _run_pending_function_calls(self):
-        if not self._deferred_function_calls:
+    async def _run_pending_node_transition_function_calls(self):
+        if not self._deferred_node_transition_function_calls:
             return
-        function_calls = self._deferred_function_calls
-        self._deferred_function_calls = []
+        function_calls = self._deferred_node_transition_function_calls
+        self._deferred_node_transition_function_calls = []
         logger.debug(
-            f"{self}: executing {len(function_calls)} deferred function call(s) "
-            "after bot turn ended"
+            f"{self}: executing {len(function_calls)} deferred workflow-control "
+            "call(s) after bot turn ended"
         )
         await self.run_function_calls(function_calls)
 
     async def _handle_evt_function_call_arguments_done(self, evt):
-        """Process or defer tool calls until the bot finishes speaking."""
+        """Run ordinary tools immediately and defer workflow-control calls."""
         try:
             args = json.loads(evt.arguments)
 
@@ -281,10 +282,11 @@ class DograhGrokRealtimeLLMService(GrokRealtimeLLMService):
                     )
                 ]
 
-                if self._bot_is_speaking:
-                    self._deferred_function_calls.extend(function_calls)
+                is_node_transition = self._function_is_node_transition(function_name)
+                if self._bot_is_speaking and is_node_transition:
+                    self._deferred_node_transition_function_calls.extend(function_calls)
                     logger.debug(
-                        f"{self}: deferring function call {function_name} "
+                        f"{self}: deferring workflow-control call {function_name} "
                         "until bot stops speaking"
                     )
                 else:

api/services/pipecat/realtime/openai_realtime.py

@@ -3,8 +3,8 @@
 Layers Dograh engine integration quirks onto upstream-pristine
 :class:`OpenAIRealtimeLLMService`. Substantially smaller than the Gemini
 subclass because OpenAI Realtime supports runtime ``session.update`` for
-both ``system_instruction`` and tools — no reconnect/defer-tool-call
-machinery needed.
+both ``system_instruction`` and tools, so node changes do not require a
+reconnect.
 
 Adds:
 
@@ -13,6 +13,9 @@ Adds:
   flow kicks off the bot's first response.
 - **One-off LLMMessagesAppendFrame handling** for ephemeral realtime prompts
   like user-idle checks, without mutating Dograh's local ``LLMContext``.
+- **Workflow-control deferral** so node transitions, call termination, and
+  transfers wait for any current bot audio to finish while ordinary tools run
+  immediately.
 - **finalized=True on TranscriptionFrame** because every OpenAI
   transcription via the ``completed`` event is final by construction.
 """
@@ -53,10 +56,10 @@ class DograhOpenAIRealtimeLLMService(OpenAIRealtimeLLMService):
         # LLMContextFrame arrives, so upstream's "first arrival means
         # self._context is None" check no longer works.
         self._handled_initial_context: bool = False
-        # Track bot speech locally so tool calls can be deferred until the bot
-        # has finished speaking, matching Dograh's Gemini Live behavior.
+        # Track bot speech locally so workflow-control calls can wait until the
+        # bot has finished speaking without delaying ordinary tools.
         self._bot_is_speaking: bool = False
-        self._deferred_function_calls: list[FunctionCallFromLLM] = []
+        self._deferred_node_transition_function_calls: list[FunctionCallFromLLM] = []
         self._pending_initial_greeting_text: str | None = None
 
     # ------------------------------------------------------------------
@@ -100,7 +103,7 @@ class DograhOpenAIRealtimeLLMService(OpenAIRealtimeLLMService):
             self._bot_is_speaking = True
         elif isinstance(frame, BotStoppedSpeakingFrame):
             self._bot_is_speaking = False
-            await self._run_pending_function_calls()
+            await self._run_pending_node_transition_function_calls()
         await super().process_frame(frame, direction)
 
     async def _handle_messages_append(self, frame: LLMMessagesAppendFrame):
@@ -268,19 +271,19 @@ class DograhOpenAIRealtimeLLMService(OpenAIRealtimeLLMService):
             )
         )
 
-    async def _run_pending_function_calls(self):
-        if not self._deferred_function_calls:
+    async def _run_pending_node_transition_function_calls(self):
+        if not self._deferred_node_transition_function_calls:
             return
-        function_calls = self._deferred_function_calls
-        self._deferred_function_calls = []
+        function_calls = self._deferred_node_transition_function_calls
+        self._deferred_node_transition_function_calls = []
         logger.debug(
-            f"{self}: executing {len(function_calls)} deferred function call(s) "
-            "after bot turn ended"
+            f"{self}: executing {len(function_calls)} deferred workflow-control "
+            "call(s) after bot turn ended"
         )
         await self.run_function_calls(function_calls)
 
     async def _handle_evt_function_call_arguments_done(self, evt):
-        """Process or defer tool calls until the bot finishes speaking."""
+        """Run ordinary tools immediately and defer workflow-control calls."""
         try:
             args = json.loads(evt.arguments)
 
@@ -297,10 +300,14 @@ class DograhOpenAIRealtimeLLMService(OpenAIRealtimeLLMService):
                     )
                 ]
 
-                if self._bot_is_speaking:
-                    self._deferred_function_calls.extend(function_calls)
+                is_node_transition = self._function_is_node_transition(
+                    function_call_item.name
+                )
+                if self._bot_is_speaking and is_node_transition:
+                    self._deferred_node_transition_function_calls.extend(function_calls)
                     logger.debug(
-                        f"{self}: deferring function call {function_call_item.name} "
+                        f"{self}: deferring workflow-control call "
+                        f"{function_call_item.name} "
                         "until bot stops speaking"
                     )
                 else:

api/services/pipecat/realtime/ultravox_realtime.py

@@ -1,19 +1,17 @@
 """Dograh subclass of pipecat's Ultravox realtime LLM service.
 
-Ultravox is audio-native and realtime, but prompt and tool configuration is
-bound to call creation. Dograh therefore cannot lean on in-session updates or
-Gemini-style session resumption handles. This wrapper adapts Ultravox to the
-Dograh engine contract by:
+Ultravox is audio-native and realtime. Its native call stages allow a client
+tool result to atomically change the system prompt and tools while preserving
+the call's server-side conversation history. This wrapper adapts that model to
+the Dograh engine contract by:
 
 - deferring the first call creation until the engine queues the initial node
   opening via ``TTSSpeakFrame`` or ``LLMContextFrame``
-- marking the call for recreation when ``system_instruction`` changes across
-  node transitions, then rebuilding it on the follow-up ``LLMContextFrame``
-  so the transition tool result is present in ``initialMessages``
-- reconstructing Ultravox ``initialMessages`` from Dograh context when the
-  call must be recreated after a node transition
-- appending a transient resumptive user nudge to recreated ``initialMessages``
-  after tool-result transitions, without mutating Dograh's stored context
+- returning node-transition tool results with ``responseType="new-stage"`` so
+  the existing call keeps its complete audio-native history
+- updating the next stage's system prompt and selected tools without a
+  disconnect/reconnect cycle
+- deferring workflow-control tools until any active Ultravox response ends
 - handling Dograh-only frames such as user mute and idle append prompts
 - tagging user transcripts with ``finalized=True`` for downstream parity
 """
@@ -34,12 +32,7 @@ from pipecat.frames.frames import (
     UserMuteStartedFrame,
     UserMuteStoppedFrame,
 )
-from pipecat.processors.aggregators import async_tool_messages
-from pipecat.processors.aggregators.llm_context import (
-    LLMContext,
-    LLMSpecificMessage,
-    is_given,
-)
+from pipecat.processors.aggregators.llm_context import LLMContext, is_given
 from pipecat.processors.frame_processor import FrameDirection
 from pipecat.services.llm_service import LLMService
 from pipecat.services.settings import _NotGiven, assert_given
@@ -58,10 +51,6 @@ class DograhUltravoxOneShotInputParams(OneShotInputParams):
 
 
 _ULTRAVOX_MAX_TOOL_TIMEOUT_SECS = 40.0
-_RESUMPTION_USER_MESSAGE = (
-    "IMPORTANT: We are resuming an existing conversation. You are given previous turns ONLY for your reference. "
-    "Do not use that to frame your response. Follow your ORIGINAL INSTRUCTIONS ONLY."
-)
 
 
 class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
@@ -72,12 +61,19 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
         self._context: LLMContext | None = None
         self._selected_tools = None
         self._user_is_muted: bool = False
-        self._call_system_instruction: str | None = None
-        self._reconnect_required: bool = False
         self._call_started: bool = False
-        self._has_connected_once: bool = False
-        self._pending_reconnect_system_instruction: str | None = None
-        self._pending_initial_messages: list[dict[str, Any]] | None = None
+        self._stage_update_required: bool = False
+        # Ultravox applies a stage update on the matching client tool result,
+        # so retain the provider invocation ID until that result reaches us via
+        # the context aggregator. Unlike Gemini, this ID is part of the wire
+        # protocol needed to update the existing call without reconnecting.
+        self._pending_node_transition_tool_call_ids: set[str] = set()
+        # A stage result can replace the active prompt and tools immediately.
+        # Hold transition invocations separately so ordinary tools can still
+        # run during speech while workflow control waits for response end.
+        self._deferred_node_transition_tool_invocations: list[
+            tuple[str, str, dict[str, Any]]
+        ] = []
         self._pending_user_text_messages: list[str] = []
 
     async def start(self, frame):
@@ -96,9 +92,7 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
         if isinstance(frame, TTSSpeakFrame):
             if not self._socket:
                 await self._connect_call(
-                    system_instruction=self._current_system_instruction(),
                     greeting_text=frame.text,
-                    initial_messages=None,
                     agent_speaks_first=True,
                 )
             else:
@@ -116,18 +110,15 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
         changed = await super(UltravoxRealtimeLLMService, self)._update_settings(delta)
         if "output_medium" in changed:
             await self._update_output_medium(assert_given(self._settings.output_medium))
-        if "system_instruction" in changed and self._has_connected_once:
-            # Mirror Gemini's "settings change means reconnect" intent, but
-            # defer the actual new-call creation until the subsequent
-            # LLMContextFrame arrives with the transition tool result. Ultravox
-            # cannot accept that historical tool result over a formal
-            # post-connect tool-response channel the way Gemini can.
-            self._reconnect_required = True
+        if "system_instruction" in changed and self._socket:
+            # The updated instruction is included in the native new-stage
+            # response when the transition tool result reaches _handle_context.
+            self._stage_update_required = True
         handled = {"output_medium", "system_instruction"}
         self._warn_unhandled_updated_settings(changed.keys() - handled)
         return changed
 
-    async def _disconnect(self, preserve_completed_tool_calls: bool = True):
+    async def _disconnect(self):
         self._disconnecting = True
         await self.stop_all_metrics()
         if self._socket:
@@ -136,10 +127,11 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
         if self._receive_task:
             await self.cancel_task(self._receive_task, timeout=1.0)
             self._receive_task = None
-        if not preserve_completed_tool_calls:
-            self._completed_tool_calls = set()
+        self._completed_tool_calls = set()
         self._call_started = False
         self._started_placeholder_sent = set()
+        self._pending_node_transition_tool_call_ids = set()
+        self._deferred_node_transition_tool_invocations = []
         self._disconnecting = False
 
     async def _send_user_audio(self, frame):
@@ -149,39 +141,20 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
 
     async def _handle_context(self, context: LLMContext):
         self._context = context
-        system_instruction = self._current_system_instruction()
 
-        if self._socket and not self._reconnect_required:
-            await super()._handle_context(context)
+        if not self._socket:
+            await self._connect_call(
+                greeting_text=None,
+                agent_speaks_first=True,
+            )
             return
 
-        initial_messages, history_tool_call_ids = self._build_initial_messages(context)
-        if history_tool_call_ids:
-            self._completed_tool_calls.update(history_tool_call_ids)
-
-        if self._bot_responding:
-            self._pending_reconnect_system_instruction = system_instruction
-            self._pending_initial_messages = initial_messages
-            return
-
-        await self._reconnect_with_context(
-            system_instruction=system_instruction,
-            initial_messages=initial_messages,
-        )
-
-    async def _handle_response_end(self):
-        await super()._handle_response_end()
-        if self._pending_reconnect_system_instruction is None:
-            return
-
-        system_instruction = self._pending_reconnect_system_instruction
-        initial_messages = self._pending_initial_messages
-        self._pending_reconnect_system_instruction = None
-        self._pending_initial_messages = None
-        await self._reconnect_with_context(
-            system_instruction=system_instruction,
-            initial_messages=initial_messages,
-        )
+        current_tools = self._current_tools_schema(context)
+        if self._pending_node_transition_tool_call_ids and self._tools_changed(
+            current_tools
+        ):
+            self._stage_update_required = True
+        await super()._handle_context(context)
 
     async def _handle_messages_append(self, frame: LLMMessagesAppendFrame):
         texts = [
@@ -199,9 +172,7 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
         if not self._socket:
             self._pending_user_text_messages.extend(texts)
             await self._connect_call(
-                system_instruction=self._current_system_instruction(),
                 greeting_text=None,
-                initial_messages=None,
                 agent_speaks_first=False,
             )
             return
@@ -229,17 +200,95 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
             finalized=True,
         )
 
+    def _requires_node_transition_context_aggregation(self) -> bool:
+        """Commit any received final user transcript before changing stages.
+
+        Ultravox preserves its own audio-native history across a stage change,
+        but Dograh's local context still needs the final transcript before the
+        transition handler updates the workflow node.
+        """
+        return True
+
+    async def _handle_tool_invocation(
+        self, tool_name: str, invocation_id: str, parameters: dict[str, Any]
+    ):
+        if self._function_is_node_transition(tool_name):
+            self._pending_node_transition_tool_call_ids.add(invocation_id)
+            if self._bot_responding:
+                self._deferred_node_transition_tool_invocations.append(
+                    (tool_name, invocation_id, parameters)
+                )
+                logger.debug(
+                    f"{self}: deferring workflow-control call {tool_name} "
+                    "until bot turn ends"
+                )
+                return
+        await super()._handle_tool_invocation(tool_name, invocation_id, parameters)
+
+    async def _handle_response_end(self):
+        """Close the current response before applying queued workflow control."""
+        await super()._handle_response_end()
+        await self._run_deferred_node_transition_tool_invocations()
+
+    async def _run_deferred_node_transition_tool_invocations(self):
+        if not self._deferred_node_transition_tool_invocations:
+            return
+
+        invocations = self._deferred_node_transition_tool_invocations
+        self._deferred_node_transition_tool_invocations = []
+        logger.debug(
+            f"{self}: executing {len(invocations)} deferred workflow-control "
+            "call(s) after bot turn ended"
+        )
+        for tool_name, invocation_id, parameters in invocations:
+            await super()._handle_tool_invocation(
+                tool_name, invocation_id, parameters
+            )
+
+    async def _send_tool_result(self, tool_call_id: str, result: str):
+        is_node_transition = tool_call_id in self._pending_node_transition_tool_call_ids
+        try:
+            if is_node_transition and self._stage_update_required:
+                await self._send_node_transition_stage_result(tool_call_id, result)
+            else:
+                await super()._send_tool_result(tool_call_id, result)
+        finally:
+            if is_node_transition:
+                self._pending_node_transition_tool_call_ids.discard(tool_call_id)
+
+    async def _send_node_transition_stage_result(self, tool_call_id: str, result: str):
+        """Apply node settings using Ultravox's native call-stage protocol."""
+        next_tools = self._current_tools_schema(self._context)
+        stage = {
+            "systemPrompt": self._current_system_instruction(),
+            "selectedTools": self._selected_tools_payload(next_tools),
+            # Keep the workflow handler's result as the tool-result message in
+            # the inherited conversation history for the next generation.
+            "toolResultText": result,
+        }
+        logger.debug(
+            f"{self}: updating Ultravox call stage for tool_call_id={tool_call_id} "
+            f"with {len(stage['selectedTools'])} selected tool(s)"
+        )
+        await self._send(
+            {
+                "type": "client_tool_result",
+                "invocationId": tool_call_id,
+                "result": json.dumps(stage, ensure_ascii=True, default=str),
+                "responseType": "new-stage",
+            }
+        )
+        self._selected_tools = next_tools
+        self._stage_update_required = False
+
     async def _connect_call(
         self,
         *,
-        system_instruction: str | None,
         greeting_text: str | None,
-        initial_messages: list[dict[str, Any]] | None,
         agent_speaks_first: bool,
     ):
         params = self._build_one_shot_params(
             greeting_text=greeting_text,
-            initial_messages=initial_messages,
             agent_speaks_first=agent_speaks_first,
         )
         self._params = params
@@ -265,9 +314,7 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
             logger.info(f"Joining Ultravox Realtime call via URL: {join_url}")
             self._socket = await websocket_client.connect(join_url)
             self._receive_task = self.create_task(self._receive_messages())
-            self._call_system_instruction = system_instruction
             self._call_started = False
-            self._has_connected_once = True
         except Exception as e:
             logger.error(
                 f"{self}: Ultravox call creation/join failed "
@@ -365,40 +412,17 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
         for pending_text in pending_texts:
             await self._send_user_text(pending_text)
 
-    async def _reconnect_with_context(
-        self,
-        *,
-        system_instruction: str | None,
-        initial_messages: list[dict[str, Any]] | None,
-    ):
-        call_initial_messages = self._initial_messages_for_call(initial_messages)
-        logger.debug(
-            f"{self}: reconnecting Ultravox call with initialMessages="
-            f"{json.dumps(call_initial_messages, ensure_ascii=True, default=str)}"
-        )
-        if self._socket:
-            await self._disconnect(preserve_completed_tool_calls=True)
-
-        await self._connect_call(
-            system_instruction=system_instruction,
-            greeting_text=None,
-            initial_messages=initial_messages,
-            agent_speaks_first=self._should_agent_speak_first(initial_messages),
-        )
-        self._reconnect_required = False
-
     def _build_one_shot_params(
         self,
         *,
         greeting_text: str | None,
-        initial_messages: list[dict[str, Any]] | None,
         agent_speaks_first: bool,
     ) -> DograhUltravoxOneShotInputParams:
         current_params = self._params
         extra = {
             key: value
             for key, value in current_params.extra.items()
-            if key not in {"firstSpeakerSettings", "initialMessages"}
+            if key != "firstSpeakerSettings"
         }
 
         if greeting_text is not None:
@@ -407,10 +431,6 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
             extra["firstSpeakerSettings"] = {"agent": {}}
         else:
             extra["firstSpeakerSettings"] = {"user": {}}
-        call_initial_messages = self._initial_messages_for_call(initial_messages)
-        if call_initial_messages:
-            extra["initialMessages"] = call_initial_messages
-
         output_medium = self._settings.output_medium
         if isinstance(output_medium, _NotGiven):
             output_medium = current_params.output_medium
@@ -432,6 +452,14 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
             return None
         return context.tools
 
+    def _selected_tools_payload(self, tools: Any) -> list[dict[str, Any]]:
+        return self._to_selected_tools(tools) if tools else []
+
+    def _tools_changed(self, tools: Any) -> bool:
+        return self._selected_tools_payload(tools) != self._selected_tools_payload(
+            self._selected_tools
+        )
+
     def _to_selected_tools(self, tool: Any) -> list[dict[str, Any]]:
         selected_tools = super()._to_selected_tools(tool)
         for selected_tool in selected_tools:
@@ -462,156 +490,6 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
         timeout_secs = min(float(item.timeout_secs), _ULTRAVOX_MAX_TOOL_TIMEOUT_SECS)
         return f"{timeout_secs:g}s"
 
-    def _initial_messages_for_call(
-        self, initial_messages: list[dict[str, Any]] | None
-    ) -> list[dict[str, Any]] | None:
-        if not initial_messages:
-            return None
-        if not self._should_add_resumption_user_message(initial_messages):
-            return initial_messages
-
-        return [
-            *initial_messages,
-            {
-                "role": "MESSAGE_ROLE_USER",
-                "text": _RESUMPTION_USER_MESSAGE,
-            },
-        ]
-
-    def _build_initial_messages(
-        self, context: LLMContext
-    ) -> tuple[list[dict[str, Any]] | None, set[str]]:
-        initial_messages: list[dict[str, Any]] = []
-        tool_call_id_to_name: dict[str, str] = {}
-        completed_tool_call_ids: set[str] = set()
-
-        for message in context.get_messages():
-            if isinstance(message, LLMSpecificMessage):
-                continue
-
-            async_payload = async_tool_messages.parse_message(message)
-            if async_payload is not None:
-                if async_payload.kind == "intermediate":
-                    logger.error(
-                        f"{self}: Ultravox does not support streamed async tool results; "
-                        f"dropping intermediate result from initialMessages for "
-                        f"tool_call_id={async_payload.tool_call_id}."
-                    )
-                    continue
-                if async_payload.kind == "final":
-                    initial_message = self._build_ultravox_message(
-                        role="MESSAGE_ROLE_TOOL_RESULT",
-                        text=async_payload.result or "",
-                        invocation_id=async_payload.tool_call_id,
-                        tool_name=tool_call_id_to_name.get(async_payload.tool_call_id),
-                    )
-                    if initial_message is not None:
-                        initial_messages.append(initial_message)
-                    completed_tool_call_ids.add(async_payload.tool_call_id)
-                continue
-
-            role = message.get("role")
-            if role == "user":
-                initial_message = self._build_ultravox_message(
-                    role="MESSAGE_ROLE_USER",
-                    text=self._extract_text_content(message.get("content")),
-                )
-                if initial_message is not None:
-                    initial_messages.append(initial_message)
-            elif role == "assistant":
-                text = self._extract_text_content(message.get("content"))
-                initial_message = self._build_ultravox_message(
-                    role="MESSAGE_ROLE_AGENT",
-                    text=text,
-                )
-                if initial_message is not None:
-                    initial_messages.append(initial_message)
-
-                tool_calls = message.get("tool_calls")
-                if isinstance(tool_calls, list):
-                    for tool_call in tool_calls:
-                        if not isinstance(tool_call, dict):
-                            continue
-                        tool_id = tool_call.get("id")
-                        function = tool_call.get("function")
-                        tool_name = (
-                            function.get("name") if isinstance(function, dict) else None
-                        )
-                        if isinstance(tool_id, str) and isinstance(tool_name, str):
-                            tool_call_id_to_name[tool_id] = tool_name
-                            initial_message = self._build_ultravox_message(
-                                role="MESSAGE_ROLE_TOOL_CALL",
-                                text="",
-                                invocation_id=tool_id,
-                                tool_name=tool_name,
-                            )
-                            if initial_message is not None:
-                                initial_messages.append(initial_message)
-            elif (
-                role == "tool"
-                and message.get("content") != "IN_PROGRESS"
-                and message.get("content") != "CANCELLED"
-            ):
-                tool_call_id = message.get("tool_call_id")
-                initial_message = self._build_ultravox_message(
-                    role="MESSAGE_ROLE_TOOL_RESULT",
-                    text=self._stringify_tool_result(message.get("content")),
-                    invocation_id=tool_call_id
-                    if isinstance(tool_call_id, str)
-                    else None,
-                    tool_name=(
-                        tool_call_id_to_name.get(tool_call_id)
-                        if isinstance(tool_call_id, str)
-                        else None
-                    ),
-                )
-                if initial_message is not None:
-                    initial_messages.append(initial_message)
-                if isinstance(tool_call_id, str):
-                    completed_tool_call_ids.add(tool_call_id)
-
-        return (initial_messages or None), completed_tool_call_ids
-
-    @staticmethod
-    def _build_ultravox_message(
-        *,
-        role: str,
-        text: str | None,
-        invocation_id: str | None = None,
-        tool_name: str | None = None,
-    ) -> dict[str, Any] | None:
-        if text is None:
-            return None
-
-        message: dict[str, Any] = {
-            "role": role,
-            "text": text,
-        }
-        if invocation_id is not None:
-            message["invocationId"] = invocation_id
-        if tool_name is not None:
-            message["toolName"] = tool_name
-        return message
-
-    @staticmethod
-    def _should_agent_speak_first(
-        initial_messages: list[dict[str, Any]] | None,
-    ) -> bool:
-        if not initial_messages:
-            return True
-        return initial_messages[-1].get("role") in {
-            "MESSAGE_ROLE_USER",
-            "MESSAGE_ROLE_TOOL_RESULT",
-        }
-
-    @staticmethod
-    def _should_add_resumption_user_message(
-        initial_messages: list[dict[str, Any]] | None,
-    ) -> bool:
-        if not initial_messages:
-            return False
-        return initial_messages[-1].get("role") == "MESSAGE_ROLE_TOOL_RESULT"
-
     @staticmethod
     def _is_benign_websocket_close(exc: ConnectionClosed) -> bool:
         return any(
@@ -636,18 +514,3 @@ class DograhUltravoxRealtimeLLMService(UltravoxRealtimeLLMService):
                 parts.append(text)
             return "\n".join(parts) if parts else None
         return None
-
-    @staticmethod
-    def _stringify_tool_result(content: Any) -> str:
-        if isinstance(content, str):
-            return content
-        if isinstance(content, list):
-            parts: list[str] = []
-            for part in content:
-                if isinstance(part, dict):
-                    text = part.get("text")
-                    if isinstance(text, str):
-                        parts.append(text)
-            if parts:
-                return "".join(parts)
-        return json.dumps(content, ensure_ascii=True, default=str)

api/services/pipecat/service_factory.py

@@ -1029,14 +1029,28 @@ def create_realtime_llm_service(user_config, audio_config: "AudioConfig"):
         from api.services.pipecat.realtime.grok_realtime import (
             DograhGrokRealtimeLLMService,
         )
-        from pipecat.services.xai.realtime.events import SessionProperties
+        from pipecat.services.xai.realtime.events import (
+            AudioConfiguration,
+            AudioInput,
+            InputAudioTranscription,
+            SessionProperties,
+        )
+
+        grok_voice = voice or "ara"
+        if grok_voice.lower() in {"ara", "rex", "sal", "eve", "leo"}:
+            grok_voice = grok_voice.lower()
 
         return DograhGrokRealtimeLLMService(
             api_key=api_key,
             settings=DograhGrokRealtimeLLMService.Settings(
                 model=model,
                 session_properties=SessionProperties(
-                    voice=voice or "Ara",
+                    voice=grok_voice,
+                    audio=AudioConfiguration(
+                        input=AudioInput(
+                            transcription=InputAudioTranscription(),
+                        ),
+                    ),
                 ),
             ),
         )
@@ -1115,19 +1129,25 @@ def create_realtime_llm_service(user_config, audio_config: "AudioConfig"):
                 detail="Azure Realtime requires an endpoint.",
             )
         _validate_runtime_service_url(endpoint, "endpoint")
-        api_version = (
-            getattr(realtime_config, "api_version", None) or "2025-04-01-preview"
-        )
-        # Construct the Azure Realtime WebSocket URL
-        # https://<resource>.openai.azure.com/openai/realtime?api-version=<ver>&deployment=<model>
+        api_version = getattr(realtime_config, "api_version", None) or "v1"
         parsed_endpoint = urlparse(endpoint)
+        if api_version == "v1":
+            # Azure's GA Realtime API uses the deployment name as `model` and
+            # deliberately has no date-based api-version query parameter.
+            path = "/openai/v1/realtime"
+            query = urlencode({"model": model})
+        else:
+            # Preserve explicitly configured preview deployments while users
+            # migrate. Microsoft deprecated this protocol on April 30, 2026.
+            path = "/openai/realtime"
+            query = urlencode({"api-version": api_version, "deployment": model})
         wss_url = urlunparse(
             (
                 "wss",
                 parsed_endpoint.netloc,
-                "/openai/realtime",
+                path,
                 "",
-                urlencode({"api-version": api_version, "deployment": model}),
+                query,
                 "",
             )
         )

api/services/telephony/providers/cloudonix/provider.py

@@ -1096,9 +1096,7 @@ class CloudonixProvider(TelephonyProvider):
         from_number = random.choice(self.from_numbers)
 
         backend_endpoint, _ = await get_backend_endpoints()
-        callback_url = (
-            f"{backend_endpoint}/api/v1/telephony/cloudonix/transfer-result/{transfer_id}"
-        )
+        callback_url = f"{backend_endpoint}/api/v1/telephony/cloudonix/transfer-result/{transfer_id}"
 
         endpoint = f"{self.base_url}/calls/{self.domain_id}/application"
         data: Dict[str, Any] = {
@@ -1111,9 +1109,7 @@ class CloudonixProvider(TelephonyProvider):
 
         data.update(kwargs)
         headers = self._get_auth_headers()
-        masked_destination = (
-            f"***{destination[-4:]}" if len(destination) > 4 else "***"
-        )
+        masked_destination = f"***{destination[-4:]}" if len(destination) > 4 else "***"
         logger.info(
             f"[Cloudonix Transfer] Dialing {masked_destination} into conference "
             f"{conference_name} (transfer_id={transfer_id})"

api/services/telephony/providers/cloudonix/routes.py

@@ -79,7 +79,7 @@ async def handle_cloudonix_transfer_result(transfer_id: str, request: Request):
     original_call_sid = transfer_context.original_call_sid
     conference_name = transfer_context.conference_name
 
-    if (conferenceStatus == "participant-join"):
+    if conferenceStatus == "participant-join":
         event = TransferEvent(
             type=TransferEventType.DESTINATION_ANSWERED,
             transfer_id=transfer_id,
@@ -89,7 +89,7 @@ async def handle_cloudonix_transfer_result(transfer_id: str, request: Request):
             message="Great! The destination answered. Connecting you now.",
             status="success",
             action="destination_answered",
-        )     
+        )
     elif outboundCallStatus in _CLOUDONIX_TRANSFER_FAILURE_STATUSES:
         event = TransferEvent(
             type=TransferEventType.TRANSFER_FAILED,

api/services/telephony/providers/cloudonix/strategies.py

@@ -120,7 +120,9 @@ class CloudonixConferenceStrategy(TransferStrategy):
             manager = await get_call_transfer_manager()
             await manager.remove_transfer_context(transfer_id)
         except Exception as e:
-            logger.error(f"[Cloudonix Transfer] Error cleaning up transfer context: {e}")
+            logger.error(
+                f"[Cloudonix Transfer] Error cleaning up transfer context: {e}"
+            )
 
 
 class CloudonixHangupStrategy(HangupStrategy):

api/services/workflow/pipecat_engine.py

@@ -344,7 +344,11 @@ class PipecatEngine:
         )
 
         # Register function with LLM
-        self.llm.register_function(name, transition_func)
+        self.llm.register_function(
+            name,
+            transition_func,
+            is_node_transition=True,
+        )
 
     async def _register_knowledge_base_function(
         self, document_uuids: list[str]

api/services/workflow/pipecat_engine_custom_tools.py

@@ -288,10 +288,19 @@ class CustomToolManager:
 
                 # Create and register the handler
                 handler, timeout_secs = self._create_handler(tool, function_name)
+                # End-call and transfer-call tools are workflow-control
+                # boundaries even though they do not necessarily select another
+                # graph node. Give them the same ordering guarantees as an
+                # explicit node-transition function.
+                is_node_transition = tool.category in {
+                    ToolCategory.END_CALL.value,
+                    ToolCategory.TRANSFER_CALL.value,
+                }
                 self._engine.llm.register_function(
                     function_name,
                     handler,
                     timeout_secs=timeout_secs,
+                    is_node_transition=is_node_transition,
                 )
 
                 logger.debug(

api/tests/test_azure_realtime_wrapper.py

@@ -86,3 +86,45 @@ async def test_tts_greeting_waits_for_session_updated_before_sending_prompt():
     assert service._pending_initial_greeting_text is None
     assert service._llm_needs_conversation_setup is False
     service._create_response.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_non_transition_function_call_runs_while_bot_is_speaking():
+    service = _make_service()
+    service._context = LLMContext()
+    service.run_function_calls = AsyncMock()
+    service._bot_is_speaking = True
+    service._pending_function_calls["call-1"] = SimpleNamespace(name="lookup_order")
+
+    await service._handle_evt_function_call_arguments_done(
+        SimpleNamespace(call_id="call-1", arguments='{"order_id":"123"}')
+    )
+
+    service.run_function_calls.assert_awaited_once()
+    assert service._deferred_node_transition_function_calls == []
+
+
+@pytest.mark.asyncio
+async def test_node_transition_function_call_waits_until_bot_stops_speaking():
+    service = _make_service()
+    service._context = LLMContext()
+    service.run_function_calls = AsyncMock()
+    service._bot_is_speaking = True
+    service.register_function(
+        "customer_support",
+        AsyncMock(),
+        is_node_transition=True,
+    )
+    service._pending_function_calls["call-1"] = SimpleNamespace(name="customer_support")
+
+    await service._handle_evt_function_call_arguments_done(
+        SimpleNamespace(call_id="call-1", arguments='{"department":"sales"}')
+    )
+
+    service.run_function_calls.assert_not_awaited()
+    assert len(service._deferred_node_transition_function_calls) == 1
+
+    await service._run_pending_node_transition_function_calls()
+
+    service.run_function_calls.assert_awaited_once()
+    assert service._deferred_node_transition_function_calls == []

api/tests/test_azure_speech_service_factory.py

@@ -170,6 +170,46 @@ def test_create_azure_realtime_blocks_private_endpoint_in_saas(monkeypatch):
     assert "public IP" in exc_info.value.detail
 
 
+def test_create_azure_realtime_uses_ga_websocket_url_by_default(monkeypatch):
+    monkeypatch.setattr("api.utils.url_security.DEPLOYMENT_MODE", "oss")
+    user_config = SimpleNamespace(
+        realtime=SimpleNamespace(
+            provider=ServiceProviders.AZURE_REALTIME.value,
+            api_key="test-key",
+            endpoint="https://example.openai.azure.com",
+            model="my-realtime-deployment",
+            voice="alloy",
+        )
+    )
+
+    service = create_realtime_llm_service(user_config, _audio_config())
+
+    assert service.base_url == (
+        "wss://example.openai.azure.com/openai/v1/realtime?model=my-realtime-deployment"
+    )
+
+
+def test_create_azure_realtime_preserves_explicit_preview_websocket_url(monkeypatch):
+    monkeypatch.setattr("api.utils.url_security.DEPLOYMENT_MODE", "oss")
+    user_config = SimpleNamespace(
+        realtime=SimpleNamespace(
+            provider=ServiceProviders.AZURE_REALTIME.value,
+            api_key="test-key",
+            endpoint="https://example.openai.azure.com",
+            api_version="2025-04-01-preview",
+            model="my-preview-deployment",
+            voice="alloy",
+        )
+    )
+
+    service = create_realtime_llm_service(user_config, _audio_config())
+
+    assert service.base_url == (
+        "wss://example.openai.azure.com/openai/realtime?"
+        "api-version=2025-04-01-preview&deployment=my-preview-deployment"
+    )
+
+
 def test_azure_embedding_service_rejects_wrong_dimension():
     service = AzureOpenAIEmbeddingService(
         db_client=SimpleNamespace(),

api/tests/test_custom_tools.py

@@ -1415,6 +1415,7 @@ class TestCustomToolManagerUnit:
             # Verify handler was registered
             assert "api_call" in registered_handlers
             assert registered_kwargs["api_call"]["timeout_secs"] == pytest.approx(5)
+            assert registered_kwargs["api_call"]["is_node_transition"] is False
 
         # Now test that the handler works
         handler = registered_handlers["api_call"]
@@ -1445,6 +1446,41 @@ class TestCustomToolManagerUnit:
             # Verify result was returned
             assert result_received["status"] == "success"
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("category", ["end_call", "transfer_call"])
+    async def test_register_handlers_marks_call_control_tools_as_node_transitions(
+        self, category
+    ):
+        from api.services.workflow.pipecat_engine_custom_tools import CustomToolManager
+
+        mock_engine = Mock()
+        mock_engine._get_organization_id = AsyncMock(return_value=1)
+        mock_engine.llm.register_function = Mock()
+        manager = CustomToolManager(mock_engine)
+        tool = MockToolModel(
+            tool_uuid=f"{category}-uuid",
+            name=category.replace("_", " "),
+            description=f"Perform {category}",
+            category=category,
+            definition={
+                "schema_version": 1,
+                "type": category,
+                "config": {},
+            },
+        )
+
+        with patch(
+            "api.services.workflow.pipecat_engine_custom_tools.db_client.get_tools_by_uuids",
+            new=AsyncMock(return_value=[tool]),
+        ):
+            await manager.register_handlers([tool.tool_uuid])
+
+        mock_engine.llm.register_function.assert_called_once()
+        assert (
+            mock_engine.llm.register_function.call_args.kwargs["is_node_transition"]
+            is True
+        )
+
     @pytest.mark.asyncio
     async def test_transfer_call_renders_destination_from_initial_context(self):
         """Transfer call tools resolve destination templates before provider calls."""

api/tests/test_gemini_json_schema_adapter.py

@@ -134,6 +134,21 @@ def test_gemini_live_service_classes_use_dograh_gemini_adapter_class():
     )
 
 
+def test_vertex_live_inherits_dograh_node_transition_lifecycle():
+    assert (
+        DograhGeminiLiveVertexLLMService._requires_node_transition_context_aggregation
+        is DograhGeminiLiveLLMService._requires_node_transition_context_aggregation
+    )
+    assert (
+        DograhGeminiLiveVertexLLMService._run_or_defer_function_calls
+        is DograhGeminiLiveLLMService._run_or_defer_function_calls
+    )
+    assert (
+        DograhGeminiLiveVertexLLMService._reconnect_for_node_transition
+        is DograhGeminiLiveLLMService._reconnect_for_node_transition
+    )
+
+
 def test_gemini_live_config_accepts_json_schema_tools():
     function_schema = FunctionSchema(
         name="customer_lookup",

api/tests/test_gemini_live_reconnect_tool_results.py

@@ -1,11 +1,20 @@
+import asyncio
 import json
 from types import SimpleNamespace
 from unittest.mock import AsyncMock
 
 import pytest
-from pipecat.frames.frames import TranscriptionFrame, TTSSpeakFrame
+from pipecat.frames.frames import (
+    NodeTransitionStartedFrame,
+    TranscriptionFrame,
+    TTSSpeakFrame,
+)
 from pipecat.processors.aggregators.llm_context import LLMContext
+from pipecat.processors.aggregators.llm_response_universal import (
+    LLMContextAggregatorPair,
+)
 from pipecat.processors.frame_processor import FrameDirection
+from pipecat.services.llm_service import FunctionCallFromLLM
 
 from api.services.pipecat.realtime.gemini_live import DograhGeminiLiveLLMService
 
@@ -163,3 +172,194 @@ async def test_tts_greeting_waits_for_gemini_session_before_sending_prompt():
     assert prompt.endswith('"Hello from Dograh."')
     assert service._run_llm_when_session_ready is False
     assert service._pending_initial_greeting_text is None
+
+
+@pytest.mark.asyncio
+async def test_transition_call_flushes_pending_transcription_before_execution():
+    service = _make_service()
+    service._NODE_TRANSITION_TRANSCRIPTION_GRACE_SECONDS = 0
+    service.register_function(
+        "transition_to_next_node",
+        AsyncMock(),
+        is_node_transition=True,
+    )
+    service._user_transcription_buffer = "My last answer"
+
+    events = []
+
+    async def _push_transcription(text, result=None):
+        events.append(("transcription", text))
+
+    async def _run_function_calls(function_calls):
+        events.append(("function", function_calls[0].function_name))
+
+    service._push_user_transcription = AsyncMock(side_effect=_push_transcription)
+    service.run_function_calls = AsyncMock(side_effect=_run_function_calls)
+    service.create_task = lambda coro, name=None: asyncio.create_task(coro, name=name)
+
+    function_call = FunctionCallFromLLM(
+        context=LLMContext(),
+        tool_call_id="call-transition",
+        function_name="transition_to_next_node",
+        arguments={},
+    )
+
+    await service._run_or_defer_function_calls([function_call])
+    transition_task = service._transition_function_call_task
+    assert transition_task is not None
+    await transition_task
+
+    assert events == [
+        ("transcription", "My last answer"),
+        ("function", "transition_to_next_node"),
+    ]
+    assert service._user_transcription_buffer == ""
+
+
+@pytest.mark.asyncio
+async def test_non_transition_call_is_not_deferred_while_bot_is_responding():
+    service = _make_service()
+    service._bot_is_responding = True
+    service.run_function_calls = AsyncMock()
+
+    function_call = FunctionCallFromLLM(
+        context=LLMContext(),
+        tool_call_id="call-ordinary",
+        function_name="look_up_account",
+        arguments={},
+    )
+
+    await service._run_or_defer_function_calls([function_call])
+
+    service.run_function_calls.assert_awaited_once_with([function_call])
+    assert service._pending_node_transition_function_calls == []
+    assert service._transition_function_call_task is None
+
+
+@pytest.mark.asyncio
+async def test_node_transition_call_is_deferred_while_bot_is_responding():
+    service = _make_service()
+    service._bot_is_responding = True
+    service.register_function(
+        "transition_to_next_node",
+        AsyncMock(),
+        is_node_transition=True,
+    )
+    service.run_function_calls = AsyncMock()
+
+    function_call = FunctionCallFromLLM(
+        context=LLMContext(),
+        tool_call_id="call-transition",
+        function_name="transition_to_next_node",
+        arguments={},
+    )
+
+    await service._run_or_defer_function_calls([function_call])
+
+    service.run_function_calls.assert_not_awaited()
+    assert service._pending_node_transition_function_calls == [function_call]
+    assert service._transition_function_call_task is None
+
+
+@pytest.mark.asyncio
+async def test_initial_system_instruction_update_is_not_a_node_handoff():
+    service = _make_service()
+    service._connect = AsyncMock()
+    service._disconnect = AsyncMock()
+
+    handled = await service._handle_changed_settings(
+        {"system_instruction": "old prompt"}
+    )
+
+    assert handled == {"system_instruction"}
+    service._connect.assert_awaited_once_with()
+    service._disconnect.assert_not_awaited()
+    assert service._awaiting_node_transition_context is False
+
+
+@pytest.mark.asyncio
+async def test_node_transition_uses_fresh_connection_instead_of_stale_handle():
+    service = _make_service()
+    service._session = _FakeSession()
+    service._session_resumption_handle = "stale-handle"
+    service._disconnect = AsyncMock()
+    service._connect = AsyncMock()
+
+    handled = await service._handle_changed_settings(
+        {"system_instruction": "old prompt"}
+    )
+
+    assert handled == {"system_instruction"}
+    assert service._session_resumption_handle is None
+    assert service._awaiting_node_transition_context is True
+    service._disconnect.assert_awaited_once()
+    service._connect.assert_awaited_once_with(session_resumption_handle=None)
+
+
+@pytest.mark.asyncio
+async def test_fresh_transition_session_waits_for_updated_context_before_ready():
+    service = _make_service()
+    service._handled_initial_context = True
+    service._awaiting_node_transition_context = True
+    service._node_transition_context_received = False
+    service._process_completed_function_calls = AsyncMock()
+    service._drain_pending_tool_results = AsyncMock()
+
+    async def _seed_context():
+        service._ready_for_realtime_input = True
+
+    service._create_initial_response = AsyncMock(side_effect=_seed_context)
+
+    session = _FakeSession()
+    await service._handle_session_ready(session)
+
+    assert service._ready_for_realtime_input is False
+    service._create_initial_response.assert_not_awaited()
+
+    context = _make_tool_result_context("call-transition")
+    await service._handle_context(context)
+
+    service._process_completed_function_calls.assert_awaited_once_with(
+        send_new_results=False
+    )
+    service._create_initial_response.assert_awaited_once()
+    service._drain_pending_tool_results.assert_awaited_once()
+    assert service._ready_for_realtime_input is True
+    assert service._awaiting_node_transition_context is False
+
+
+@pytest.mark.asyncio
+async def test_node_transition_frame_commits_user_transcript_to_context():
+    context = LLMContext()
+    context_aggregator = LLMContextAggregatorPair(context, realtime_service_mode=True)
+    user_aggregator = context_aggregator.user()
+    user_aggregator.push_context_frame = AsyncMock()
+
+    await user_aggregator._handle_transcription(
+        TranscriptionFrame(
+            text="The answer that selected this node",
+            user_id="",
+            timestamp="now",
+        )
+    )
+    context_aggregation_event = asyncio.Event()
+    await user_aggregator._handle_node_transition_started(
+        NodeTransitionStartedFrame(
+            function_calls=[
+                FunctionCallFromLLM(
+                    context=context,
+                    tool_call_id="call-transition",
+                    function_name="transition_to_next_node",
+                    arguments={},
+                )
+            ],
+            context_aggregation_event=context_aggregation_event,
+        )
+    )
+
+    assert context.messages[-1] == {
+        "role": "user",
+        "content": "The answer that selected this node",
+    }
+    user_aggregator.push_context_frame.assert_awaited_once()
+    assert context_aggregation_event.is_set()

api/tests/test_grok_realtime_wrapper.py

@@ -130,7 +130,7 @@ async def test_messages_append_frame_sends_conversation_item():
 
 
 @pytest.mark.asyncio
-async def test_function_call_is_deferred_until_bot_stops_speaking():
+async def test_non_transition_function_call_runs_while_bot_is_speaking():
     service = _make_service()
     service._context = LLMContext()
     service.run_function_calls = AsyncMock()
@@ -145,13 +145,38 @@ async def test_function_call_is_deferred_until_bot_stops_speaking():
         )
     )
 
-    service.run_function_calls.assert_not_awaited()
-    assert len(service._deferred_function_calls) == 1
+    service.run_function_calls.assert_awaited_once()
+    assert service._deferred_node_transition_function_calls == []
 
-    await service._run_pending_function_calls()
+
+@pytest.mark.asyncio
+async def test_node_transition_function_call_waits_until_bot_stops_speaking():
+    service = _make_service()
+    service._context = LLMContext()
+    service.run_function_calls = AsyncMock()
+    service._bot_is_speaking = True
+    service.register_function(
+        "customer_support",
+        AsyncMock(),
+        is_node_transition=True,
+    )
+    service._pending_function_calls["call-1"] = SimpleNamespace(name="customer_support")
+
+    await service._handle_evt_function_call_arguments_done(
+        SimpleNamespace(
+            call_id="call-1",
+            name="customer_support",
+            arguments='{"department":"sales"}',
+        )
+    )
+
+    service.run_function_calls.assert_not_awaited()
+    assert len(service._deferred_node_transition_function_calls) == 1
+
+    await service._run_pending_node_transition_function_calls()
 
     service.run_function_calls.assert_awaited_once()
-    assert service._deferred_function_calls == []
+    assert service._deferred_node_transition_function_calls == []
 
 
 @pytest.mark.asyncio
@@ -190,3 +215,21 @@ def test_factory_creates_dograh_grok_realtime_service():
     )
 
     assert isinstance(service, DograhGrokRealtimeLLMService)
+    assert service._settings.session_properties.voice == "sal"
+    assert service._settings.session_properties.audio.input.transcription.model == (
+        "grok-transcribe"
+    )
+
+
+def test_grok_audio_config_preserves_transcription_when_filling_sample_rates():
+    service = _make_service()
+    service._settings.session_properties.audio = events.AudioConfiguration(
+        input=events.AudioInput(transcription=events.InputAudioTranscription())
+    )
+
+    service._ensure_audio_config(input_sample_rate=16000, output_sample_rate=24000)
+
+    audio = service._settings.session_properties.audio
+    assert audio.input.format.rate == 16000
+    assert audio.input.transcription.model == "grok-transcribe"
+    assert audio.output.format.rate == 24000

api/tests/test_openai_realtime_initial_context.py

@@ -127,11 +127,11 @@ async def test_function_call_executes_immediately_when_bot_is_not_speaking():
     )
 
     service.run_function_calls.assert_awaited_once()
-    assert service._deferred_function_calls == []
+    assert service._deferred_node_transition_function_calls == []
 
 
 @pytest.mark.asyncio
-async def test_function_call_is_deferred_until_bot_stops_speaking():
+async def test_non_transition_function_call_runs_while_bot_is_speaking():
     service = _make_service()
     service._context = LLMContext()
     service.run_function_calls = AsyncMock()
@@ -142,10 +142,31 @@ async def test_function_call_is_deferred_until_bot_stops_speaking():
         SimpleNamespace(call_id="call-1", arguments='{"department":"sales"}')
     )
 
-    service.run_function_calls.assert_not_awaited()
-    assert len(service._deferred_function_calls) == 1
+    service.run_function_calls.assert_awaited_once()
+    assert service._deferred_node_transition_function_calls == []
 
-    await service._run_pending_function_calls()
+
+@pytest.mark.asyncio
+async def test_node_transition_function_call_is_deferred_until_bot_stops_speaking():
+    service = _make_service()
+    service._context = LLMContext()
+    service.run_function_calls = AsyncMock()
+    service._bot_is_speaking = True
+    service.register_function(
+        "customer_support",
+        AsyncMock(),
+        is_node_transition=True,
+    )
+    service._pending_function_calls["call-1"] = SimpleNamespace(name="customer_support")
+
+    await service._handle_evt_function_call_arguments_done(
+        SimpleNamespace(call_id="call-1", arguments='{"department":"sales"}')
+    )
+
+    service.run_function_calls.assert_not_awaited()
+    assert len(service._deferred_node_transition_function_calls) == 1
+
+    await service._run_pending_node_transition_function_calls()
 
     service.run_function_calls.assert_awaited_once()
-    assert service._deferred_function_calls == []
+    assert service._deferred_node_transition_function_calls == []

api/tests/test_pipecat_engine_tool_calls.py

@@ -182,6 +182,7 @@ class TestPipecatEngineToolCalls:
 
         # Assert that the context was updated with END_CALL_SYSTEM_PROMPT
         assert llm._settings.system_instruction == END_CALL_SYSTEM_PROMPT
+        assert llm._functions["end_call"].is_node_transition is True
 
     @pytest.mark.asyncio
     async def test_parallel_builtin_and_transition_calls_through_engine_1(

api/tests/test_ultravox_realtime_wrapper.py

@@ -1,3 +1,4 @@
+import json
 from types import SimpleNamespace
 from unittest.mock import AsyncMock, call
 
@@ -13,7 +14,6 @@ from websockets.frames import Close
 from api.schemas.ai_model_configuration import EffectiveAIModelConfiguration
 from api.services.configuration.registry import UltravoxRealtimeLLMConfiguration
 from api.services.pipecat.realtime.ultravox_realtime import (
-    _RESUMPTION_USER_MESSAGE,
     DograhUltravoxOneShotInputParams,
     DograhUltravoxRealtimeLLMService,
 )
@@ -100,50 +100,35 @@ async def test_initial_context_connects_without_replay():
     await service._handle_context(context)
 
     service._connect_call.assert_awaited_once()
-    assert service._connect_call.await_args.kwargs["initial_messages"] is None
+    assert service._connect_call.await_args.kwargs["greeting_text"] is None
     assert service._connect_call.await_args.kwargs["agent_speaks_first"] is True
 
 
 @pytest.mark.asyncio
-async def test_system_instruction_update_marks_reconnect_required():
+async def test_system_instruction_update_marks_stage_update_required():
     service = _make_service()
-    service._has_connected_once = True
+    service._socket = object()
 
     changed = await service._update_settings(
         DograhUltravoxRealtimeLLMService.Settings(system_instruction="new instruction")
     )
 
     assert "system_instruction" in changed
-    assert service._reconnect_required is True
+    assert service._stage_update_required is True
 
 
 @pytest.mark.asyncio
-async def test_system_instruction_change_reconnects_with_full_initial_messages():
+async def test_node_transition_updates_native_stage_without_reconnecting():
     service = _make_service()
     service._socket = object()
-    service._has_connected_once = True
-    service._call_system_instruction = "old instruction"
-    service._reconnect_required = True
+    service._send = AsyncMock()
+    service._connect_call = AsyncMock()
+    service._pending_node_transition_tool_call_ids.add("call-transition")
+    service._stage_update_required = True
     service._settings.system_instruction = "new instruction"
-    service._reconnect_with_context = AsyncMock()
 
     context = LLMContext(
         messages=[
-            {"role": "user", "content": "I want to hear the pricing."},
-            {
-                "role": "assistant",
-                "content": "Let me check that for you.",
-                "tool_calls": [
-                    {
-                        "id": "call-transition",
-                        "type": "function",
-                        "function": {
-                            "name": "transition_to_next_node",
-                            "arguments": '{"reason":"pricing requested"}',
-                        },
-                    }
-                ],
-            },
             {
                 "role": "tool",
                 "tool_call_id": "call-transition",
@@ -155,43 +140,28 @@ async def test_system_instruction_change_reconnects_with_full_initial_messages()
 
     await service._handle_context(context)
 
-    service._reconnect_with_context.assert_awaited_once()
-    initial_messages = service._reconnect_with_context.await_args.kwargs[
-        "initial_messages"
-    ]
-    assert initial_messages == [
-        {
-            "role": "MESSAGE_ROLE_USER",
-            "text": "I want to hear the pricing.",
-        },
-        {
-            "role": "MESSAGE_ROLE_AGENT",
-            "text": "Let me check that for you.",
-        },
-        {
-            "role": "MESSAGE_ROLE_TOOL_CALL",
-            "text": "",
-            "invocationId": "call-transition",
-            "toolName": "transition_to_next_node",
-        },
-        {
-            "role": "MESSAGE_ROLE_TOOL_RESULT",
-            "text": '{"status":"done"}',
-            "invocationId": "call-transition",
-            "toolName": "transition_to_next_node",
-        },
-    ]
+    service._connect_call.assert_not_awaited()
+    service._send.assert_awaited_once()
+    message = service._send.await_args.args[0]
+    assert message["type"] == "client_tool_result"
+    assert message["invocationId"] == "call-transition"
+    assert message["responseType"] == "new-stage"
+    stage = json.loads(message["result"])
+    assert stage["systemPrompt"] == "new instruction"
+    assert stage["toolResultText"] == '{"status":"done"}'
+    assert stage["selectedTools"][0]["temporaryTool"]["modelToolName"] == (
+        "transition_to_next_node"
+    )
     assert "call-transition" in service._completed_tool_calls
+    assert service._pending_node_transition_tool_call_ids == set()
+    assert service._stage_update_required is False
 
 
 @pytest.mark.asyncio
-async def test_tool_context_update_does_not_reconnect_when_system_instruction_is_unchanged():
+async def test_ordinary_tool_result_uses_standard_tool_response():
     service = _make_service()
     service._socket = object()
-    service._call_system_instruction = "same instruction"
-    service._settings.system_instruction = "same instruction"
-    service._reconnect_with_context = AsyncMock()
-    service._send_tool_result = AsyncMock()
+    service._send = AsyncMock()
 
     context = LLMContext(
         messages=[
@@ -206,13 +176,89 @@ async def test_tool_context_update_does_not_reconnect_when_system_instruction_is
 
     await service._handle_context(context)
 
-    service._reconnect_with_context.assert_not_awaited()
-    service._send_tool_result.assert_awaited_once_with(
-        "call-transition",
-        '{"status":"done"}',
+    service._send.assert_awaited_once_with(
+        {
+            "type": "client_tool_result",
+            "invocationId": "call-transition",
+            "result": '{"status":"done"}',
+        }
     )
 
 
+@pytest.mark.asyncio
+async def test_only_registered_node_transition_invocations_are_tracked():
+    service = _make_service()
+    service.run_function_calls = AsyncMock()
+    service.register_function(
+        "transition_to_next_node",
+        AsyncMock(),
+        is_node_transition=True,
+    )
+
+    await service._handle_tool_invocation(
+        "transition_to_next_node", "call-transition", {"reason": "pricing"}
+    )
+    await service._handle_tool_invocation("lookup_price", "call-lookup", {})
+
+    assert service._pending_node_transition_tool_call_ids == {"call-transition"}
+    assert service.run_function_calls.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_node_transition_invocation_waits_for_response_end():
+    service = _make_service()
+    service.run_function_calls = AsyncMock()
+    service.stop_processing_metrics = AsyncMock()
+    service.push_frame = AsyncMock()
+    service.register_function(
+        "transition_to_next_node",
+        AsyncMock(),
+        is_node_transition=True,
+    )
+    service._bot_responding = "voice"
+
+    await service._handle_tool_invocation(
+        "transition_to_next_node", "call-transition", {"reason": "pricing"}
+    )
+
+    service.run_function_calls.assert_not_awaited()
+    assert service._deferred_node_transition_tool_invocations == [
+        (
+            "transition_to_next_node",
+            "call-transition",
+            {"reason": "pricing"},
+        )
+    ]
+
+    await service._handle_response_end()
+
+    service.run_function_calls.assert_awaited_once()
+    function_call = service.run_function_calls.await_args.args[0][0]
+    assert function_call.function_name == "transition_to_next_node"
+    assert function_call.tool_call_id == "call-transition"
+    assert function_call.arguments == {"reason": "pricing"}
+    assert service._deferred_node_transition_tool_invocations == []
+    assert service._bot_responding is None
+
+
+@pytest.mark.asyncio
+async def test_ordinary_tool_invocation_runs_while_response_is_active():
+    service = _make_service()
+    service.run_function_calls = AsyncMock()
+    service._bot_responding = "voice"
+
+    await service._handle_tool_invocation("lookup_price", "call-lookup", {})
+
+    service.run_function_calls.assert_awaited_once()
+    assert service._deferred_node_transition_tool_invocations == []
+
+
+def test_ultravox_requires_transition_context_aggregation():
+    service = _make_service()
+
+    assert service._requires_node_transition_context_aggregation() is True
+
+
 @pytest.mark.asyncio
 async def test_messages_append_frame_sends_user_text():
     service = _make_service()
@@ -287,7 +333,6 @@ def test_build_one_shot_params_uses_explicit_greeting_text():
 
     params = service._build_one_shot_params(
         greeting_text="Welcome to Dograh",
-        initial_messages=None,
         agent_speaks_first=True,
     )
 
@@ -296,85 +341,18 @@ def test_build_one_shot_params_uses_explicit_greeting_text():
     }
 
 
-def test_build_one_shot_params_includes_initial_messages():
+def test_build_one_shot_params_uses_current_system_instruction():
     service = _make_service()
     service._settings.system_instruction = "Base instruction"
 
     params = service._build_one_shot_params(
         greeting_text=None,
-        initial_messages=[
-            {"role": "MESSAGE_ROLE_USER", "text": "User asked a question."},
-            {"role": "MESSAGE_ROLE_TOOL_RESULT", "text": '{"status":"done"}'},
-        ],
         agent_speaks_first=True,
     )
 
-    assert params.extra["initialMessages"] == [
-        {"role": "MESSAGE_ROLE_USER", "text": "User asked a question."},
-        {"role": "MESSAGE_ROLE_TOOL_RESULT", "text": '{"status":"done"}'},
-        {"role": "MESSAGE_ROLE_USER", "text": _RESUMPTION_USER_MESSAGE},
-    ]
     assert params.system_prompt == "Base instruction"
 
 
-def test_build_one_shot_params_without_tool_result_does_not_add_resumption_user_message():
-    service = _make_service()
-    service._settings.system_instruction = "Base instruction"
-
-    params = service._build_one_shot_params(
-        greeting_text=None,
-        initial_messages=[
-            {"role": "MESSAGE_ROLE_USER", "text": "User asked a question."},
-            {"role": "MESSAGE_ROLE_AGENT", "text": "Assistant replied."},
-        ],
-        agent_speaks_first=False,
-    )
-
-    assert params.system_prompt == "Base instruction"
-
-
-def test_should_agent_speak_first_when_history_ends_with_tool_result():
-    service = _make_service()
-
-    assert (
-        service._should_agent_speak_first(
-            [
-                {"role": "MESSAGE_ROLE_USER", "text": "Hello"},
-                {"role": "MESSAGE_ROLE_TOOL_RESULT", "text": '{"status":"done"}'},
-            ]
-        )
-        is True
-    )
-
-
-def test_should_not_force_agent_speaks_first_when_history_ends_with_agent():
-    service = _make_service()
-
-    assert (
-        service._should_agent_speak_first(
-            [{"role": "MESSAGE_ROLE_AGENT", "text": "How else can I help?"}]
-        )
-        is False
-    )
-
-
-def test_should_add_resumption_user_message_only_when_history_ends_with_tool_result():
-    service = _make_service()
-
-    assert (
-        service._should_add_resumption_user_message(
-            [{"role": "MESSAGE_ROLE_TOOL_RESULT", "text": '{"status":"done"}'}]
-        )
-        is True
-    )
-    assert (
-        service._should_add_resumption_user_message(
-            [{"role": "MESSAGE_ROLE_AGENT", "text": "Assistant replied."}]
-        )
-        is False
-    )
-
-
 def test_to_selected_tools_includes_registered_timeout():
     service = _make_service()
     service.register_function(