fix(flows): detect thought-only and whitespace turns as empty content

When models return turns that contain only reasoning thoughts
(parts with thought=True) or whitespace text with finish_reason=STOP
after tool execution or under streaming, BaseLlmFlow previously
treated them as complete final responses because parts was not empty.
This caused the agent loop to silently terminate without answering the
user or surfacing an error.

- Add has_meaningful_content(llm_response) helper in _finalizer.py
  to verify if an LLM response contains actionable content (tools, code,
  data, or non-thought non-whitespace text).
- Update apply_empty_response_policy in _model_call.py to stamp
  MODEL_RETURNED_NO_CONTENT when an LLM response has finish_reason=STOP
  but lacks meaningful content.
- Ensure LiteLlm.generate_content_async streaming always yields a terminal
  partial=False response on normal termination even when no content chunks
  were emitted.
- Add unit tests covering has_meaningful_content, BaseLlmFlow error events
  for thought-only and whitespace-only turns, and LiteLlm empty stream fallback.

Co-authored-by: Shangjie Chen <deanchen@google.com>
PiperOrigin-RevId: 988479382

Author: DeanChensj

src/google/adk/flows/llm_flows/core/_finalizer.py

@@ -79,6 +79,52 @@ def finalize_model_response_event(
   return finalized_event
 
 
+def has_meaningful_content(llm_response: Optional[LlmResponse]) -> bool:
+  """Returns whether the LLM response contains meaningful, actionable content.
+
+  A response is considered to have meaningful content if it contains at least
+  one part with:
+  - An active function call or function response
+  - Executable code or a code execution result
+  - Inline data or file data
+  - Non-thought, non-whitespace text
+
+  Responses that are None, have no content, have empty parts, or contain only
+  thought parts (reasoning tokens) or whitespace-only text return False.
+
+  Args:
+    llm_response: The LLM response to check.
+
+  Returns:
+    True if the response contains meaningful content, False otherwise.
+  """
+  if (
+      not llm_response
+      or not llm_response.content
+      or not llm_response.content.parts
+  ):
+    return False
+
+  for part in llm_response.content.parts:
+    if part.function_call is not None:
+      return True
+    if part.function_response is not None:
+      return True
+    if part.executable_code is not None:
+      return True
+    if part.code_execution_result is not None:
+      return True
+    if part.inline_data is not None:
+      return True
+    if part.file_data is not None:
+      return True
+    is_thought = getattr(part, 'thought', False) or False
+    if not is_thought and part.text and part.text.strip():
+      return True
+
+  return False
+
+
 async def handle_before_model_callback(
     invocation_context: InvocationContext,
     llm_request: LlmRequest,

src/google/adk/flows/llm_flows/core/_model_call.py

@@ -27,13 +27,16 @@
 from ....agents.invocation_context import InvocationContext
 from ....agents.readonly_context import ReadonlyContext
 from ....events.event import Event
+from ....features import FeatureName
+from ....features import is_feature_enabled
 from ....live.live_request_queue import LiveRequestQueue
 from ....models.llm_request import LlmRequest
 from ....models.llm_response import LlmResponse
 from ....telemetry.tracing import trace_call_llm
 from ....telemetry.tracing import tracer
 from ....utils._runner_utils import _with_caller_context
 from ....utils.context_utils import Aclosing
+from ._finalizer import has_meaningful_content
 from ._utils import as_llm_agent as _as_llm_agent
 from ._utils import require_run_config as _require_run_config
 
@@ -47,19 +50,27 @@
 NO_CONTENT_ERROR_MESSAGE = (
     'The model returned no content (finish_reason=STOP with empty parts).'
 )
+NO_MEANINGFUL_CONTENT_ERROR_MESSAGE = (
+    'The model returned no actionable content (finish_reason=STOP with'
+    ' thought-only or whitespace-only parts).'
+)
 
 
 def apply_empty_response_policy(
     invocation_context: InvocationContext,
     llm_response: LlmResponse,
 ) -> None:
-  """Marks non-streaming empty STOP responses with NO_CONTENT_ERROR_CODE.
-
-  A non-streaming turn that finishes with STOP but has no content parts would
-  otherwise be skipped and become a silent empty final response; surface it as
-  an actionable error instead. Streaming is excluded because a terminal
-  finish-only chunk legitimately follows content already streamed in earlier
-  chunks.
+  """Marks terminal STOP responses that lack meaningful content as errors.
+
+  A turn that finishes with STOP but has no meaningful content (empty parts,
+  thought-only parts, or whitespace-only text) would otherwise be skipped or
+  treated as a complete answer; surface it as an actionable error instead.
+  In SSE streaming, progressive SSE aggregates the entire turn into a single
+  non-partial response, so a non-partial response carrying only thought or
+  whitespace parts represents a completed turn with no answer, whereas empty
+  parts (a terminal finish-only chunk) and non-progressive SSE (where the
+  aggregator emits a non-partial thought-only chunk before a function call)
+  are excluded.
 
   This must run before the response processors. Emptiness is a property of
   what the model returned, so it can only be judged before local processing
@@ -68,17 +79,27 @@ def apply_empty_response_policy(
   once it has run the code and emitted its result.
   """
   run_config = _require_run_config(invocation_context)
+  has_parts = bool(llm_response.content and llm_response.content.parts)
   if (
       not llm_response.partial
       and llm_response.error_code is None
       and llm_response.finish_reason == types.FinishReason.STOP
-      and (not llm_response.content or not llm_response.content.parts)
-      and run_config.streaming_mode != StreamingMode.SSE
+      and not has_meaningful_content(llm_response)
+      and (
+          run_config.streaming_mode != StreamingMode.SSE
+          or (
+              has_parts
+              and is_feature_enabled(FeatureName.PROGRESSIVE_SSE_STREAMING)
+          )
+      )
   ):
     llm_response.error_code = NO_CONTENT_ERROR_CODE
-    llm_response.error_message = (
-        llm_response.error_message or NO_CONTENT_ERROR_MESSAGE
+    default_message = (
+        NO_MEANINGFUL_CONTENT_ERROR_MESSAGE
+        if has_parts
+        else NO_CONTENT_ERROR_MESSAGE
     )
+    llm_response.error_message = llm_response.error_message or default_message
 
 
 async def resolve_llm(invocation_context: InvocationContext) -> BaseLlm:

src/google/adk/models/lite_llm.py

@@ -3573,6 +3573,7 @@ async def generate_content_async(
       usage_metadata = None
       grounding_metadata = None
       last_finish_reason: str | None = None
+      last_model_version: str | None = None
       fallback_index = 0
       multiple_choices_logged = False
 
@@ -3688,6 +3689,8 @@ def _reset_stream_buffers() -> None:
         last_finish_reason = None
 
       async for part in await self.llm_client.acompletion(**completion_args):
+        if getattr(part, "model", None):
+          last_model_version = part.model
         part_choices = part.get("choices") or []
         if not multiple_choices_logged and (
             len(part_choices) > 1
@@ -3828,36 +3831,33 @@ def _reset_stream_buffers() -> None:
       # the provider actually sent rather than assuming a clean stop, so a
       # filtered stream reports the same finish_reason and error_code that the
       # non-streaming path reports.
+      resolved_model_version = last_model_version or effective_model
       if function_calls and not aggregated_llm_response_with_tool_call:
         aggregated_llm_response_with_tool_call = _finalize_tool_call_response(
-            model_version=part.model,
+            model_version=resolved_model_version,
             finish_reason=last_finish_reason or "tool_calls",
         )
         _reset_stream_buffers()
 
       if (text_parts or reasoning_parts) and not aggregated_llm_response:
         aggregated_llm_response = _finalize_text_response(
-            model_version=part.model,
+            model_version=resolved_model_version,
             finish_reason=last_finish_reason or "stop",
         )
         _reset_stream_buffers()
       elif (
           not aggregated_llm_response
           and not aggregated_llm_response_with_tool_call
       ):
-        # The stream ended abnormally without ever producing content (an
-        # immediate content filter, or truncation before the first token).
-        # Non-streaming reports that as an error response; without this the
-        # generator ends having yielded nothing at all, so the reason, the
-        # error and the usage are all dropped and the caller sees a silent stop.
-        trailing_finish_reason = last_finish_reason or ""
-        if trailing_finish_reason and _map_finish_reason(
-            trailing_finish_reason
-        ) not in (None, types.FinishReason.STOP):
-          aggregated_llm_response = _finalize_text_response(
-              model_version=part.model,
-              finish_reason=trailing_finish_reason,
-          )
+        # The stream ended without ever producing content or tool calls (an
+        # immediate content filter, truncation before the first token, or a
+        # normal stop/tool_calls/function_call/EOF with empty deltas). Finalize
+        # an empty response so the finish_reason, error, and usage are
+        # preserved rather than ending the generator having yielded nothing.
+        aggregated_llm_response = _finalize_text_response(
+            model_version=resolved_model_version,
+            finish_reason=last_finish_reason or "stop",
+        )
 
       # waiting until streaming ends to yield the llm_response as litellm tends
       # to send chunk that contains usage_metadata after the chunk with

tests/unittests/flows/llm_flows/core/test_finalizer.py

@@ -456,3 +456,168 @@ async def failing_generator():
         failing_generator(), ctx, llm_request, event
     ):
       pass
+
+
+# --- Tests for has_meaningful_content ---
+
+
+def test_has_meaningful_content_none_response():
+  assert not _model_response_finalizer.has_meaningful_content(None)
+
+
+def test_has_meaningful_content_none_content():
+  resp = LlmResponse(content=None)
+  assert not _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_empty_parts():
+  resp = LlmResponse(content=types.Content(role="model", parts=[]))
+  assert not _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_thought_only():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[types.Part(text="Thinking about this...", thought=True)],
+      )
+  )
+  assert not _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_multiple_thoughts_only():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[
+              types.Part(text="Step 1...", thought=True),
+              types.Part(text="Step 2...", thought=True),
+          ],
+      )
+  )
+  assert not _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_whitespace_only():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[types.Part.from_text(text="   \n\t  ")],
+      )
+  )
+  assert not _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_empty_string():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[types.Part.from_text(text="")],
+      )
+  )
+  assert not _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_valid_text():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[types.Part.from_text(text="Hello world")],
+      )
+  )
+  assert _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_thought_and_valid_text():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[
+              types.Part(text="Thinking...", thought=True),
+              types.Part.from_text(text="Final answer."),
+          ],
+      )
+  )
+  assert _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_function_call():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[types.Part.from_function_call(name="search", args={})],
+      )
+  )
+  assert _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_function_response():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[types.Part.from_function_response(name="search", response={})],
+      )
+  )
+  assert _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_executable_code():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[
+              types.Part(
+                  executable_code=types.ExecutableCode(
+                      code="print(1)", language=types.Language.PYTHON
+                  )
+              )
+          ],
+      )
+  )
+  assert _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_code_execution_result():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[
+              types.Part(
+                  code_execution_result=types.CodeExecutionResult(
+                      outcome=types.Outcome.OUTCOME_OK, output="1"
+                  )
+              )
+          ],
+      )
+  )
+  assert _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_inline_data():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[
+              types.Part(
+                  inline_data=types.Blob(data=b"data", mime_type="image/png")
+              )
+          ],
+      )
+  )
+  assert _model_response_finalizer.has_meaningful_content(resp)
+
+
+def test_has_meaningful_content_file_data():
+  resp = LlmResponse(
+      content=types.Content(
+          role="model",
+          parts=[
+              types.Part(
+                  file_data=types.FileData(
+                      file_uri="gs://bucket/file", mime_type="application/pdf"
+                  )
+              )
+          ],
+      )
+  )
+  assert _model_response_finalizer.has_meaningful_content(resp)