Erste Schritte mit der Realtime API

Entwickle mit der Realtime API einen Speech-to-Speech-Sprachagenten. Das Modell verarbeitet Audio direkt, verwaltet den Gesprächszustand und kann Werkzeuge aufrufen. Dieser Leitfaden beginnt mit dem Agents SDK für eine Browseranwendung. Wenn du direkte Kontrolle benötigst, nutze die Leitfäden zu den zugrunde liegenden Verbindungen.

Informationen zu Vollduplex-Unterhaltungen mit einem separaten Backend, an das Aufgaben delegiert werden, findest du unter GPT-Live. Einen Vergleich von Spracharchitekturen und verketteten Pipelines findest du unter Sprachagenten.

Einen Speech-to-Speech-Sprachagenten entwickeln

Nutze die Realtime API, wenn sich die Interaktion wie ein unmittelbares, natürliches Gespräch anfühlen soll. Sie ist der beste Einstieg für Sprachagenten, die sich beim Sprechen unterbrechen lassen, eine geringe Latenz bis zur ersten Audioausgabe bieten, natürliche Sprecherwechsel ermöglichen und Werkzeuge in Echtzeit nutzen sollen.

Der typische Ablauf im Browser sieht so aus:

1. Dein Anwendungsserver erstellt ein kurzlebiges Client-Secret für die Echtzeitsitzung.
2. Dein Frontend erstellt eine RealtimeSession.
3. Die Sitzung stellt die Verbindung im Browser über WebRTC oder auf dem Server über WebSocket her.
4. Der Agent verarbeitet innerhalb dieser Sitzung Audiobeiträge, Werkzeuge, Unterbrechungen und Übergaben.

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { 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)",
});

Füge dem RealtimeAgent anschließend Werkzeuge, Übergaben und Schutzmechanismen hinzu, genauso wie bei einem Textagenten. Belasse die Audioübertragung auf der Sitzungsebene und die Geschäftslogik in der Agentendefinition.

Wenn du die Übertragung auf einer tieferen Ebene steuern möchtest, beginne mit dieser Dokumentation:

• Übersicht zu Audio und Stimme
• Realtime API mit WebRTC
• Realtime API mit WebSocket

Sicherheitskennungen

Wenn deine Anwendung einzelne Endnutzende identifiziert, sende bei Anfragen an die Realtime API eine Sicherheitskennung mit. OpenAI empfiehlt Sicherheitskennungen, schreibt sie aber nicht vor. Sie helfen OpenAI dabei, schädliches Verhalten zu erkennen und Maßnahmen gezielt gegen einzelne Nutzende statt gegen deine gesamte Organisation zu ergreifen. Verwende einen gleichbleibenden Wert, der die Privatsphäre schützt, beispielsweise den Hash einer internen Nutzer-ID.

Sende die Kennung bei Anfragen an die Realtime API im Header OpenAI-Safety-Identifier. Wenn du kurzlebige Token verwendest, setze den Header in der serverseitigen Anfrage, die das Client-Secret erstellt, um die Kennung der Sitzung zuzuordnen. Wenn du die Verbindung von einem vertrauenswürdigen Server aus über WebSocket oder die einheitliche WebRTC-Schnittstelle herstellst, setze den Header in der Verbindungsanfrage.

Sicherheitskennungen werden nicht aus Anfragen an die Responses API oder aus anderen Sitzungen übernommen. Wenn du den Parameter safety_identifier der Responses API an anderer Stelle in deiner Anwendung verwendest, übergib denselben gleichbleibenden Wert, wenn du eine Echtzeitsitzung erstellst oder eine Verbindung zu ihr herstellst.

Migration von Beta zu GA

Wenn du noch eine Realtime-Integration auf Basis der Beta-Version verwendest, migriere sie zur GA-Schnittstelle, bevor du mit neuen Arbeiten beginnst. Die wichtigsten Änderungen sind:

• Entferne den Header OpenAI-Beta: realtime=v1, wenn du die GA-Schnittstelle aufrufst.
• Verwende POST /v1/realtime/client_secrets, um kurzlebige Zugangsdaten für Browser- oder mobile Clients zu erstellen.
• Verwende /v1/realtime/calls, um WebRTC-Sitzungen aufzubauen.
• Passe die Datenstrukturen für Sitzungen und Ereignisse an die GA-Schnittstelle an. Setze insbesondere session.type, verschiebe die Konfiguration der Audioausgabe unter session.audio.output und verwende die neueren Namen für Antwortereignisse wie response.output_text.delta, response.output_audio.delta und response.output_audio_transcript.delta.
• Wenn du eine Speech-to-Speech-App weiterentwickelst, nutze das Browserbeispiel als Ausgangspunkt. Wenn du einen Transkriptionsablauf weiterentwickelst, nutze Echtzeittranskription.

Den aktuellen GA-Ablauf findest du in der Referenz zu Realtime-Client-Ereignissen, der Referenz zu Echtzeitsitzungen und im Browserbeispiel.

Nächste Schritte

• Unterhaltungen verwalten: Konfiguriere Sitzungen und verarbeite Audio, Text und Ereignisse.
• Sprachaktivitätserkennung: Konfiguriere die automatische Erkennung von Gesprächsbeiträgen.
• Werkzeuge und MCP: Füge Funktionen, MCP-Server und Konnektoren hinzu.
• Prompts für Sprachmodelle formulieren: Nutze den Leitfaden für dein Realtime-Modell.
• Kosten optimieren: Erfahre, wie Abrechnung und Caching bei der Realtime API funktionieren.
• Serverseitige Steuerung: Belasse die Ausführung von Werkzeugen und die Sitzungssteuerung auf deinem Server.

Weitere Audio-Arbeitsabläufe

Die Auswahlhilfe für Arbeitsabläufe und die gemeinsamen Audiobegriffe findest du jetzt unter Audio und Stimme. Nutze für fortlaufende Übersetzungen Live-Übersetzung, für Live-Untertitel Live-Transkription und für Audioaufnahmen Dateien transkribieren.