使用 Realtime API 建立語音到語音的語音智慧體。模型可直接處理音訊、維護對話狀態，並呼叫工具。本指南從使用 Agents SDK 建立瀏覽器應用程式開始；若需要直接控制底層連線，請參閱相關的連線指南。
若要建立可將工作委派給獨立後端的全雙工對話，請參閱 GPT-Live。若要比較語音架構與串接式處理流程，請參閱語音智慧體。
建立語音到語音的語音智慧體
若希望互動像自然對話一樣即時流暢，請使用 Realtime API。對於需要支援插話打斷、低首段音訊延遲、自然的發言輪替，以及即時工具使用的語音智慧體，這是最佳起點。
瀏覽器中的典型流程如下：
- 應用程式伺服器為即時工作階段建立短效用戶端密鑰。
- 前端建立
RealtimeSession。 - 工作階段在瀏覽器中透過 WebRTC 連線，或在伺服器上透過 WebSocket 連線。
- 智慧體在該工作階段中處理語音對話回合、工具、中斷與交接。
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
const agent = new RealtimeAgent({
name: "Assistant",
instructions: "You are a helpful voice assistant.",
});
const session = new RealtimeSession(agent, {
model: "gpt-realtime-2.1",
});
await session.connect({
apiKey: "ek_...(ephemeral key from your server)",
});接著，您可以像設定文字智慧體一樣，為 RealtimeAgent 加入工具、交接與防護機制。請將音訊傳輸相關的處理保留在工作階段層，並將業務邏輯保留在智慧體定義中。
若需要更底層的控制，請先參閱傳輸相關文件：
安全識別碼
如果應用程式會識別個別終端使用者，請在 Realtime API 請求中附上安全識別碼。OpenAI 建議使用安全識別碼，但並未強制要求。安全識別碼有助於 OpenAI 偵測有害行為，並針對個別使用者而非整個組織採取處置。請使用穩定且能保護隱私的值，例如經過雜湊處理的內部使用者 ID。
發出 Realtime API 請求時，請透過 OpenAI-Safety-Identifier 標頭傳送識別碼。使用短效 Token 時，請在建立用戶端密鑰的伺服器端請求中設定此標頭，將識別碼與工作階段建立關聯。從受信任的伺服器透過 WebSocket 或統一的 WebRTC 介面連線時，請在連線請求中設定此標頭。
安全識別碼不會從 Responses API 請求或其他工作階段自動沿用。如果你在應用程式的其他地方使用 Responses API 的 safety_identifier 參數，請在建立或連線至每個即時工作階段時，傳入相同的穩定值。
從 Beta 遷移至 GA
如果你仍在使用 Realtime 的 beta 版整合，請先遷移至 GA 介面，再進行新的開發工作。最重要的變更如下：
- 呼叫 GA 介面時，請移除
OpenAI-Beta: realtime=v1標頭。 - 使用
POST /v1/realtime/client_secrets為瀏覽器或行動用戶端建立短效憑證。 - 建立 WebRTC 工作階段時，請使用
/v1/realtime/calls。 - 更新工作階段與事件的資料結構，以符合 GA 介面。具體來說，請設定
session.type、將輸出音訊組態移至session.audio.output底下，並使用較新的回應事件名稱，例如response.output_text.delta、response.output_audio.delta和response.output_audio_transcript.delta。 - 若要將語音到語音應用程式遷移至新版，請從瀏覽器範例開始。若要遷移轉錄工作流程，請參閱即時轉錄。
如需目前的 GA 流程，請參閱即時用戶端事件參考資料、即時工作階段參考資料與瀏覽器範例。
後續步驟
- 管理對話：設定工作階段，並處理音訊、文字與事件。
- 語音活動偵測：設定自動對話回合偵測。
- 工具與 MCP：加入函式、MCP 伺服器與連接器。
- 語音模型提示詞：參閱您所使用的 Realtime 模型對應的指南。
- 成本最佳化：瞭解 Realtime 的計費與快取機制。
- 伺服器端控制：將工具執行與工作階段控制保留在您的伺服器上。
其他音訊工作流程
工作流程選擇工具與共通音訊術語現已移至音訊與語音。如需連續翻譯，請使用即時翻譯。如需即時字幕，請使用即時轉錄；若要處理錄製的音訊，請使用檔案轉錄。