digitallysavvy · Aug 21, 2026 · Sep 14, 2026 · Sep 14, 2026 · Sep 15, 2026 · Sep 15, 2026
diff --git a/.fernignore b/.fernignore
@@ -31,3 +31,16 @@ requirements.txt
 .fern/replay.lock
 .fern/replay.yml
 .gitattributes
+
+# Additive v3 preview adapter and typed staging contracts are maintained manually.
+src/agora_agent/v3/
+
+# Public token-only policy and transport enforcement are maintained manually.
+src/agora_agent/client.py
+src/agora_agent/core/public_auth.py
+src/agora_agent/core/http_client.py
+src/agora_agent/core/client_wrapper.py
+
+# Shared corrected release contract, local preview generation input/handoff.
+openapi.json
+openapi.yaml
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -102,30 +102,12 @@ jobs:
 
       - name: Verify package versions match release tag
         run: |
-          TAG_VERSION="${GITHUB_REF_NAME#v}"
-          ROOT_VERSION="$(poetry version -s | sed 's/^v//')"
-          COMPAT_VERSION="$(cd compat/agora-agent-server-sdk && poetry version -s | sed 's/^v//')"
-          COMPAT_DEP_VERSION="$(python -c "import re, sys; from pathlib import Path; text = Path('compat/agora-agent-server-sdk/pyproject.toml').read_text(); match = re.search(r'^agora-agents\s*=\s*\"([^\"]+)\"', text, re.M); sys.exit('agora-agents dependency not found in compat pyproject.toml') if not match else None; print(match.group(1))")"
-
-          if [ "$ROOT_VERSION" != "$TAG_VERSION" ]; then
-            echo "Root package version ($ROOT_VERSION) does not match tag version ($TAG_VERSION)."
-            exit 1
-          fi
-
-          if [ "$COMPAT_VERSION" != "$TAG_VERSION" ]; then
-            echo "Compat package version ($COMPAT_VERSION) does not match tag version ($TAG_VERSION)."
-            exit 1
-          fi
-
-          if [ "$COMPAT_DEP_VERSION" != ">=${TAG_VERSION},<3.0.0" ]; then
-            echo "Compat package dependency on agora-agents ($COMPAT_DEP_VERSION) does not match >=${TAG_VERSION},<3.0.0."
-            exit 1
-          fi
+          poetry run python scripts/check_release_workflow.py --tag "$GITHUB_REF_NAME"
 
       - name: Publish primary package to pypi
         run: |
           PACKAGE_NAME="agora-agents"
-          PACKAGE_VERSION="${GITHUB_REF_NAME#v}"
+          PACKAGE_VERSION="$(poetry version -s | sed 's/^v//')"
           STATUS="$(curl -sS -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/${PACKAGE_NAME}/${PACKAGE_VERSION}/json")"
           case "$STATUS" in
             200)
@@ -146,7 +128,7 @@ jobs:
 
       - name: Wait for primary package on PyPI
         run: |
-          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          TAG_VERSION="$(poetry version -s | sed 's/^v//')"
           PACKAGE="agora-agents"
           for attempt in $(seq 1 12); do
             if curl -fsS "https://pypi.org/pypi/${PACKAGE}/${TAG_VERSION}/json" >/dev/null; then
@@ -162,7 +144,7 @@ jobs:
       - name: Publish compatibility package to pypi
         run: |
           PACKAGE_NAME="agora-agent-server-sdk"
-          PACKAGE_VERSION="${GITHUB_REF_NAME#v}"
+          PACKAGE_VERSION="$(poetry version -s | sed 's/^v//')"
           STATUS="$(curl -sS -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/${PACKAGE_NAME}/${PACKAGE_VERSION}/json")"
           case "$STATUS" in
             200)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -45,8 +45,10 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: |
           TAG="${RELEASE_TAG}"
+          PRERELEASE=false
+          if [[ "$TAG" == *-* ]]; then PRERELEASE=true; fi
           if gh release view "$TAG" >/dev/null 2>&1; then
-            gh release edit "$TAG" --title "$TAG" --notes-file release_notes.md
+            gh release edit "$TAG" --title "$TAG" --notes-file release_notes.md --prerelease="$PRERELEASE"
           else
-            gh release create "$TAG" --title "$TAG" --notes-file release_notes.md
+            gh release create "$TAG" --title "$TAG" --notes-file release_notes.md --prerelease="$PRERELEASE"
           fi
diff --git a/README.md b/README.md
@@ -7,20 +7,34 @@ The Agora Conversational AI SDK provides convenient access to the Agora Conversa
 enabling you to build voice-powered AI agents with support for both cascading flows (ASR -> LLM -> TTS) 
 and multimodal flows (MLLM) for real-time audio processing.
 
+## Run or save the same agent configuration
+
+Use one `Agent` builder to configure providers, then call `create_ephemeral_session(...).start()` for an explicit Platform session or `create_session(...).start()` for a running session or `save()` for a `SavedAgent`. Async applications use `create_async_ephemeral_session()`, `create_async_session()` and `save_async()`. A saved handle owns `update(config)`, deletion, number assignment/unassignment, and client-side `list_numbers()` scans. Use `client.secrets` and `client.numbers` for provisioning, with explicit `secret_ref()` credentials for saved BYOK agents (inline keys remain valid for ephemeral sessions) and immutable `with_variable()` definitions for saved configurations.
+
+Saving and project provisioning are part of SDK preview `3.0.0a3`. Existing session behavior is preserved. Saved agents and preview ephemeral sessions support cascaded ASR/LLM/TTS only; MLLM remains available for existing inline sessions. See the [daily agent workflow](docs/guides/agent-workflow.md), [persistence transport guide](docs/guides/v3-api-preview.md), and [advanced 32-operation reference](docs/reference/v3.md) for ETags, cursor pagination, session lifecycle, limited token/messages/provider-params updates, and project queries. The shared release contract is available as [openapi.yaml](openapi.yaml). `deploy` / `DeployedAgent` remain compatibility names. Saved handles also create sessions by ID; configurations with secret references or variable definitions start ephemeral sessions. Use `client.campaigns` for typed campaign create/list/get/update/delete/pause/resume/cancel operations. REST authentication supports `auth_token`, tokens signed from App ID/App Certificate, or Basic authentication through `customer_id` and `customer_secret`. Internal gateway headers remain unsupported. The new default origin is `https://preview.ai.agora.io`, with `/conversational-ai/v1/projects/{appid}`.
+
 ## Install
 
 ```sh
-pip install agora-agents
+pip install agora-agents==3.0.0a3
+```
+
+For source checkouts on Windows, use a short path and enable Git long paths before checkout:
+
+```sh
+git clone -c core.longpaths=true https://github.com/AgoraIO/agora-agents-python.git C:/src/agora-python
 ```
 
+The generated legacy modules retain their public import names, including long filenames. A default Windows checkout in a deeply nested folder can still exceed OS/tool limits; installing the wheel avoids Git checkout limits.
+
 ## Requirements
 
 - Python 3.8+
 
 ## Quick Start
 
 Start with the `Agent` builder: create a client with app credentials, pass it to `Agent(client=client, ...)`, choose your ASR, LLM, and TTS providers, then start a session. Omit vendor API keys for supported Agora-managed global models, or provide keys when you want BYOK.
-Set Agora interaction language with `turn_detection.language`; provider-specific STT language values remain under `asr.params`. Ares uses only the REST `asr.language` value sourced from `turn_detection.language`.
+For Platform sessions, vendor STT language maps to `pipeline.asr.language`; explicit `turn_detection.language` overrides it. Ares defaults to `en-US`. Existing Voice Agent sessions retain their language mapping.
 
 ```python
 import os
@@ -167,7 +181,7 @@ agent = Agent(client=client, turn_detection={"language": "en-US"}).with_stt(
 )
 ```
 
-Migrating from `agora-agent-server-sdk` on PyPI? Use `pip install agora-agents`; imports stay `agora_agent` — see [changelog migration notes](./changelog.md#migration-notes) or [installation guide](./docs/getting-started/installation.md#migrating-from-a-previous-package-name).
+Migrating from `agora-agent-server-sdk` on PyPI? Use `pip install agora-agents==3.0.0a3`; imports stay `agora_agent` — see [changelog migration notes](./changelog.md#migration-notes) or [installation guide](./docs/getting-started/installation.md#migrating-from-a-previous-package-name).
 
 ## BYOK
 
@@ -207,6 +221,21 @@ session = agent.create_session(
 session.start()
 ```
 
+For Gemini 3.8 Live Extended Thinking, use the same single `GeminiLive` class as the regular Live model:
+
+```python
+from agora_agent import GeminiLive
+
+gemini_agent = Agent(client=client).with_mllm(GeminiLive(
+    api_key=os.environ["GOOGLE_API_KEY"],
+    model="models/gemini-3.8-live-extended-thinking",
+    thinking_level="medium",
+    greeting_message="Hello! Ready to chat.",
+))
+```
+
+Use `models/gemini-3.8-live` without `thinking_level` for the lower-latency model. Gemini sessions use the preview gateway and `agora-feature: gemini-live`; the Google key is sent as `mllm.api_key`. See the [Preview Endpoint guide](./docs/guides/preview-endpoint.md).
+
 See the [MLLM Flow guide](./docs/guides/mllm-flow.md) for full examples with Gemini Live and Vertex AI.
 
 ## Documentation

diff --git a/changelog.md b/changelog.md
@@ -4,6 +4,34 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [v3.0.0-alpha.3] — 2026-10-30
+
+- Support Basic REST authentication with `customer_id`/`customer_secret` alongside Token007 authentication in synchronous and asynchronous clients. Optional App Certificate signing remains available for RTC transport tokens.
+
+- Include the ConvoAI service in SDK-generated authorization tokens by integrating the latest production token builder fix. Regression tests verify service grants, signatures and sync/async Platform session request headers.
+- Preserve ASR provider language parameters for AssemblyAI, Google, Microsoft, Sarvam and Speechmatics, alongside the interaction language.
+- Default Sarvam TTS to `bulbul:v3`, preserving explicit model overrides.
+- Reject malformed App ID/certificate values, including whitespace.
+
+## [v3.0.0-alpha.2] — 2026-10-29
+
+- Correct Platform provider IDs, Gemini and Bedrock credentials, ASR language/keywords/endpoints, and HeyGen mapping. Managed OpenAI model availability is validated by the service.
+- Add explicit ephemeral-session and outbound-call helpers, full inbound call policies, RTC token generation for fixed numeric UIDs, Azure resource names, optional session analysis and secret-key metadata.
+- Fix Pydantic import configuration warnings and document Windows source checkout requirements.
+- Preserve Gemini credentials during endpoint normalization and capture RTC signing identity per session. Retain generated RTC tokens across failed-start retries, refresh them for new unkeyed session lifecycles, and leave unsupported UIDs to server provisioning.
+
+## [v3.0.0-alpha.1] — 2026-10-28
+
+- Shared root OpenAPI JSON/YAML, local reproducible wire generator, sync/async/raw session PATCH, and cascaded-only preview contracts.
+- Realtime/MLLM configurations and runtime updates are rejected by preview APIs before network access; existing inline MLLM sessions remain supported.
+- BYOK `credential.fields` preserves vendor credential names; saved writes require explicit secret references, ephemeral sessions permit inline values.
+- Optional RTC UID, inbound/voicemail end-call policies, SIP IPv4 allowlists, campaign create retention, 50,000-contact / 10 MiB limits. Removed campaign retry fields are rejected.
+- Six idempotent POST operations use optional 1–256 visible ASCII keys, 24-hour replay and replay response headers. No automatic write retries or region availability gates.
+
+### Preview rollout
+
+The current stored-agent, session and campaign preview rollout is available in the US only (PM confirmation, 2026-10-27). Availability may expand as rollout progresses.
+
 ## [v2.13.0] — 2026-10-29
 
 ### Added

diff --git a/compat/agora-agent-server-sdk/README.md b/compat/agora-agent-server-sdk/README.md
@@ -5,7 +5,7 @@ This package has been renamed to `agora-agents`.
 New projects should install:
 
 ```sh
-pip install agora-agents
+pip install agora-agents==3.0.0a3
 ```
 
 This compatibility package re-exports the public API from `agora-agents` to support existing installs during the migration window. The primary import path remains `agora_agent`; you can also import from `agora_agent_server_sdk_compat`:
@@ -16,3 +16,5 @@ from agora_agent_server_sdk_compat import Agora, Area
 ```
 
 Maintainers: dual-publish steps live in the repository release workflow, not in the root README.
+
+The shim exposes features from the installed `agora-agents` version; it does not independently add API support. The [v3 stored-agent preview](../../docs/guides/v3-api-preview.md) is included in preview `3.0.0a3`. Existing v2 imports remain available.
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.13.0"
+version = "3.0.0a3"
 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.13.0,<3.0.0"
+agora-agents = ">=3.0.0a3,<4.0.0"
 
 [build-system]
 requires = ["poetry-core"]

diff --git a/docs/concepts/agent.md b/docs/concepts/agent.md
@@ -8,6 +8,8 @@ description: The Agent builder — configure an AI agent with LLM, TTS, STT, and
 
 The `Agent` class is a fluent builder for configuring AI agent properties. Pass a bound `Agora` or `AsyncAgora` client with `client=...` — it is required for `create_session()` and `create_async_session()`. The builder collects vendor settings (LLM, TTS, STT, MLLM, avatar) and produces a fully configured `AgentSession` when you call `create_session()`. The agent instance name is set on `create_session(name=...)`, not on the `Agent` constructor.
 
+In the [v3 preview](../guides/v3-api-preview.md), the same local builder can save a stored configuration with `save()` / `save_async()`. Its stored name is passed to deploy, and the returned handle manages inbound-number assignments. This does not start a session or change the v2 `create_session()` lifecycle. Secret references require deployment; they cannot be sent to v2 sessions.
+
 ## Constructor
 
 <!-- snippet: executable -->

diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md
@@ -41,7 +41,11 @@ This is the primary developer-facing API. It provides:
 
 ### Fern-Generated Layer
 
-The auto-generated core provides typed HTTP methods for every Agora API endpoint. You rarely need this directly, but it is accessible via `session.raw` for advanced use cases or new endpoints that the agentkit layer does not yet cover.
+The auto-generated core provides typed HTTP methods for the existing v2 API endpoints. You rarely need this directly, but it is accessible via `session.raw` for advanced use cases or new endpoints that the agentkit layer does not yet cover.
+
+### v3 Preview Adapter
+
+`client.v3` adds typed wire dictionaries and agents/secrets/numbers/session-read resources alongside the v2 generated clients. It reuses the pool client's HTTP transport and authentication, with separate staging origin/header overrides. This is protected custom/local-generated code rather than canonical Fern output. AgentKit adds `SavedAgent` / `AsyncSavedAgent` for persisted configurations; existing session handles remain v2. See [v3 workflows](../guides/v3-api-preview.md) and [reference](../reference/v3.md).
 
 ## Sync vs. Async
 
@@ -51,6 +55,7 @@ The SDK provides two parallel client hierarchies:
 |---|---|---|
 | `Agora` | `AsyncAgora` | `httpx.Client` / `httpx.AsyncClient` |
 | `AgentSession` | `AsyncAgentSession` | Blocking calls / Coroutines |
+| `SavedAgent` (preview) | `AsyncSavedAgent` (preview) | Stored configuration and number assignment calls |
 
 ### When to Use Each
 

diff --git a/docs/getting-started/authentication.md b/docs/getting-started/authentication.md
@@ -6,7 +6,7 @@ description: Configure the Python SDK with app credentials and understand other
 
 # Authentication
 
-Create `Agora` or `AsyncAgora` with `app_id` and `app_certificate` only. The SDK mints a fresh ConvoAI REST token for each API call and generates the RTC join token when the session starts.
+By default, create `Agora` or `AsyncAgora` with `app_id` and `app_certificate`. The SDK mints a fresh ConvoAI REST token for each API call and generates the RTC join token when the session starts.
 
 ## App credentials
 
@@ -50,35 +50,40 @@ session = agent.create_session(
 print(client.auth_mode)  # "app-credentials"
 ```
 
-## Legacy auth modes
+## Pre-built REST tokens
 
-The generated client still supports pre-minted REST tokens and HTTP Basic Auth for legacy integrations. Do not use those modes for new session integrations. Use app credentials so AgentKit can mint short-lived ConvoAI REST auth and RTC join tokens for each session.
+The SDK supports Token007 and Basic REST authentication. Pass a raw `auth_token`, let the SDK sign tokens from `app_id` and `app_certificate`, or configure a Customer ID/Secret pair. REST authentication is separate from the optional RTC transport token.
 
-### HTTP Basic Auth
+### Pre-built REST token
+
+Pass the raw token string. The SDK sets `Authorization: agora token=<auth_token>` automatically.
 
 ```python
 client = Agora(
     area=Area.US,
     app_id="your-app-id",
-    app_certificate="your-app-certificate",
-    customer_id="your-customer-id",
-    customer_secret="your-customer-secret",
+    auth_token="your-raw-token",  # No certificate needed for prebuilt REST auth.
 )
-print(client.auth_mode)  # "basic"
+print(client.auth_mode)  # "token"
 ```
 
-### Pre-built REST token
+New resources use `https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}`. Do not send internal gateway headers or `X-Studio-Region`.
 
-Pass the raw token string. The SDK sets `Authorization: agora token=<auth_token>` automatically.
+A client with only a REST `auth_token` or Basic credentials cannot generate RTC join tokens. Supply `token=` when starting an ordinary legacy RTC session, or also configure the App Certificate for RTC signing. Saved/ephemeral RTC sessions accept their optional token through `transport.token`.
+
+## Basic REST authentication
 
 ```python
 client = Agora(
     area=Area.US,
     app_id="your-app-id",
-    app_certificate="your-app-certificate",
-    auth_token="your-raw-token",
+    customer_id="your-customer-id",
+    customer_secret="your-customer-secret",
+    # app_certificate="your-app-certificate",  # Optional RTC token signing.
 )
-print(client.auth_mode)  # "token"
+print(client.auth_mode)  # "basic"
 ```
 
-`auth_token` is mutually exclusive with `customer_id` / `customer_secret`.
+The same options work with `AsyncAgora`. Both credentials must be nonempty, and Customer ID must not contain a colon. Do not combine them with `auth_token`. The SDK sends `Authorization: Basic <base64(customer_id:customer_secret)>` on REST requests, including saved-agent and ephemeral sessions. An optional App Certificate signs RTC tokens without replacing Basic REST authentication.
+
+For low-level overrides, a valid Basic `Authorization` header is accepted in request options. Configure credentials on the SDK client instead of attaching `httpx.BasicAuth` to the underlying HTTP client, which would silently override SDK authentication.
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -13,13 +13,13 @@ description: Install the Agora Conversational AI Python SDK.
 ## Install with pip
 
 ```sh
-pip install agora-agents
+pip install agora-agents==3.0.0a3
 ```
 
 ## Install with Poetry
 
 ```sh
-poetry add agora-agents
+poetry add agora-agents@3.0.0a3
 ```
 
 ## Imports
@@ -59,7 +59,7 @@ from agora_agent import AsyncAgora, AsyncAgentSession, Area
 | Package                        | Purpose                                                |
 | ------------------------------ | ------------------------------------------------------ |
 | `httpx` (>= 0.21.2)            | HTTP client for sync and async requests                |
-| `pydantic` (>= 1.9.2)          | Data validation for vendor configuration and API types |
+| `pydantic` (>= 2.7.1, < 3)     | Data validation for vendor configuration and API types |
 | `typing_extensions` (>= 4.0.0) | Backported type hints for Python 3.8+                  |
 
 ## Next steps