Skip to content

指南

本指南將深入介紹如何利用 OpenAI Agents SDK 的即時（realtime）功能，打造具備語音能力的 AI 智能代理（AI agent）。

Beta feature

Realtime agents 目前為 beta 版本。在我們持續改進實作過程中，可能會有不相容的變更。

概覽

Realtime agents 支援即時的對話流程，能夠即時處理語音與文字輸入，並以即時語音回應。它們會與 OpenAI Realtime API 維持持久連線，實現低延遲的自然語音對話，並能優雅地處理用戶中斷。

架構

核心元件

即時系統包含以下幾個主要元件：

  • RealtimeAgent：代理（Agent），可設定指令、工具（Tools）與交接（Handoffs）。
  • RealtimeRunner：負責管理設定。你可以呼叫 runner.run() 來取得一個 session（會話）。
  • RealtimeSession：單一互動 session。通常每當用戶開始對話時建立一個，並在對話結束前保持存活。
  • RealtimeModel：底層模型介面（通常為 OpenAI 的 WebSocket 實作）

Session 流程

一般的即時 session 會遵循以下流程：

  1. 建立你的 RealtimeAgent，設定指令、工具與交接。
  2. 設置 RealtimeRunner，並提供 agent 與相關設定選項。
  3. 啟動 session，使用 await runner.run()，這會回傳一個 RealtimeSession。
  4. 傳送語音或文字訊息到 session，使用 send_audio() 或 send_message()。
  5. 監聽事件，透過遍歷 session 來接收事件——事件包含語音輸出、逐字稿、工具呼叫、交接及錯誤等。
  6. 處理中斷，當用戶在 agent 說話時插話，系統會自動停止目前的語音產生。

session 會維護對話歷史，並管理與即時模型的持久連線。

Agent 設定

RealtimeAgent 的運作方式與一般 Agent 類似，但有幾項關鍵差異。完整 API 詳情請參閱 [RealtimeAgent][agents.realtime.agent.RealtimeAgent] API 參考文件。

與一般 agent 的主要差異：

  • 模型選擇是在 session 層級設定，而非 agent 層級。
  • 不支援結構化輸出（outputType 不支援）。
  • 語音可於每個 agent 設定，但在第一個 agent 開口後無法更改。
  • 其他功能如工具（Tools）、交接（Handoffs）與指令皆與一般 agent 相同。

Session 設定

模型設定

session 設定可讓你控制底層即時模型的行為。你可以設定模型名稱（例如 gpt-realtime）、語音選擇（alloy、echo、fable、onyx、nova、shimmer），以及支援的模態（文字與/或語音）。音訊格式可分別設定輸入與輸出，預設為 PCM16。

音訊設定

音訊設定用於控制 session 如何處理語音輸入與輸出。你可以使用如 Whisper 等模型進行輸入語音轉錄，設定語言偏好，並提供轉錄提示詞（prompts）以提升領域專有詞彙的準確度。輪流偵測（turn detection）設定可控制 agent 何時開始與結束回應，包括語音活動偵測閾值、靜音時長與偵測語音前後的補白等選項。

工具（Tools）與函式

新增工具

與一般 agent 相同，realtime agents 也支援在對話過程中執行的函式工具（function tools）：

from agents import function_tool

@function_tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    # Your weather API logic here
    return f"The weather in {city} is sunny, 72°F"

@function_tool
def book_appointment(date: str, time: str, service: str) -> str:
    """Book an appointment."""
    # Your booking logic here
    return f"Appointment booked for {service} on {date} at {time}"

agent = RealtimeAgent(
    name="Assistant",
    instructions="You can help with weather and appointments.",
    tools=[get_weather, book_appointment],
)

交接 (Handoffs)

建立交接 (Creating Handoffs)

交接 (Handoffs) 可用於在不同專業的代理 (Agents) 之間轉移對話。

from agents.realtime import realtime_handoff

# Specialized agents
billing_agent = RealtimeAgent(
    name="Billing Support",
    instructions="You specialize in billing and payment issues.",
)

technical_agent = RealtimeAgent(
    name="Technical Support",
    instructions="You handle technical troubleshooting.",
)

# Main agent with handoffs
main_agent = RealtimeAgent(
    name="Customer Service",
    instructions="You are the main customer service agent. Hand off to specialists when needed.",
    handoffs=[
        realtime_handoff(billing_agent, tool_description="Transfer to billing support"),
        realtime_handoff(technical_agent, tool_description="Transfer to technical support"),
    ]
)

事件處理

Session 會串流事件，您可以透過對 session 物件進行迭代來監聽這些事件。事件類型包含語音回應音訊片段、語音辨識結果、工具 (Tools) 執行的開始與結束、代理 (Agent) 任務交接 (handoff) 以及錯誤等。建議特別處理以下重點事件：

  • audio：來自代理 (Agent) 回應的原始音訊資料
  • audio_end：代理 (Agent) 完成語音回應
  • audio_interrupted：使用者中斷代理 (Agent)
  • tool_start/tool_end：工具 (Tools) 執行生命週期
  • handoff：發生代理 (Agent) 任務交接
  • error：處理過程中發生錯誤

完整事件細節請參考 [RealtimeSessionEvent][agents.realtime.events.RealtimeSessionEvent]。

Guardrails

即時代理 (Realtime agents) 僅支援輸出 guardrail。這些 guardrail 採用防彈跳 (debounce) 機制，並定期執行（非每個字都檢查），以避免即時生成時產生效能問題。預設的 debounce 長度為 100 個字元，但可自行設定。

Guardrail 可以直接附加在 RealtimeAgent，或透過 session 的 run_config 提供。兩種來源的 guardrail 會一同執行。

from agents.guardrail import GuardrailFunctionOutput, OutputGuardrail

def sensitive_data_check(context, agent, output):
    return GuardrailFunctionOutput(
        tripwire_triggered="password" in output,
        output_info=None,
    )

agent = RealtimeAgent(
    name="Assistant",
    instructions="...",
    output_guardrails=[OutputGuardrail(guardrail_function=sensitive_data_check)],
)

當 guardrail 被觸發時，會產生 guardrail_tripped 事件，並且可以中斷 Agent 當前的回應。debounce 行為有助於在安全性與即時效能需求之間取得平衡。與文字型 Agent 不同，Realtime agents 在 guardrail 被觸發時不會拋出 Exception。

音訊處理

請使用 [session.send_audio(audio_bytes)][agents.realtime.session.RealtimeSession.send_audio] 傳送音訊至 session，或使用 [session.send_message()][agents.realtime.session.RealtimeSession.send_message] 傳送文字。

對於音訊輸出，請監聽 audio 事件，並透過你偏好的音訊函式庫播放音訊資料。當使用者中斷 Agent 時，務必監聽 audio_interrupted 事件，立即停止播放並清除所有排隊中的音訊。

直接存取模型

你可以存取底層模型，以新增自訂監聽器或執行進階操作：

# Add a custom listener to the model
session.model.add_listener(my_custom_listener)

這讓你可以直接存取 [RealtimeModel][agents.realtime.model.RealtimeModel] 介面，適用於需要更低階連線控制的進階應用情境。

範例

如需完整可運作的範例，請參考 examples/realtime directory，其中包含有 UI 元件與無 UI 元件的示範。