AgoraIO · seymourtang · Sep 16, 2026 · Sep 15, 2026 · Sep 15, 2026 · Sep 15, 2026
diff --git a/README.md b/README.md
@@ -181,6 +181,7 @@ Use `with_mllm()` for OpenAI Realtime, Gemini Live, Vertex AI, or xAI Grok. No S
 
 ```python
 from agora_agent import Agent, Agora, Area, OpenAIRealtime
+import os
 import time
 
 client = Agora(

diff --git a/changelog.md b/changelog.md
@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [v2.9.0] — 2026-09-15
+
+### Added
+
+- **Gemini 3.8 Live MLLM** — `GeminiLive` now supports `models/gemini-3.8-live` and `models/gemini-3.8-live-extended-thinking`. The standard Live model is the default; Extended Thinking accepts `low`, `medium`, or `high` through `thinking_level`.
+
+### Changed
+
+- **Gemini Live routing and credentials** — Gemini 3.8 sessions use the preview gateway with `agora-feature: gemini-live`, send the Google credential as top-level `mllm.api_key`, and keep older Gemini Live model IDs on the production route.
+- **Gemini Live documentation** — The vendor reference and MLLM guide document the existing `GeminiLive` API for both 3.8 models and the Extended Thinking level.
+
 ## [v2.8.1] — 2026-09-11
 
 ### Changed

diff --git a/compat/agora-agent-server-sdk/pyproject.toml b/compat/agora-agent-server-sdk/pyproject.toml
@@ -3,7 +3,7 @@ name = "agora-agent-server-sdk"
 
 [tool.poetry]
 name = "agora-agent-server-sdk"
-version = "v2.8.1"
+version = "v2.9.0"
 description = "Compatibility shim for the renamed agora-agents package."
 readme = "README.md"
 authors = []
@@ -35,7 +35,7 @@ Repository = 'https://github.com/AgoraIO/agora-agents-python'
 
 [tool.poetry.dependencies]
 python = "^3.8"
-agora-agents = ">=2.8.1,<3.0.0"
+agora-agents = ">=2.9.0,<3.0.0"
 
 [build-system]
 requires = ["poetry-core"]

diff --git a/docs/concepts/vendors.md b/docs/concepts/vendors.md
@@ -160,7 +160,7 @@ Used with `agent.with_mllm()` for the [MLLM flow](../guides/mllm-flow.md). These
 | `OpenAIRealtime` | OpenAI Realtime | Global | `api_key`; optional `turn_detection` |
 | `OpenAIGPTLive` | OpenAI GPT Live | Global | `api_key`; optional `greeting` |
 | `AzureOpenAIRealtime` | Azure OpenAI Realtime | Global | `api_key`, `url`, `turn_detection`; optional `max_history` |
-| `GeminiLive` | Google Gemini Live API | Global | `api_key`, `model`; optional `turn_detection` |
+| `GeminiLive` | Google Gemini Live API | Global | `api_key`; `model` defaults to `models/gemini-3.8-live`. The two 3.8 IDs use preview routing; older IDs use production. |
 | `VertexAI` | Vertex AI (Gemini Live) | Global | `model`, `project_id`, `location`, `adc_credentials_string`; optional `turn_detection` |
 | `XaiGrok` | xAI Grok (`mllm.vendor`: `xai`) | Global | `api_key`; optional `voice`, `language`, `sample_rate`, `turn_detection` |
 | `QwenOmni` | Alibaba Cloud Qwen Omni Realtime | CN | `api_key`, `url`; optional `turn_detection` |

diff --git a/docs/guides/mllm-flow.md b/docs/guides/mllm-flow.md
@@ -95,6 +95,8 @@ asyncio.run(main())
 
 ## Gemini Live
 
+Use `GeminiLive` for the existing Gemini Live models and both Gemini 3.8 models. The 3.8 IDs select the preview route automatically; Extended Thinking also accepts `thinking_level`. See the [Preview Endpoint guide](./preview-endpoint.md).
+
 Gemini Live uses a Google AI API key:
 
 ```python

diff --git a/docs/guides/preview-endpoint.md b/docs/guides/preview-endpoint.md
@@ -28,6 +28,14 @@ agent_id = session.start()
 Preview providers use the preview base URL and `agora-feature` gate. A session using `GeminiSTT` or GPT Live uses the
 client's normal GA regional endpoint without that header.
 
+Use the single `GeminiLive(api_key=..., model=...)` class with `with_mllm`.
+The model IDs are `models/gemini-3.8-live` and
+`models/gemini-3.8-live-extended-thinking`; the low-latency ID is the default.
+Set `thinking_level="medium"` for extended thinking. `GeminiLive` sends it
+only for the extended-thinking ID. The Gemini
+credential is sent once as `mllm.api_key`, never as `mllm.params.api_key`.
+Gemini sessions send `agora-feature: gemini-live`; GPT Live uses the production gateway without a preview header.
+
 ## Session-scoped routing
 
 Preview routing does not mutate the bound `Agora` or `AsyncAgora` client. A session that needs a preview feature
@@ -37,7 +45,7 @@ receives private generated clients configured with:
 - `agora-feature` as the feature gate header.
 - All custom headers, authentication settings, timeouts, and the supplied `httpx` client from the original client.
 
-The gate header is applied after caller-provided headers, so it cannot be accidentally blanked or replaced. It is
+The gate header is applied after caller-provided and per-call headers, so it cannot be accidentally blanked or replaced. It is
 kept on every request made through that session. Production sessions created from the same client continue using
 the regional production endpoint.
 

diff --git a/docs/index.md b/docs/index.md
@@ -54,6 +54,7 @@ The Agora Conversational AI Python SDK lets you build voice-powered AI agents on
 | [Pagination](./guides/pagination.md) | Iterate over paginated list endpoints |
 | [Advanced](./guides/advanced.md) | Raw response, retries, timeouts, custom httpx client |
 | [Low-Level API](./guides/low-level-api.md) | Generated REST APIs |
+| [Preview Endpoint](./guides/preview-endpoint.md) | `AgoraPreview`, the `agora-feature` gate header, and preview routing |
 | [Client Reference](./reference/client.md) | Full `Agora` / `AsyncAgora` API |
 | [Agent Reference](./reference/agent.md) | Full `Agent` builder API |
 | [Session Reference](./reference/session.md) | Full `AgentSession` / `AsyncAgentSession` API |

diff --git a/docs/reference/vendors.md b/docs/reference/vendors.md
@@ -1013,14 +1013,18 @@ CN Alibaba Cloud Qwen Omni Realtime vendor (`mllm.vendor`: `"qwen_omni"`). Impor
 
 ### `GeminiLive`
 
+`GeminiLive` supports existing Gemini Live models and both public Gemini 3.8 voice models. The 3.8 IDs select the preview gateway with `agora-feature: gemini-live`; older model IDs keep the production route. See [Preview Endpoint](../guides/preview-endpoint.md).
+
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `api_key` | `str` | Yes | — | Google Gemini API key |
-| `model` | `str` | Yes | — | Gemini Live model name |
-| `url` | `str` | No | `None` | Custom WebSocket URL |
+| `model` | `str` | No | `models/gemini-3.8-live` | Gemini Live model name |
+| `thinking_level` | `str` | No | `None` | `low`, `medium`, or `high`; sent only for 3.8 Extended Thinking |
+| `language_codes` | `List[str]` | No | `None` | 3.8 language codes in `mllm.params.language_codes` |
+| `url` | `str` | No | `None` | Custom endpoint; 3.8 defaults to the Gemini Developer API host |
 | `instructions` | `str` | No | `None` | System instructions |
 | `voice` | `str` | No | `None` | Voice name |
-| `greeting_message` | `str` | No | `None` | Greeting message |
+| `greeting_message` | `str` | No | `None` | Greeting message; sent as `mllm.greeting` for 3.8 models |
 | `failure_message` | `str` | No | `None` | Message played when the model call fails |
 | `input_modalities` | `List[str]` | No | `None` | Input modalities |
 | `output_modalities` | `List[str]` | No | `None` | Output modalities |

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,9 +1,10 @@
 [project]
 name = "agora-agents"
+dynamic = ["version"]
 
 [tool.poetry]
 name = "agora-agents"
-version = "v2.8.1"
+version = "v2.9.0"
 description = ""
 readme = "README.md"
 authors = []

diff --git a/src/agora_agent/__init__.py b/src/agora_agent/__init__.py
@@ -49,6 +49,8 @@
         GeminiSTT,
         GeminiSTTModels,
         GeminiLive,
+        GeminiLiveModels,
+        GEMINI_MLLM_DEFAULT_MODEL,
         GenericAvatar,
         GenericTTS,
         GoogleSTT,

diff --git a/src/agora_agent/agentkit/__init__.py b/src/agora_agent/agentkit/__init__.py
@@ -155,6 +155,7 @@
     OpenAITtsPresetModels,
     normalize_preset_input,
 )
+from .preview import GeminiLiveModels, GEMINI_MLLM_DEFAULT_MODEL
 from .vendors import (
     AkoolAvatar,
     AmazonBedrock,
@@ -395,6 +396,8 @@
     "BaseSTT",
     "BaseMLLM",
     "OpenAIGPTLive",
+    "GeminiLiveModels",
+    "GEMINI_MLLM_DEFAULT_MODEL",
     "BaseAvatar",
     "SampleRate",
     "ElevenLabsSampleRate",

diff --git a/src/agora_agent/agentkit/agent.py b/src/agora_agent/agentkit/agent.py
@@ -893,7 +893,7 @@ def create_session(
         if resolved_client is None:
             raise ValueError("client is required. Pass client=... to Agent(...).")
 
-        session_name = name or f"agent-{int(time.time())}"
+        session_name = name or f"agent-{time.time_ns()}"
         return AgentSession(
             client=resolved_client,
             agent=self,
@@ -940,7 +940,7 @@ def create_async_session(
         if resolved_client is None:
             raise ValueError("client is required. Pass client=... to Agent(...).")
 
-        session_name = name or f"agent-{int(time.time())}"
+        session_name = name or f"agent-{time.time_ns()}"
         return AsyncAgentSession(
             client=resolved_client,
             agent=self,

diff --git a/src/agora_agent/agentkit/agent_session.py b/src/agora_agent/agentkit/agent_session.py
@@ -43,7 +43,7 @@
     normalize_preset_input,
     resolve_session_presets,
 )
-from .preview.client import create_preview_session_clients, required_preview_features
+from .preview.client import apply_preview_shape, create_preview_session_clients, required_preview_features
 from .token import _parse_numeric_uid, generate_convo_ai_token
 
 
@@ -632,6 +632,7 @@ def start(self) -> str:
                 properties,
             )
 
+            apply_preview_shape(resolved_properties)
             self._bind_session_clients(required_preview_features(resolved_properties))
 
             if self._debug:
@@ -999,6 +1000,7 @@ async def start(self) -> str:
                 properties,
             )
 
+            apply_preview_shape(resolved_properties)
             self._bind_session_clients(required_preview_features(resolved_properties))
 
             if self._debug:

diff --git a/src/agora_agent/agentkit/preview/__init__.py b/src/agora_agent/agentkit/preview/__init__.py
@@ -9,12 +9,18 @@
     PREVIEW_FEATURE_HEADER,
     PreviewFeature,
     PreviewFeatures,
+    apply_preview_shape,
     create_preview_session_clients,
     required_preview_features,
 )
 from .vendors import (
+    GEMINI_MLLM_DEFAULT_MODEL,
+    GEMINI_PREVIEW_MLLM_URL,
+    GEMINI_THINKING_LEVELS,
+    GeminiLiveModels,
     GeminiSTT,
     GeminiSTTModels,
+    GeminiThinkingLevel,
     OpenAIGPTLive,
 )
 
@@ -24,6 +30,12 @@
     "GeminiSTTModels",
     "GeminiSTT",
     "OpenAIGPTLive",
+    "GEMINI_MLLM_DEFAULT_MODEL",
+    "GEMINI_PREVIEW_MLLM_URL",
+    "GEMINI_THINKING_LEVELS",
+    "GeminiLiveModels",
+    "GeminiThinkingLevel",
+    "apply_preview_shape",
     "PreviewFeature",
     "PreviewFeatures",
     "create_preview_session_clients",