docs(google): clarify Gemini 3.1 realtime limitations (#1198)

Author: rahulmanuwas

plugins/google/README.md

@@ -41,7 +41,9 @@ To use the Gemini realtime model or TTS (Beta)
 ```typescript
 import * as google from '@livekit/agents-plugin-google';
 
-const realtimeModel = new google.beta.realtime.RealtimeModel()
+const realtimeModel = new google.beta.realtime.RealtimeModel({
+  model: 'gemini-2.5-flash-native-audio-preview-12-2025',
+})
 const geminiTTS = new google.beta.TTS(),
 ```
 
@@ -60,6 +62,18 @@ const geminiTTS = new google.beta.TTS(),
 - `gemini-2.0-flash-exp` - Latest experimental model
 - And more (see models.ts for full list)
 
+### Realtime Model Notes
+
+- `gemini-3.1-flash-live-preview` is supported as a realtime model, but `generateReply()` is not currently compatible with it.
+- This matters for `voice.AgentSession` flows that rely on programmatic reply generation, such as explicit post-tool continuation, greetings, reconnect replies, and other server-triggered follow-up turns.
+- If your voice-agent flow depends on `generateReply()`, prefer a Gemini 2.5 native-audio live model for now.
+
+### Thinking Configuration
+
+- `thinkingConfig` is model-specific.
+- Gemini 3.1 live models use `thinkingLevel` such as `minimal`, `low`, `medium`, and `high`.
+- Gemini 2.5 live models use `thinkingBudget`.
+
 ### Advanced Configuration
 
 ```typescript

plugins/google/src/beta/realtime/realtime_api.ts

@@ -288,8 +288,8 @@ export class RealtimeModel extends llm.RealtimeModel {
       /**
        * Thinking configuration for native audio models.
        * If not set, the model's default thinking behavior is used.
-       * Use `\{ thinkingBudget: 0 \}` to disable thinking.
-       * Use `\{ thinkingBudget: -1 \}` for automatic/dynamic thinking.
+       * Gemini 3.1 live models use `thinkingLevel`.
+       * Gemini 2.5 live models use `thinkingBudget`.
        */
       thinkingConfig?: types.ThinkingConfig;
     } = {},
@@ -698,9 +698,11 @@ export class RealtimeSession extends llm.RealtimeSession {
   async generateReply(instructions?: string): Promise<llm.GenerationCreatedEvent> {
     if (this.options.model === 'gemini-3.1-flash-live-preview') {
       this.#logger.warn(
-        'generateReply is not compatible with gemini-3.1-flash-live-preview and will be ignored.',
+        'generateReply is not compatible with gemini-3.1-flash-live-preview. Use a Gemini 2.5 live model for voice-agent flows that require programmatic reply generation.',
+      );
+      throw new Error(
+        "generateReply is not compatible with 'gemini-3.1-flash-live-preview'; use a Gemini 2.5 live model for voice-agent flows that require programmatic reply generation.",
       );
-      throw new Error("generateReply is not compatible with 'gemini-3.1-flash-live-preview'");
     }
 
     if (this.pendingGenerationFut && !this.pendingGenerationFut.done) {

plugins/google/src/llm.ts

@@ -80,7 +80,7 @@ export class LLM extends llm.LLM {
    * @param presencePenalty - Penalizes the model for generating previously mentioned concepts. Defaults to undefined.
    * @param frequencyPenalty - Penalizes the model for repeating words. Defaults to undefined.
    * @param toolChoice - Specifies whether to use tools during response generation. Defaults to "auto".
-   * @param thinkingConfig - The thinking configuration for response generation. Defaults to undefined.
+   * @param thinkingConfig - The thinking configuration for response generation. Gemini 3.1 models use `thinkingLevel`; Gemini 2.5 models use `thinkingBudget`. Defaults to undefined.
    * @param automaticFunctionCallingConfig - The automatic function calling configuration for response generation. Defaults to undefined.
    * @param geminiTools - The Gemini-specific tools to use for the session.
    * @param httpOptions - The HTTP options to use for the session.