Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Tools in Realtime verwenden

Lass Sprachagenten in Echtzeit Funktionstools und entfernte MCP-Server aufrufen.

Du kannst einer Realtime-Sitzung Tools hinzufügen, damit das Modell während eines laufenden Gesprächs Daten abrufen, Aktionen ausführen oder Dienste aufrufen kann. Für die Konfiguration der Tools verwendest du dieselben Ereignisse, unabhängig davon, ob dein Client einen WebRTC-Datenkanal oder einen WebSocket nutzt.

Verwende Funktionstools, wenn deine Anwendung das Tool ausführen und das Ergebnis zurückgeben soll. Verwende MCP-Tools, wenn die Realtime API für dich eine Verbindung zu einem entfernten Tool-Server herstellen soll.

Tool-Typ auswählen

Tool-Typ Wann du ihn verwendest Wer das Tool ausführt
function Deine Anwendung steuert die Geschäftslogik, prüft Genehmigungen oder regelt den Zugriff auf private Systeme. Dein Client oder Server empfängt einen Funktionsaufruf und gibt function_call_output zurück.
mcp mit server_url Das Modell soll Tools aufrufen, die ein entfernter MCP-Server bereitstellt. Die Realtime API ruft den entfernten MCP-Server auf.
mcp mit connector_id Du verwendest einen älteren integrierten Konnektor mit einem bestehenden Modell. Die Realtime API ruft den Konnektor mit der von dir bereitgestellten Autorisierung auf.

Füge Tools auf einer von zwei Ebenen hinzu:

  • Auf Sitzungsebene mit session.tools in session.update, wenn das Tool während der gesamten Sitzung verfügbar sein soll.
  • Auf Antwortebene mit response.tools in response.create, wenn du das Tool nur für eine Gesprächsrunde brauchst.

Ein Funktionstool konfigurieren

Wenn deine Anwendung das Tool ausführen soll, ist ein Funktionstool in der Regel die richtige Wahl. Das Modell liefert die Argumente für den Funktionsaufruf. Dein Code führt die Aktion aus und sendet das Ergebnis in einem Element vom Typ function_call_output zurück.

Ein Funktionstool mit session.update konfigurieren
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));

Wenn das Modell die Funktion aufruft, warte auf das Element mit dem Funktionsaufruf, führe die Logik deiner Anwendung aus und sende das Ergebnis zurück:

Ergebnis eines Funktionsaufrufs senden
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" },
  })
);

Der Leitfaden Gespräche verwalten erklärt den Funktionsaufruf Schritt für Schritt anhand aller beteiligten Ereignisse.

Ein MCP-Tool konfigurieren

MCP-Tools eignen sich, wenn ein entfernter MCP-Server das Tool bereits bereitstellt oder ein bestehendes Modell einen älteren integrierten Konnektor verwendet. Anders als bei Funktionstools übernimmt die Realtime API bei MCP-Tools selbst die Ausführung.

In Realtime hat die Definition eines MCP-Tools folgende Felder:

  • type: "mcp"
  • server_label
  • Entweder server_url oder connector_id
  • Optional: authorization und headers
  • Optional: allowed_tools
  • Optional: require_approval
  • Optional: server_description

Dieses Beispiel stellt einen MCP-Server für die Dokumentation während der gesamten Sitzung bereit:

Ein MCP-Tool mit session.update konfigurieren
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));

Ältere Konnektoren

connector_id gilt bei Modellen, die nach dem 1. September 2026 erschienen sind, als veraltet. Verwende server_url für die Verbindung zu einem entfernten MCP-Server oder tunnel_id für die Verbindung zu einem lokalen MCP-Server über Secure MCP Tunnel. Bestehende Modelle unterstützen Konnektoren weiterhin. Das folgende Beispiel verwendet gpt-realtime-1.5, das vor dem Stichtag erschienen ist.

Integrierte Konnektoren verwenden dieselbe MCP-Tool-Struktur. Du übergibst jedoch connector_id anstelle von server_url. Google Kalender verwendet beispielsweise connector_googlecalendar. Nutze diese integrierten Konnektoren in Realtime für Lesezugriffe, etwa um Termine oder E-Mails zu suchen oder zu lesen. Übergib das OAuth-Zugriffstoken der Person, die den Zugriff gewährt, in authorization. Beschränke die verfügbaren Tools nach Möglichkeit mit allowed_tools:

Einen Konnektor für Google Kalender konfigurieren
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));

Entfernte MCP-Server erhalten nicht automatisch den vollständigen Gesprächskontext. Sie können aber alle Daten einsehen, die das Modell bei einem Tool-Aufruf sendet. Beschränke die verfügbaren Tools mit allowed_tools und verlange eine Genehmigung für jede Aktion, die du nicht automatisch ausführen würdest.

Ablauf von MCP-Aufrufen in Realtime

Anders als bei Realtime-Tools vom Typ function führt die Realtime API entfernte MCP-Tools selbst aus. Dein Client führt das entfernte Tool nicht aus und gibt auch kein function_call_output zurück. Dein Client konfiguriert den Zugriff, überwacht die Ereignisse im MCP-Lebenszyklus und kann auf Genehmigungsanfragen des Servers antworten.

Ein typischer Ablauf sieht so aus:

  1. Du sendest session.update oder response.create mit einem Eintrag in tools, dessen Feld type den Wert mcp hat.
  2. Der Server beginnt mit dem Import der Tools und sendet mcp_list_tools.in_progress.
  3. Solange der Server die Tool-Liste noch lädt, kann das Modell nur bereits geladene Tools aufrufen. Wenn eine Gesprächsrunde diese Tools benötigt und du sie erst nach dem Import starten möchtest, warte auf mcp_list_tools.completed. Das Ereignis conversation.item.done, bei dem item.type den Wert mcp_list_tools hat, enthält die Namen der tatsächlich importierten Tools. Schlägt der Import fehl, erhältst du mcp_list_tools.failed.
  4. Eine Person spricht oder sendet Text. Daraufhin erstellt dein Client eine Antwort, oder die Sitzung erstellt sie je nach Konfiguration automatisch.
  5. Wählt das Modell ein MCP-Tool aus, erhältst du response.mcp_call_arguments.delta und response.mcp_call_arguments.done.
  6. Wenn eine Genehmigung erforderlich ist, fügt der Server dem Gespräch ein Element hinzu, dessen Feld item.type den Wert mcp_approval_request hat. Dein Client muss darauf mit einem Element vom Typ mcp_approval_response antworten.
  7. Sobald das Tool ausgeführt wird, erhältst du response.mcp_call.in_progress. Bei Erfolg erhältst du anschließend ein Ereignis vom Typ response.output_item.done, bei dem item.type den Wert mcp_call hat. Bei einem Fehler erhältst du response.mcp_call.failed.
  8. response.done kann für eine Antwort eintreffen, bevor alle zugehörigen MCP-Aufrufe abgeschlossen sind. Sobald die Antwort und alle zugehörigen MCP-Aufrufe abgeschlossen sind, sende erneut ein Ereignis vom Typ response.create. So kann das Modell die Ergebnisse nutzen und das Gespräch fortsetzen. Wiederhole diesen Schritt, wenn das Modell weitere MCP-Aufrufe ausführt. Die Realtime API erstellt diese Folgeantworten nicht automatisch.

Dieser Ereignishandler protokolliert die wichtigsten Ereignisse im MCP-Lebenszyklus. Folgeantworten verwaltet er nicht.

MCP-Ereignisse während einer Realtime-Sitzung empfangen
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;
  }
});

Häufige Fehler

  • mcp_list_tools.failed: Die Realtime API konnte keine Tools vom entfernten Server oder Konnektor importieren. Prüfe server_url oder connector_id, die Authentifizierung, die Verbindung zum Server und alle Tool-Namen, die du in allowed_tools angegeben hast.
  • response.mcp_call.failed: Das Modell hat ein Tool ausgewählt, aber der Aufruf wurde nicht abgeschlossen. Prüfe die Ereignisdaten und das nachfolgende Element vom Typ mcp_call auf Fehler im MCP-Protokoll, bei der Ausführung oder beim Datentransport.
  • mcp_approval_request ohne passende mcp_approval_response: Der Tool-Aufruf kann erst fortgesetzt werden, wenn dein Client ihn ausdrücklich genehmigt oder ablehnt.
  • Eine Gesprächsrunde beginnt, während mcp_list_tools.in_progress noch aktiv ist: Für diese Runde stehen nur Tools zur Verfügung, die bereits vollständig geladen sind.
  • Eine Antwort verwendet tool_choice: "required", obwohl derzeit keine Tools verfügbar sind: Das Modell kann kein Tool aufrufen. Warte auf mcp_list_tools.completed, vergewissere dich, dass mindestens ein Tool importiert wurde, oder verwende für Gesprächsrunden, die kein Tool benötigen, einen anderen Wert für tool_choice.
  • Die Validierung der MCP-Tool-Definition schlägt vor Beginn des Imports fehl: Häufige Ursachen sind ein doppelt vergebenes server_label im selben tools-Array, die gleichzeitige Angabe von server_url und connector_id, das Fehlen beider Felder in der ersten Anfrage zum Erstellen der Sitzung, eine ungültige connector_id oder die gleichzeitige Übermittlung von authorization und headers.Authorization. Sende bei Konnektoren niemals headers.Authorization.

MCP-Tool-Aufrufe genehmigen oder ablehnen

Wenn ein Tool eine Genehmigung erfordert, fügt die Realtime API ein Element vom Typ mcp_approval_request in das Gespräch ein. Um fortzufahren, sende ein neues Ereignis vom Typ conversation.item.create, bei dem item.type den Wert mcp_approval_response hat.

Eine MCP-Anfrage genehmigen
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));
}

Wenn du die Anfrage ablehnst, setze approve auf false. Optional kannst du mit reason eine Begründung angeben.

MCP nur für eine Antwort verwenden

Wenn MCP nur für eine einzige Gesprächsrunde verfügbar sein soll, füge dasselbe MCP-Tool-Objekt zu response.tools statt zu session.tools hinzu:

MCP-Tools für eine einzelne Antwort hinzufügen
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));

Das ist sinnvoll, wenn nur eine Antwort externen Kontext benötigt oder wenn du für verschiedene Gesprächsrunden unterschiedliche MCP-Server verwenden möchtest.

Eine bereits definierte Serverkennung wiederverwenden

server_label ist die feste Kennung einer Tool-Definition in der aktuellen Realtime-Sitzung. Sobald du einen Server oder Konnektor mit server_label und entweder server_url oder connector_id definiert hast, genügt bei späteren Ereignissen vom Typ session.update oder response.create die Angabe desselben Werts für server_label. Die Realtime API verwendet dann die vorhandene Definition. Du musst das vollständige Tool-Objekt nicht erneut senden.

Einen bereits definierten Konnektor wiederverwenden
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));

Die Definition lässt sich nur innerhalb derselben Sitzung wiederverwenden. Wenn du eine neue Realtime-Sitzung startest, sende die vollständige MCP-Definition erneut, damit der Server die Liste der Tools importieren kann.