如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

在 Realtime 中使用工具

讓即時語音智慧體呼叫函式工具和遠端 MCP 伺服器。

你可以在 Realtime 工作階段中加入工具,讓模型在即時對話期間查詢資料、執行動作或呼叫服務。無論用戶端使用 WebRTC 資料通道 或 WebSocket,都可以透過相同的事件設定工具。

如果需要由應用程式執行工具並傳回結果,請使用函式工具。如果需要由 Realtime API 代為連線至遠端工具伺服器,請使用 MCP 工具。

選擇工具類型

工具類型 適用情境 執行者
function 應用程式負責處理業務邏輯、檢查核准狀態或存取私有系統。 用戶端或伺服器接收函式呼叫並傳回 function_call_output。
mcp 搭配 server_url 你想讓模型呼叫遠端 MCP 伺服器提供的工具。 Realtime API 呼叫遠端 MCP 伺服器。
mcp 搭配 connector_id 你使用的既有模型搭配舊版內建連接器。 Realtime API 使用你提供的授權呼叫連接器。

你可以選擇下列其中一個層級加入工具:

  • 工作階段層級:若要讓工具在整個工作階段中都可用,請在 session.tools 中設定工具,並透過 session.update 傳送。
  • 回應層級:若只有一輪對話需要工具,請在 response.tools 中設定工具,並透過 response.create 傳送。

設定函式工具

如果工具需要在應用程式中執行,建議優先使用函式工具。模型會輸出函式呼叫所需的引數,接著由你的程式碼執行動作,再透過 function_call_output 項目傳回結果。

使用 session.update 設定函式工具
const event = {
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2.1",
    tools: [
      {
        type: "function",
        name: "lookup_order",
        description: "Look up an order by its order number.",
        parameters: {
          type: "object",
          properties: {
            order_number: {
              type: "string",
              description: "The customer-facing order number.",
            },
          },
          required: ["order_number"],
        },
      },
    ],
    tool_choice: "auto",
  },
};

ws.send(JSON.stringify(event));

模型呼叫函式時,請監聽函式呼叫項目,執行應用程式邏輯,再傳回輸出:

傳回函式呼叫的輸出
const event = {
  type: "conversation.item.create",
  item: {
    type: "function_call_output",
    call_id: functionCall.call_id,
    output: JSON.stringify({
      status: "shipped",
      delivery_date: "2026-05-09",
    }),
  },
};

ws.send(JSON.stringify(event));
ws.send(
  JSON.stringify({
    type: "response.create",
    response: { output_modalities: ["text"], tool_choice: "none" },
  })
);

如需瞭解函式呼叫的完整流程及各步驟涉及的事件,請參閱管理對話。

設定 MCP 工具

如果遠端 MCP 伺服器已提供所需的工具,或既有模型使用舊版內建連接器,就適合使用 MCP 工具。與函式工具不同,MCP 工具由 Realtime API 直接執行。

Realtime 中的 MCP 工具定義包含下列欄位:

  • type: "mcp"
  • server_label
  • server_url 或 connector_id,擇一使用
  • 選用欄位 authorization 和 headers
  • 選用欄位 allowed_tools
  • 選用欄位 require_approval
  • 選用欄位 server_description

以下範例讓整個工作階段都能使用提供文件的 MCP 伺服器:

使用 session.update 設定 MCP 工具
const event = {
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2.1",
    output_modalities: ["text"],
    tools: [
      {
        type: "mcp",
        server_label: "openai_docs",
        server_url: "https://developers.openai.com/mcp",
        allowed_tools: ["search_openai_docs", "fetch_openai_doc"],
        require_approval: "never",
      },
    ],
  },
};

ws.send(JSON.stringify(event));

舊版連接器

connector_id 在 2026 年 9 月 1 日之後發布的模型中已棄用。請使用 server_url 連線至遠端 MCP 伺服器,或使用 tunnel_id 透過 安全 MCP 通道連線至本機 MCP 伺服器。既有模型仍支援連接器。以下範例使用的 gpt-realtime-1.5 於上述日期之前發布。

內建連接器的 MCP 工具定義格式相同,但要傳入 connector_id 來取代 server_url。例如,Google 日曆使用 connector_googlecalendar。在 Realtime 中,請使用這些內建連接器執行讀取操作,例如搜尋或讀取日曆活動或電子郵件。請在 authorization 中傳入使用者的 OAuth 存取權杖,並盡可能透過 allowed_tools 限制可用的工具:

設定 Google 日曆連接器
const event = {
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-1.5",
    output_modalities: ["text"],
    tools: [
      {
        type: "mcp",
        server_label: "google_calendar",
        connector_id: "connector_googlecalendar",
        authorization: "<google-oauth-access-token>",
        allowed_tools: ["search_events", "read_event"],
        require_approval: "never",
      },
    ],
  },
};

ws.send(JSON.stringify(event));

遠端 MCP 伺服器 不會自動收到完整的對話上下文,但可以看到模型在工具呼叫中傳送的所有資料。 請限制可用工具的範圍,做法是設定 allowed_tools,並針對任何不宜自動執行的動作要求核准。

Realtime MCP 流程

與 Realtime 的 function 工具不同,遠端 MCP 工具由 Realtime API 直接執行。用戶端不會執行遠端工具,也不會傳回 function_call_output。用戶端負責設定存取權及監聽 MCP 生命週期事件,並可在伺服器要求核准時傳送核准回覆。

典型流程如下:

  1. 傳送 session.update 或 response.create,其中包含一個 tools 項目,並將其 type 設為 mcp。
  2. 伺服器開始匯入工具,並發出 mcp_list_tools.in_progress。
  3. 在伺服器列出工具的過程中,模型無法呼叫尚未載入的工具。如果接下來的一輪對話需要這些工具,且你想等工具載入後再開始,請監聽 mcp_list_tools.completed。在 conversation.item.done 事件中,若 item.type 為 mcp_list_tools,該事件就會列出實際匯入的工具名稱。如果匯入失敗,你會收到 mcp_list_tools.failed。
  4. 使用者說話或傳送文字後,用戶端會建立回應,或由系統依工作階段設定自動建立回應。
  5. 如果模型選擇 MCP 工具,你會看到 response.mcp_call_arguments.delta 和 response.mcp_call_arguments.done。
  6. 如果需要核准,伺服器會加入一個對話項目,其 item.type 為 mcp_approval_request。用戶端必須以 mcp_approval_response 項目回覆。
  7. 工具開始執行時,你會看到 response.mcp_call.in_progress。如果執行成功,你隨後會收到 response.output_item.done 事件,其 item.type 為 mcp_call。如果執行失敗,你會收到 response.mcp_call.failed。
  8. response.done 可能會在該回應的 MCP 呼叫完成前送達。等到回應結束,且該回應的所有 MCP 呼叫都完成後,請再傳送一個 response.create 事件,讓模型使用這些結果繼續對話。如果模型再次呼叫 MCP 工具,請重複這個步驟。Realtime API 不會自動建立這些後續回應。

以下事件處理常式會記錄主要的 MCP 生命週期事件,但不會管理後續回應:

在 Realtime 工作階段中監聽 MCP 事件
import type WebSocket from "ws";
import type {
  ConversationItem,
  RealtimeServerEvent,
} from "openai/resources/realtime/realtime";

function parseRealtimeEvent(
  rawMessage: string | WebSocket.RawData | MessageEvent<string>
): RealtimeServerEvent {
  if (typeof rawMessage === "string") {
    return JSON.parse(rawMessage);
  }

  if ("data" in rawMessage && typeof rawMessage.data === "string") {
    return JSON.parse(rawMessage.data);
  }

  return JSON.parse(rawMessage.toString());
}

function getOutputText(item: ConversationItem) {
  if (item.type !== "message") return "";

  return (item.content ?? [])
    .filter((part) => part.type === "output_text")
    .map((part) => part.text)
    .join("");
}

ws.on("message", (rawMessage) => {
  const event = parseRealtimeEvent(rawMessage);

  switch (event.type) {
    case "mcp_list_tools.in_progress":
      console.log("Listing MCP tools for item:", event.item_id);
      break;

    case "mcp_list_tools.completed":
      console.log("MCP tool listing complete for item:", event.item_id);
      break;

    case "mcp_list_tools.failed":
      console.error("MCP tool listing failed for item:", event.item_id);
      break;

    case "conversation.item.done":
      if (event.item.type === "mcp_list_tools") {
        const names = event.item.tools.map((tool) => tool.name).join(", ");
        console.log(`MCP tools ready on ${event.item.server_label}: ${names}`);
      }

      if (event.item.type === "mcp_approval_request") {
        console.log(
          "Approval required for:",
          event.item.name,
          event.item.arguments
        );
      }
      break;

    case "response.mcp_call_arguments.done":
      console.log("Final MCP call arguments:", event.arguments);
      break;

    case "response.mcp_call.in_progress":
      console.log("Running MCP tool for item:", event.item_id);
      break;

    case "response.mcp_call.failed":
      console.error("MCP tool call failed for item:", event.item_id);
      break;

    case "response.output_item.done":
      if (event.item.type === "mcp_call") {
        console.log(
          `MCP output from ${event.item.server_label}.${event.item.name}:`,
          event.item.output
        );
      }

      if (event.item.type === "message") {
        console.log("Assistant:", getOutputText(event.item));
      }
      break;

    case "response.done":
      console.log("Realtime turn complete.");
      break;
  }
});

常見錯誤

  • mcp_list_tools.failed:Realtime API 無法從遠端伺服器或連接器匯入工具。請檢查 server_url 或 connector_id、驗證設定、伺服器連線狀態,以及你在 allowed_tools 中指定的工具名稱。
  • response.mcp_call.failed:模型選擇了工具,但工具呼叫未完成。請檢查事件承載資料及後續的 mcp_call 項目,確認是否發生 MCP 通訊協定、執行或傳輸錯誤。
  • mcp_approval_request 沒有對應的 mcp_approval_response:用戶端必須明確核准或拒絕,工具呼叫才能繼續處理。
  • 新一輪對話開始時,mcp_list_tools.in_progress 仍在進行中:這一輪只能使用已載入完成的工具。
  • 回應使用 tool_choice: "required",但目前沒有可用工具:模型沒有符合條件的工具可呼叫。請等到收到 mcp_list_tools.completed,並確認至少已匯入一個工具,或針對不需要工具的對話輪次使用其他 tool_choice 設定。
  • MCP 工具定義在開始匯入前未通過驗證:常見原因包括同一個 server_label 在同一個 tools 陣列中出現多次、同時設定 server_url 和 connector_id、在最初建立工作階段的請求中省略這兩個欄位、使用無效的 connector_id,或同時傳送 authorization 和 headers.Authorization。使用連接器時,一律不要傳送 headers.Authorization。

核准或拒絕 MCP 工具呼叫

如果工具需要核准,Realtime API 會在對話中插入一個 mcp_approval_request 項目。若要繼續,請傳送新的 conversation.item.create 事件,並將其 item.type 設為 mcp_approval_response。

核准 MCP 請求
function approveMcpRequest(approvalRequestId: string) {
  const event = {
    type: "conversation.item.create",
    item: {
      type: "mcp_approval_response",
      approval_request_id: approvalRequestId,
      approve: true,
    },
  };

  ws.send(JSON.stringify(event));
}

若要拒絕請求,請將 approve 設為 false,也可以在 reason 中說明原因。

僅在單一回應中使用 MCP

如果 MCP 只應在一輪對話中可用,請將同一個 MCP 工具物件加入 response.tools,而非 session.tools:

為單一回應加入 MCP 工具
const event = {
  type: "response.create",
  response: {
    output_modalities: ["text"],
    tool_choice: "required",
    parallel_tool_calls: false,
    input: [
      {
        type: "message",
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Which transport should I use for browser clients in the Realtime API?",
          },
        ],
      },
    ],
    tools: [
      {
        type: "mcp",
        server_label: "openai_docs",
        server_url: "https://developers.openai.com/mcp",
        allowed_tools: ["search_openai_docs", "fetch_openai_doc"],
        require_approval: "never",
      },
    ],
  },
};

ws.send(JSON.stringify(event));

如果只有一個回應需要外部上下文,或不同輪次的對話需要使用不同的 MCP 伺服器,就適合採用這種做法。

重複使用先前定義的伺服器標籤

server_label 是目前 Realtime 工作階段中用來識別工具定義的固定標籤。使用 server_label 搭配 server_url 或 connector_id 定義伺服器或連接器後,後續的 session.update 或 response.create 事件只需參照同一個 server_label。Realtime API 會沿用先前的定義,你不必再次傳送完整的工具物件。

重複使用先前定義的連接器
const event = {
  type: "response.create",
  response: {
    output_modalities: ["text"],
    input: [
      {
        type: "message",
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Check my schedule for this afternoon.",
          },
        ],
      },
    ],
    // Reuses the google_calendar connector defined earlier in this session.
    tools: [
      {
        type: "mcp",
        server_label: "google_calendar",
      },
    ],
  },
};

ws.send(JSON.stringify(event));

只有在同一個工作階段中才能沿用定義。如果你開始新的 Realtime 工作階段,請再次傳送完整的 MCP 定義,讓伺服器匯入工具清單。