Update realtime agent guide document page

Author: seratch

docs/ja/realtime/quickstart.md

@@ -4,26 +4,26 @@ search:
 ---
 # クイックスタート
 
-Realtime エージェントは、 OpenAI の Realtime API を使用して AI 音声会話を実現します。このガイドでは、最初の Realtime 音声エージェントの作成手順を説明します。
+Realtime エージェントは、OpenAI の Realtime API を使って AI エージェントとの音声対話を可能にします。このガイドでは、最初のリアルタイム音声エージェントの作成手順を説明します。
 
 !!! warning "ベータ機能"
-Realtime エージェントはベータ版です。実装の改良に伴い、互換性のない変更が入る可能性があります。
+Realtime エージェントはベータ版です。実装の改善に伴い、非互換の変更が入る可能性があります。
 
 ## 前提条件
 
-- Python 3.9 以上
-- OpenAI API キー
-- OpenAI Agents SDK の基本的な知識
+-   Python 3.9 以上
+-   OpenAI API キー
+-   OpenAI Agents SDK の基本的な知識
 
 ## インストール
 
-まだの場合は、 OpenAI Agents SDK をインストールします:
+まだの場合は、OpenAI Agents SDK をインストールします:
 
 ```bash
 pip install openai-agents
 ```
 
-## はじめての Realtime エージェントの作成
+## 最初の Realtime エージェントの作成
 
 ### 1. 必要なコンポーネントのインポート
 
@@ -41,47 +41,77 @@ agent = RealtimeAgent(
 )
 ```
 
-### 3. Runner のセットアップ
+### 3. Runner をセットアップ
 
 ```python
 runner = RealtimeRunner(
     starting_agent=agent,
     config={
         "model_settings": {
-            "model_name": "gpt-4o-realtime-preview",
-            "voice": "alloy",
-            "modalities": ["text", "audio"],
+            "model_name": "gpt-realtime",
+            "voice": "ash",
+            "modalities": ["audio"],
+            "input_audio_format": "pcm16",
+            "output_audio_format": "pcm16",
+            "input_audio_transcription": {"model": "gpt-4o-mini-transcribe"},
+            "turn_detection": {"type": "semantic_vad", "interrupt_response": True},
         }
     }
 )
 ```
 
-### 4. セッションの開始
+### 4. セッションを開始
 
 ```python
-async def main():
-    # Start the realtime session
-    session = await runner.run()
-
-    async with session:
-        # Send a text message to start the conversation
-        await session.send_message("Hello! How are you today?")
-
-        # The agent will stream back audio in real-time (not shown in this example)
-        # Listen for events from the session
-        async for event in session:
-            if event.type == "response.audio_transcript.done":
-                print(f"Assistant: {event.transcript}")
-            elif event.type == "conversation.item.input_audio_transcription.completed":
-                print(f"User: {event.transcript}")
-
-# Run the session
-asyncio.run(main())
+# Start the session
+session = await runner.run()
+
+async with session:
+    print("Session started! The agent will stream audio responses in real-time.")
+    # Process events
+    async for event in session:
+        try:
+            if event.type == "agent_start":
+                print(f"Agent started: {event.agent.name}")
+            elif event.type == "agent_end":
+                print(f"Agent ended: {event.agent.name}")
+            elif event.type == "handoff":
+                print(f"Handoff from {event.from_agent.name} to {event.to_agent.name}")
+            elif event.type == "tool_start":
+                print(f"Tool started: {event.tool.name}")
+            elif event.type == "tool_end":
+                print(f"Tool ended: {event.tool.name}; output: {event.output}")
+            elif event.type == "audio_end":
+                print("Audio ended")
+            elif event.type == "audio":
+                # Enqueue audio for callback-based playback with metadata
+                # Non-blocking put; queue is unbounded, so drops won’t occur.
+                pass
+            elif event.type == "audio_interrupted":
+                print("Audio interrupted")
+                # Begin graceful fade + flush in the audio callback and rebuild jitter buffer.
+            elif event.type == "error":
+                print(f"Error: {event.error}")
+            elif event.type == "history_updated":
+                pass  # Skip these frequent events
+            elif event.type == "history_added":
+                pass  # Skip these frequent events
+            elif event.type == "raw_model_event":
+                print(f"Raw model event: {_truncate_str(str(event.data), 200)}")
+            else:
+                print(f"Unknown event type: {event.type}")
+        except Exception as e:
+            print(f"Error processing event: {_truncate_str(str(e), 200)}")
+
+def _truncate_str(s: str, max_length: int) -> str:
+    if len(s) > max_length:
+        return s[:max_length] + "..."
+    return s
 ```
 
-## 完全なコード例
+## 完全な例
 
-動作する完全なコード例は次のとおりです:
+以下は動作する完全な例です:
 
 ```python
 import asyncio
@@ -93,86 +123,109 @@ async def main():
         name="Assistant",
         instructions="You are a helpful voice assistant. Keep responses brief and conversational.",
     )
-
     # Set up the runner with configuration
     runner = RealtimeRunner(
         starting_agent=agent,
         config={
             "model_settings": {
-                "model_name": "gpt-4o-realtime-preview",
-                "voice": "alloy",
-                "modalities": ["text", "audio"],
-                "input_audio_transcription": {
-                    "model": "whisper-1"
-                },
-                "turn_detection": {
-                    "type": "server_vad",
-                    "threshold": 0.5,
-                    "prefix_padding_ms": 300,
-                    "silence_duration_ms": 200
-                }
+                "model_name": "gpt-realtime",
+                "voice": "ash",
+                "modalities": ["audio"],
+                "input_audio_format": "pcm16",
+                "output_audio_format": "pcm16",
+                "input_audio_transcription": {"model": "gpt-4o-mini-transcribe"},
+                "turn_detection": {"type": "semantic_vad", "interrupt_response": True},
             }
-        }
+        },
     )
-
     # Start the session
     session = await runner.run()
 
     async with session:
         print("Session started! The agent will stream audio responses in real-time.")
-
         # Process events
         async for event in session:
-            if event.type == "response.audio_transcript.done":
-                print(f"Assistant: {event.transcript}")
-            elif event.type == "conversation.item.input_audio_transcription.completed":
-                print(f"User: {event.transcript}")
-            elif event.type == "error":
-                print(f"Error: {event.error}")
-                break
+            try:
+                if event.type == "agent_start":
+                    print(f"Agent started: {event.agent.name}")
+                elif event.type == "agent_end":
+                    print(f"Agent ended: {event.agent.name}")
+                elif event.type == "handoff":
+                    print(f"Handoff from {event.from_agent.name} to {event.to_agent.name}")
+                elif event.type == "tool_start":
+                    print(f"Tool started: {event.tool.name}")
+                elif event.type == "tool_end":
+                    print(f"Tool ended: {event.tool.name}; output: {event.output}")
+                elif event.type == "audio_end":
+                    print("Audio ended")
+                elif event.type == "audio":
+                    # Enqueue audio for callback-based playback with metadata
+                    # Non-blocking put; queue is unbounded, so drops won’t occur.
+                    pass
+                elif event.type == "audio_interrupted":
+                    print("Audio interrupted")
+                    # Begin graceful fade + flush in the audio callback and rebuild jitter buffer.
+                elif event.type == "error":
+                    print(f"Error: {event.error}")
+                elif event.type == "history_updated":
+                    pass  # Skip these frequent events
+                elif event.type == "history_added":
+                    pass  # Skip these frequent events
+                elif event.type == "raw_model_event":
+                    print(f"Raw model event: {_truncate_str(str(event.data), 200)}")
+                else:
+                    print(f"Unknown event type: {event.type}")
+            except Exception as e:
+                print(f"Error processing event: {_truncate_str(str(e), 200)}")
+
+def _truncate_str(s: str, max_length: int) -> str:
+    if len(s) > max_length:
+        return s[:max_length] + "..."
+    return s
 
 if __name__ == "__main__":
+    # Run the session
     asyncio.run(main())
 ```
 
 ## 設定オプション
 
 ### モデル設定
 
-- `model_name`: 利用可能な Realtime モデルから選択 (例: `gpt-4o-realtime-preview`)
-- `voice`: 音声の選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`)
-- `modalities`: テキストや音声の有効化 (`["text", "audio"]`)
+-   `model_name`: 利用可能なリアルタイムモデルから選択 (例: `gpt-realtime`)
+-   `voice`: 音声を選択 (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`)
+-   `modalities`: テキストまたは音声を有効化 (`["text"]` または `["audio"]`)
 
 ### オーディオ設定
 
-- `input_audio_format`: 入力音声の形式 (`pcm16`, `g711_ulaw`, `g711_alaw`)
-- `output_audio_format`: 出力音声の形式
-- `input_audio_transcription`: 書き起こしの設定
+-   `input_audio_format`: 入力音声の形式 (`pcm16`, `g711_ulaw`, `g711_alaw`)
+-   `output_audio_format`: 出力音声の形式
+-   `input_audio_transcription`: 文字起こしの設定
 
 ### ターン検出
 
-- `type`: 検出方法 (`server_vad`, `semantic_vad`)
-- `threshold`: 音声活動の閾値 (0.0–1.0)
-- `silence_duration_ms`: ターン終了を検出する無音時間
-- `prefix_padding_ms`: 発話前の音声パディング
+-   `type`: 検出方法 (`server_vad`, `semantic_vad`)
+-   `threshold`: 音声アクティビティのしきい値 (0.0–1.0)
+-   `silence_duration_ms`: ターン終了を検出する無音時間
+-   `prefix_padding_ms`: 発話前の音声パディング
 
 ## 次のステップ
 
-- [Realtime エージェントについて詳しく学ぶ](guide.md)
-- [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダの動作するコード例を参照
-- エージェントにツールを追加
-- エージェント間のハンドオフを実装
-- 安全性のためのガードレールを設定
+-   [Realtime エージェントの詳細](guide.md)
+-   実行可能なサンプルは [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) フォルダを参照してください
+-   エージェントにツールを追加する
+-   エージェント間のハンドオフを実装する
+-   安全性のためのガードレールを設定する
 
 ## 認証
 
-環境に OpenAI API キーが設定されていることを確認してください:
+OpenAI API キーが環境に設定されていることを確認してください:
 
 ```bash
 export OPENAI_API_KEY="your-api-key-here"
 ```
 
-また、セッション作成時に直接渡すこともできます:
+または、セッション作成時に直接渡します:
 
 ```python
 session = await runner.run(model_config={"api_key": "your-api-key"})