feat(live): allow Voice activity detection (VAD) events to be returned

Co-authored-by: Liang Wu <wuliang@google.com>
PiperOrigin-RevId: 944678774

Author: wuliang229

src/google/adk/agents/run_config.py

@@ -242,6 +242,9 @@ class RunConfig(BaseModel):
   realtime_input_config: Optional[types.RealtimeInputConfig] = None
   """Realtime input config for live agents with audio input from user."""
 
+  explicit_vad_signal: Optional[bool] = None
+  """Whether to enable explicit voice activity detection (VAD) signals from the model."""
+
   translation_config: Optional[types.TranslationConfig] = None
   """Configures real-time speech-to-speech translation.
 

src/google/adk/cli/api_server.py

@@ -1706,6 +1706,7 @@ async def run_agent_live(
         enable_affective_dialog: bool | None = Query(default=None),
         enable_session_resumption: bool | None = Query(default=None),
         save_live_blob: bool = Query(default=False),
+        explicit_vad_signal: bool | None = Query(default=None),
     ) -> None:
       resolved_app_name = app_name or self.default_app_name
       if not resolved_app_name:
@@ -1762,6 +1763,7 @@ async def forward_events():
                 else None
             ),
             save_live_blob=save_live_blob,
+            explicit_vad_signal=explicit_vad_signal,
         )
         async with Aclosing(
             runner.run_live(

src/google/adk/flows/llm_flows/base_llm_flow.py

@@ -1171,6 +1171,7 @@ async def _postprocess_live(
         and not llm_response.usage_metadata
         and not llm_response.live_session_resumption_update
         and not llm_response.grounding_metadata
+        and not llm_response.voice_activity
     ):
       return
 
@@ -1182,6 +1183,12 @@ async def _postprocess_live(
       yield model_response_event
       return
 
+    # Handle voice activity events
+    if llm_response.voice_activity:
+      model_response_event.voice_activity = llm_response.voice_activity
+      yield model_response_event
+      return
+
     # Handle transcription events ONCE per llm_response, outside the event loop
     if llm_response.input_transcription:
       model_response_event.input_transcription = (

src/google/adk/flows/llm_flows/basic.py

@@ -113,6 +113,9 @@ def _build_basic_request(
   llm_request.live_connect_config.realtime_input_config = (
       invocation_context.run_config.realtime_input_config
   )
+  llm_request.live_connect_config.explicit_vad_signal = (
+      invocation_context.run_config.explicit_vad_signal
+  )
   llm_request.live_connect_config.translation_config = (
       invocation_context.run_config.translation_config
   )

src/google/adk/models/gemini_llm_connection.py

@@ -602,6 +602,13 @@ async def receive(self) -> AsyncGenerator[LlmResponse, None]:
                   live_session_id=live_session_id,
               )
           )
+        if message.voice_activity:
+          logger.debug('Received voice activity: %s', message.voice_activity)
+          yield LlmResponse(
+              voice_activity=message.voice_activity,
+              model_version=self._model_version,
+              live_session_id=live_session_id,
+          )
         if message.go_away:
           logger.debug('Received GoAway message: %s', message.go_away)
           yield LlmResponse(

src/google/adk/models/llm_response.py

@@ -123,6 +123,9 @@ class LlmResponse(BaseModel):
   go_away: Optional[types.LiveServerGoAway] = None
   """The GoAway signal from the Live model."""
 
+  voice_activity: Optional[types.VoiceActivity] = None
+  """Voice activity signal from the Live model."""
+
   input_transcription: Optional[types.Transcription] = None
   """Audio transcription of user input."""
 

tests/unittests/cli/test_adk_web_server_run_live.py

@@ -106,6 +106,7 @@ async def _get_runner_async(_self, _app_name: str):
       "&enable_affective_dialog=true"
       "&enable_session_resumption=true"
       "&save_live_blob=true"
+      "&explicit_vad_signal=true"
   )
 
   with client.websocket_connect(url) as ws:
@@ -120,23 +121,27 @@ async def _get_runner_async(_self, _app_name: str):
   assert run_config.session_resumption is not None
   assert run_config.session_resumption.transparent is True
   assert run_config.save_live_blob is True
+  assert run_config.explicit_vad_signal is True
 
 
 @pytest.mark.parametrize(
     (
         "query,expected_enable_affective,expected_proactive_audio,"
-        "expected_session_resumption_transparent,expected_save_live_blob"
+        "expected_session_resumption_transparent,expected_save_live_blob,"
+        "expected_explicit_vad_signal"
     ),
     [
-        ("", None, None, None, False),
-        ("&proactive_audio=true", None, True, None, False),
-        ("&proactive_audio=false", None, False, None, False),
-        ("&enable_affective_dialog=true", True, None, None, False),
-        ("&enable_affective_dialog=false", False, None, None, False),
-        ("&enable_session_resumption=true", None, None, True, False),
-        ("&enable_session_resumption=false", None, None, False, False),
-        ("&save_live_blob=true", None, None, None, True),
-        ("&save_live_blob=false", None, None, None, False),
+        ("", None, None, None, False, None),
+        ("&proactive_audio=true", None, True, None, False, None),
+        ("&proactive_audio=false", None, False, None, False, None),
+        ("&enable_affective_dialog=true", True, None, None, False, None),
+        ("&enable_affective_dialog=false", False, None, None, False, None),
+        ("&enable_session_resumption=true", None, None, True, False, None),
+        ("&enable_session_resumption=false", None, None, False, False, None),
+        ("&save_live_blob=true", None, None, None, True, None),
+        ("&save_live_blob=false", None, None, None, False, None),
+        ("&explicit_vad_signal=true", None, None, None, False, True),
+        ("&explicit_vad_signal=false", None, None, None, False, False),
     ],
 )
 def test_run_live_defaults_and_individual_options(
@@ -145,6 +150,7 @@ def test_run_live_defaults_and_individual_options(
     expected_proactive_audio: bool | None,
     expected_session_resumption_transparent: bool | None,
     expected_save_live_blob: bool,
+    expected_explicit_vad_signal: bool | None,
 ):
   session_service = InMemorySessionService()
   asyncio.run(
@@ -210,6 +216,7 @@ async def _get_runner_async(_self, _app_name: str):
         is expected_session_resumption_transparent
     )
   assert run_config.save_live_blob is expected_save_live_blob
+  assert run_config.explicit_vad_signal is expected_explicit_vad_signal
 
 
 _WS_BASE_URL = (

tests/unittests/flows/llm_flows/test_base_llm_flow.py

@@ -1826,3 +1826,34 @@ async def test_postprocess_live_skips_none_function_response_event():
     ]
 
   assert all(event is not None for event in events)
+
+
+@pytest.mark.asyncio
+async def test_postprocess_live_voice_activity_events():
+  """Test that _postprocess_live yields voice activity events."""
+  agent = Agent(name='test_agent', model='gemini-2.0-flash')
+  invocation_context = await testing_utils.create_invocation_context(
+      agent=agent
+  )
+  flow = BaseLlmFlowForTesting()
+
+  vad = types.VoiceActivity(
+      voice_activity_type=types.VoiceActivityType.ACTIVITY_START,
+      audio_offset='1.5s',
+  )
+  llm_response = LlmResponse(voice_activity=vad)
+  model_response_event = Event(
+      invocation_id=invocation_context.invocation_id,
+      author=agent.name,
+  )
+  llm_request = LlmRequest(model='gemini-2.0-flash')
+
+  events = [
+      event
+      async for event in flow._postprocess_live(
+          invocation_context, llm_request, llm_response, model_response_event
+      )
+  ]
+
+  assert len(events) == 1
+  assert events[0].voice_activity == vad