docs(google): note Gemini 3.1 instruction limitations

livekit-plugins/livekit-plugins-google/README.md

@@ -33,6 +33,13 @@ And these on Vertex AI:
 
 - gemini-live-2.5-flash-native-audio
 
+### Gemini 3.1 Live compatibility
+
+`gemini-3.1-flash-live-preview` does not reliably apply mid-session system instruction
+updates sent with `AgentSession.update_instructions()`. When dynamic context changes during a
+session, prefer starting a new session with the updated instructions or pass the context as
+user-visible conversation content instead of relying on a system-instruction update.
+
 References:
 
 - [Gemini API Models](https://ai.google.dev/gemini-api/docs/models)

livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py

@@ -63,6 +63,10 @@
 )
 
 
+def _is_gemini_31_live(model: str) -> bool:
+    return model.lower().startswith("gemini-3.1-") and "live" in model.lower()
+
+
 def _validate_model_api_match(model: str, use_vertexai: bool) -> None:
     """
     Validate that the model name matches the API being used.
@@ -484,6 +488,7 @@ def __init__(self, realtime_model: RealtimeModel) -> None:
         self._in_user_activity = False
         self._session_lock = asyncio.Lock()
         self._num_retries = 0
+        self._logged_gemini_31_instruction_warning = False
 
     async def _close_active_session(self) -> None:
         async with self._session_lock:
@@ -556,6 +561,17 @@ async def update_instructions(self, instructions: str) -> None:
                     return
 
             # Active session exists — send mid-session system instruction update (no reconnect needed)
+            if (
+                _is_gemini_31_live(self._opts.model)
+                and not self._logged_gemini_31_instruction_warning
+            ):
+                logger.warning(
+                    "Gemini 3.1 Live does not reliably support mid-session instruction "
+                    "updates; prefer starting a new session with updated instructions or "
+                    "passing dynamic context as user-visible conversation content."
+                )
+                self._logged_gemini_31_instruction_warning = True
+
             logger.debug("Updating instructions mid-session")
             self._send_client_event(
                 types.LiveClientContent(