fix(asr): update session handling and improve schema for GA integration (#2290)

* fix(asr): update session handling and improve schema for GA integration

* fix(asr): update OpenAI ASR extension to use GA Realtime API and improve session handling

---------

Co-authored-by: hanhandi <1540984562@qq.com>

Author: diyuyi-agora

ai_agents/agents/ten_packages/extension/openai_asr_python/docs/README.en-US.md

@@ -1,13 +1,13 @@
 # OpenAI ASR Python Extension
 
-A Python extension for OpenAI's Automatic Speech Recognition (ASR) service, providing real-time speech-to-text conversion capabilities with full async support using OpenAI's beta realtime API.
+A Python extension for OpenAI's Automatic Speech Recognition (ASR) service, providing real-time speech-to-text conversion capabilities with full async support using OpenAI's Realtime transcription API (GA).
 
 ## Features
 
 - **Full Async Support**: Built with complete asynchronous architecture for high-performance speech recognition
 - **Real-time Streaming**: Supports real-time audio streaming with low latency using OpenAI's WebSocket API
-- **OpenAI Beta API**: Uses OpenAI's beta realtime transcription API for cutting-edge performance
-- **Multiple Audio Formats**: Supports PCM16, G711 U-law, and G711 A-law audio formats
+- **OpenAI Realtime API**: Uses OpenAI's GA Realtime transcription API via `session.update`
+- **PCM16 Audio**: Accepts arbitrary input sample rates and resamples to 24 kHz PCM16 before sending
 - **Audio Dumping**: Optional audio recording for debugging and analysis
 - **Configurable Logging**: Adjustable log levels for debugging
 - **Error Handling**: Comprehensive error handling with detailed logging
@@ -37,26 +37,28 @@ The extension requires the following configuration parameters:
 
 ```json
 {
-  "api_key": "your_openai_api_key",
-  "organization": "your_organization_id",
-  "project": "your_project_id",
   "params": {
+    "api_key": "your_openai_api_key",
     "input_audio_format": "pcm16",
     "input_audio_transcription": {
-      "model": "whisper-1"
+      "model": "whisper-1",
+      "prompt": "",
+      "language": "en"
     },
     "turn_detection": {
-      "enabled": true
-    },
-    "input_audio_noise_reduction": {
-      "enabled": true
+      "type": "server_vad",
+      "threshold": 0.5,
+      "prefix_padding_ms": 300,
+      "silence_duration_ms": 500
     }
   },
   "dump": false,
   "log_level": "INFO"
 }
 ```
 
+Optional connection settings such as `organization`, `project`, and `base_url` belong under `params`.
+
 ## API
 
 The extension implements the `AsyncASRBaseExtension` interface and provides the following key methods:
@@ -144,9 +146,8 @@ The extension supports various OpenAI transcription models:
 
 ## Audio Format Support
 
-- **PCM16**: 16-bit PCM audio format
-- **G711 U-law**: G711 U-law compressed audio
-- **G711 A-law**: G711 A-law compressed audio
+- **PCM16** (recommended): The extension resamples incoming audio to 24 kHz PCM16 before sending to OpenAI. Set `input_audio_format` to `"pcm16"`.
+- **G711 U-law / A-law**: Accepted in configuration for forward compatibility, but the extension currently always sends resampled PCM16 regardless of this setting.
 
 ## Troubleshooting
 

ai_agents/agents/ten_packages/extension/openai_asr_python/docs/README.ja-JP.md

@@ -1,13 +1,13 @@
 # OpenAI ASR Python 拡張
 
-OpenAI の自動音声認識 (ASR) サービスのための Python 拡張で、OpenAI の beta リアルタイム API を使用してリアルタイム音声テキスト変換機能を提供し、完全な非同期操作をサポートします。
+OpenAI の自動音声認識 (ASR) サービスのための Python 拡張で、OpenAI Realtime 転写 API（GA）を使用してリアルタイム音声テキスト変換機能を提供し、完全な非同期操作をサポートします。
 
 ## 機能
 
 - **完全非同期サポート**: 高性能音声認識のための完全な非同期アーキテクチャで構築
 - **リアルタイムストリーミング**: OpenAI の WebSocket API を使用した低遅延リアルタイム音声ストリーミング
-- **OpenAI Beta API**: 最先端のパフォーマンスのための OpenAI の beta リアルタイム転写 API を使用
-- **複数の音声形式**: PCM16、G711 U-law、G711 A-law 音声形式をサポート
+- **OpenAI Realtime API**: GA 版 `session.update` 経由で OpenAI Realtime 転写 API を使用
+- **PCM16 音声**: 任意の入力サンプリングレートを受け付け、送信前に 24 kHz PCM16 にリサンプリング
 - **音声ダンプ**: デバッグと分析のためのオプション音声録音
 - **設定可能なログ**: デバッグのための調整可能なログレベル
 - **エラーハンドリング**: 詳細なログ記録による包括的なエラー処理
@@ -37,26 +37,28 @@ OpenAI の自動音声認識 (ASR) サービスのための Python 拡張で、O
 
 ```json
 {
-  "api_key": "your_openai_api_key",
-  "organization": "your_organization_id",
-  "project": "your_project_id",
   "params": {
+    "api_key": "your_openai_api_key",
     "input_audio_format": "pcm16",
     "input_audio_transcription": {
-      "model": "whisper-1"
+      "model": "whisper-1",
+      "prompt": "",
+      "language": "en"
     },
     "turn_detection": {
-      "enabled": true
-    },
-    "input_audio_noise_reduction": {
-      "enabled": true
+      "type": "server_vad",
+      "threshold": 0.5,
+      "prefix_padding_ms": 300,
+      "silence_duration_ms": 500
     }
   },
   "dump": false,
   "log_level": "INFO"
 }
 ```
 
+`organization`、`project`、`base_url` などのオプション接続パラメータは `params` 配下に配置します。
+
 ## API
 
 拡張は `AsyncASRBaseExtension` インターフェースを実装し、以下の主要メソッドを提供します：
@@ -144,9 +146,8 @@ pytest tests/
 
 ## 音声形式サポート
 
-- **PCM16**: 16 ビット PCM 音声形式
-- **G711 U-law**: G711 U-law 圧縮音声
-- **G711 A-law**: G711 A-law 圧縮音声
+- **PCM16**（推奨）: 拡張は入力音声を 24 kHz PCM16 にリサンプリングしてから OpenAI に送信します。`input_audio_format` は `"pcm16"` に設定してください。
+- **G711 U-law / A-law**: 将来互換のため設定では受け付けますが、拡張は現在この設定に関わらず常にリサンプリング済み PCM16 を送信します。
 
 ## トラブルシューティング
 

ai_agents/agents/ten_packages/extension/openai_asr_python/docs/README.ko-KR.md

@@ -1,13 +1,13 @@
 # OpenAI ASR Python 확장
 
-OpenAI의 자동 음성 인식(ASR) 서비스를 위한 Python 확장으로, OpenAI의 beta 실시간 API를 사용하여 실시간 음성-텍스트 변환 기능을 제공하며 완전한 비동기 작업을 지원합니다.
+OpenAI의 자동 음성 인식(ASR) 서비스를 위한 Python 확장으로, OpenAI Realtime 전사 API(GA)를 사용하여 실시간 음성-텍스트 변환 기능을 제공하며 완전한 비동기 작업을 지원합니다.
 
 ## 기능
 
 - **완전한 비동기 지원**: 고성능 음성 인식을 위한 완전한 비동기 아키텍처로 구축
 - **실시간 스트리밍**: OpenAI의 WebSocket API를 사용한 낮은 지연 시간의 실시간 오디오 스트리밍
-- **OpenAI Beta API**: 최첨단 성능을 위한 OpenAI의 beta 실시간 전사 API 사용
-- **다중 오디오 형식**: PCM16, G711 U-law, G711 A-law 오디오 형식 지원
+- **OpenAI Realtime API**: GA `session.update`를 통해 OpenAI Realtime 전사 API 사용
+- **PCM16 오디오**: 임의의 입력 샘플링 레이트를 수용하며 전송 전 24 kHz PCM16으로 리샘플링
 - **오디오 덤프**: 디버깅 및 분석을 위한 선택적 오디오 녹음
 - **구성 가능한 로깅**: 디버깅을 위한 조정 가능한 로그 레벨
 - **오류 처리**: 상세한 로깅을 통한 포괄적인 오류 처리
@@ -37,26 +37,28 @@ OpenAI의 자동 음성 인식(ASR) 서비스를 위한 Python 확장으로, Ope
 
 ```json
 {
-  "api_key": "your_openai_api_key",
-  "organization": "your_organization_id",
-  "project": "your_project_id",
   "params": {
+    "api_key": "your_openai_api_key",
     "input_audio_format": "pcm16",
     "input_audio_transcription": {
-      "model": "whisper-1"
+      "model": "whisper-1",
+      "prompt": "",
+      "language": "en"
     },
     "turn_detection": {
-      "enabled": true
-    },
-    "input_audio_noise_reduction": {
-      "enabled": true
+      "type": "server_vad",
+      "threshold": 0.5,
+      "prefix_padding_ms": 300,
+      "silence_duration_ms": 500
     }
   },
   "dump": false,
   "log_level": "INFO"
 }
 ```
 
+`organization`, `project`, `base_url` 등 선택적 연결 매개변수는 `params` 아래에 둡니다.
+
 ## API
 
 확장은 `AsyncASRBaseExtension` 인터페이스를 구현하고 다음 주요 메서드를 제공합니다:
@@ -144,9 +146,8 @@ pytest tests/
 
 ## 오디오 형식 지원
 
-- **PCM16**: 16비트 PCM 오디오 형식
-- **G711 U-law**: G711 U-law 압축 오디오
-- **G711 A-law**: G711 A-law 압축 오디오
+- **PCM16** (권장): 확장은 입력 오디오를 24 kHz PCM16으로 리샘플링한 뒤 OpenAI로 전송합니다. `input_audio_format`을 `"pcm16"`으로 설정하세요.
+- **G711 U-law / A-law**: 향후 호환을 위해 구성에서 허용되지만, 확장은 현재 이 설정과 관계없이 항상 리샘플링된 PCM16을 전송합니다.
 
 ## 문제 해결
 

ai_agents/agents/ten_packages/extension/openai_asr_python/docs/README.zh-CN.md

@@ -1,13 +1,13 @@
 # OpenAI ASR Python 扩展
 
-一个用于 OpenAI 自动语音识别 (ASR) 服务的 Python 扩展，提供实时语音转文本转换功能，完全支持异步操作，使用 OpenAI 的 beta 实时 API。
+一个用于 OpenAI 自动语音识别 (ASR) 服务的 Python 扩展，提供实时语音转文本转换功能，完全支持异步操作，使用 OpenAI Realtime 转录 API（GA 正式版）。
 
 ## 功能特性
 
 - **完全异步支持**: 采用完整的异步架构，实现高性能语音识别
 - **实时流式处理**: 使用 OpenAI 的 WebSocket API 支持低延迟实时音频流
-- **OpenAI Beta API**: 使用 OpenAI 的 beta 实时转录 API，提供前沿性能
-- **多种音频格式**: 支持 PCM16、G711 U-law 和 G711 A-law 音频格式
+- **OpenAI Realtime API**: 通过 GA 版 `session.update` 使用 OpenAI Realtime 转录 API
+- **PCM16 音频**: 接受任意输入采样率，发送前重采样为 24 kHz PCM16
 - **音频转储**: 可选的音频录制功能，用于调试和分析
 - **可配置日志**: 可调整的日志级别，便于调试
 - **错误处理**: 全面的错误处理和详细日志记录
@@ -37,26 +37,28 @@
 
 ```json
 {
-  "api_key": "your_openai_api_key",
-  "organization": "your_organization_id",
-  "project": "your_project_id",
   "params": {
+    "api_key": "your_openai_api_key",
     "input_audio_format": "pcm16",
     "input_audio_transcription": {
-      "model": "whisper-1"
+      "model": "whisper-1",
+      "prompt": "",
+      "language": "en"
     },
     "turn_detection": {
-      "enabled": true
-    },
-    "input_audio_noise_reduction": {
-      "enabled": true
+      "type": "server_vad",
+      "threshold": 0.5,
+      "prefix_padding_ms": 300,
+      "silence_duration_ms": 500
     }
   },
   "dump": false,
   "log_level": "INFO"
 }
 ```
 
+`organization`、`project`、`base_url` 等可选连接参数应放在 `params` 下。
+
 ## API
 
 扩展实现了 `AsyncASRBaseExtension` 接口，提供以下关键方法：
@@ -144,9 +146,8 @@ pytest tests/
 
 ## 音频格式支持
 
-- **PCM16**: 16 位 PCM 音频格式
-- **G711 U-law**: G711 U-law 压缩音频
-- **G711 A-law**: G711 A-law 压缩音频
+- **PCM16**（推荐）：扩展会将输入音频重采样为 24 kHz PCM16 后发送给 OpenAI。请将 `input_audio_format` 设为 `"pcm16"`。
+- **G711 U-law / A-law**：配置中可接受以便向前兼容，但扩展目前无论此项如何设置，实际始终发送重采样后的 PCM16。
 
 ## 故障排除
 

ai_agents/agents/ten_packages/extension/openai_asr_python/docs/README.zh-TW.md

@@ -1,13 +1,13 @@
 # OpenAI ASR Python 擴充
 
-一個用於 OpenAI 自動語音識別 (ASR) 服務的 Python 擴充，提供即時語音轉文字轉換功能，完全支援非同步操作，使用 OpenAI 的 beta 即時 API。
+一個用於 OpenAI 自動語音識別 (ASR) 服務的 Python 擴充，提供即時語音轉文字轉換功能，完全支援非同步操作，使用 OpenAI Realtime 轉錄 API（GA 正式版）。
 
 ## 功能特性
 
 - **完全非同步支援**: 採用完整的非同步架構，實現高效能語音識別
 - **即時串流處理**: 使用 OpenAI 的 WebSocket API 支援低延遲即時音訊串流
-- **OpenAI Beta API**: 使用 OpenAI 的 beta 即時轉錄 API，提供前沿效能
-- **多種音訊格式**: 支援 PCM16、G711 U-law 和 G711 A-law 音訊格式
+- **OpenAI Realtime API**: 透過 GA 版 `session.update` 使用 OpenAI Realtime 轉錄 API
+- **PCM16 音訊**: 接受任意輸入取樣率，傳送前重採樣為 24 kHz PCM16
 - **音訊轉儲**: 可選的音訊錄製功能，用於除錯和分析
 - **可設定日誌**: 可調整的日誌級別，便於除錯
 - **錯誤處理**: 全面的錯誤處理和詳細日誌記錄
@@ -37,26 +37,28 @@
 
 ```json
 {
-  "api_key": "your_openai_api_key",
-  "organization": "your_organization_id",
-  "project": "your_project_id",
   "params": {
+    "api_key": "your_openai_api_key",
     "input_audio_format": "pcm16",
     "input_audio_transcription": {
-      "model": "whisper-1"
+      "model": "whisper-1",
+      "prompt": "",
+      "language": "en"
     },
     "turn_detection": {
-      "enabled": true
-    },
-    "input_audio_noise_reduction": {
-      "enabled": true
+      "type": "server_vad",
+      "threshold": 0.5,
+      "prefix_padding_ms": 300,
+      "silence_duration_ms": 500
     }
   },
   "dump": false,
   "log_level": "INFO"
 }
 ```
 
+`organization`、`project`、`base_url` 等可選連線參數應放在 `params` 下。
+
 ## API
 
 擴充實現了 `AsyncASRBaseExtension` 介面，提供以下關鍵方法：
@@ -144,9 +146,8 @@ pytest tests/
 
 ## 音訊格式支援
 
-- **PCM16**: 16 位 PCM 音訊格式
-- **G711 U-law**: G711 U-law 壓縮音訊
-- **G711 A-law**: G711 A-law 壓縮音訊
+- **PCM16**（建議）：擴充會將輸入音訊重採樣為 24 kHz PCM16 後傳送給 OpenAI。請將 `input_audio_format` 設為 `"pcm16"`。
+- **G711 U-law / A-law**：設定中可接受以便向前相容，但擴充目前無論此項如何設定，實際始終傳送重採樣後的 PCM16。
 
 ## 故障排除
 

ai_agents/agents/ten_packages/extension/openai_asr_python/extension.py

@@ -4,6 +4,7 @@
 # See the LICENSE file for more information.
 #
 import asyncio
+import json
 import time
 from typing import Any
 from typing_extensions import override
@@ -42,6 +43,7 @@
     Error,
     Session,
 )
+from .openai_asr_client.schemas import build_ga_session_update
 from .config import OpenAIASRConfig
 from ten_ai_base.dumper import Dumper
 
@@ -224,8 +226,9 @@ async def finalize(self, session_id: str | None) -> None:
     # openai asr client event handler
     @override
     async def on_asr_start(self, response: Session[TranscriptionParam]):
+        ga_payload = build_ga_session_update(response.session)
         self.ten_env.log_info(
-            f"vendor_status_changed: on_asr_start {response.model_dump_json()}",
+            f"vendor_status_changed: on_asr_start {json.dumps(ga_payload)}",
             category=LOG_CATEGORY_VENDOR,
         )
         self.sent_user_audio_duration_ms_before_last_reset += (

ai_agents/agents/ten_packages/extension/openai_asr_python/manifest.json

@@ -1,7 +1,7 @@
 {
   "type": "extension",
   "name": "openai_asr_python",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "display_name": {
     "locales": {
       "en-US": {
@@ -123,4 +123,4 @@
       "docs/**"
     ]
   }
-}
+}