Entwickle mit der Realtime API einen Speech-to-Speech-Agenten. Das Modell verarbeitet Audiodaten direkt, behält den Gesprächskontext bei und kann Tools aufrufen. Diese Anleitung zeigt dir zunächst, wie du das Agents SDK für eine Browseranwendung einsetzt. Wenn du die Verbindung direkt steuern möchtest, nutze die Anleitungen zu den einzelnen Verbindungsverfahren.
Wie du Vollduplexgespräche mit einem separaten Backend führst, an das du Aufgaben delegierst, erfährst du in der Anleitung zu GPT-Live. Einen Vergleich von Architekturen für Sprachanwendungen und Pipelines mit mehreren aufeinanderfolgenden Verarbeitungsschritten findest du im Leitfaden zu Sprachagenten.
Einen Speech-to-Speech-Agenten entwickeln
Nutze die Realtime API, wenn sich die Interaktion wie ein direktes Gespräch anfühlen soll. Sie ist der beste Ausgangspunkt für Sprachagenten, die sich beim Sprechen unterbrechen lassen, schnell mit der Audioausgabe beginnen, einen natürlichen Sprecherwechsel ermöglichen und Tools in Echtzeit nutzen sollen.
Im Browser läuft eine Sitzung üblicherweise so ab:
- Dein Anwendungsserver erstellt für die Realtime-Sitzung ein kurzlebiges Client-Secret.
- Dein Frontend erstellt eine
RealtimeSession. - Die Sitzung stellt im Browser eine Verbindung über WebRTC her, auf dem Server über WebSocket.
- Innerhalb der Sitzung verarbeitet der Agent gesprochene Beiträge und Unterbrechungen, ruft Tools auf und übernimmt die Übergabe an andere Agenten.
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
const ephemeralKey = process.env.OPENAI_REALTIME_EPHEMERAL_KEY;
if (!ephemeralKey)
throw new Error("Set OPENAI_REALTIME_EPHEMERAL_KEY from your server.");
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: ephemeralKey,
});Anschließend kannst du dem RealtimeAgent wie einem Textagenten Tools, Übergaben und Schutzmechanismen hinzufügen. Kümmere dich in der Sitzungsschicht um die Übertragung der Audiodaten und lege die Geschäftslogik in der Agentendefinition fest.
Wenn du die Verbindung auf Protokollebene steuern möchtest, beginne mit der Dokumentation zur Datenübertragung:
Sicherheitskennungen
Wenn deine Anwendung einzelne Personen identifiziert, die sie nutzen, sende bei Anfragen an die Realtime API eine Sicherheitskennung mit. OpenAI empfiehlt Sicherheitskennungen, ihre Verwendung ist aber freiwillig. Sie helfen OpenAI, schädliches Verhalten zu erkennen und Maßnahmen gezielt auf die betreffende Person zu beschränken, statt die gesamte Organisation einzubeziehen. Verwende einen stabilen Wert, der die Privatsphäre schützt, etwa den Hash einer internen Benutzer-ID.
Sende die Kennung bei Anfragen an die Realtime API im Header OpenAI-Safety-Identifier. Wenn du kurzlebige Tokens verwendest, setze den Header bei der serverseitigen Anfrage, die das Client-Secret erstellt. Dadurch wird die Kennung der Sitzung zugeordnet. Wenn du die Verbindung von einem vertrauenswürdigen Server über WebSocket oder die einheitliche WebRTC-Schnittstelle herstellst, setze den Header bei der Verbindungsanfrage.
Sicherheitskennungen aus Anfragen an die Responses API oder aus anderen Sitzungen werden nicht automatisch übernommen. Wenn du an anderer Stelle in deiner Anwendung den Parameter safety_identifier der Responses API verwendest, übergib denselben stabilen Wert jedes Mal, wenn du eine Realtime-Sitzung erstellst oder eine Verbindung zu ihr herstellst.
Von der Beta-Version zur allgemein verfügbaren Version (GA) migrieren
Wenn deine Realtime-Integration noch die Beta-Schnittstelle nutzt, stelle sie auf die GA-Schnittstelle um, bevor du mit neuen Arbeiten beginnst. Die wichtigsten Änderungen sind:
- Entferne bei Aufrufen der GA-Schnittstelle den Header
OpenAI-Beta: realtime=v1. - Verwende
POST /v1/realtime/client_secrets, um kurzlebige Zugangsdaten für Browser oder mobile Clients zu erstellen. - Verwende
/v1/realtime/calls, wenn du WebRTC-Sitzungen aufbaust. - Passe die Datenstrukturen für Sitzungen und Ereignisse an die GA-Schnittstelle an. Setze insbesondere
session.type, verschiebe die Konfiguration der Audioausgabe untersession.audio.outputund verwende für Antwortereignisse die neueren Namen wieresponse.output_text.delta,response.output_audio.deltaundresponse.output_audio_transcript.delta. - Wenn du eine Speech-to-Speech-App migrierst, beginne mit dem Browserbeispiel. Wenn du einen Transkriptionsworkflow migrierst, nutze die Anleitung zur Echtzeittranskription.
Den aktuellen Ablauf für die GA-Schnittstelle findest du in der Referenz zu Realtime-Clientereignissen, in der Referenz zu Realtime-Sitzungen und im Browserbeispiel.
Nächste Schritte
- Gespräche verwalten: Konfiguriere Sitzungen und verarbeite Audio, Text und Ereignisse.
- Sprachaktivität erkennen: Konfiguriere die automatische Erkennung von Redebeiträgen.
- Tools und MCP: Füge Funktionen, MCP-Server und Konnektoren hinzu.
- Prompts für Sprachmodelle: Nutze die Anleitung für dein Realtime-Modell.
- Kosten optimieren: Erfahre, wie die Realtime API die Nutzung abrechnet und Daten zwischenspeichert.
- Serverseitige Steuerung: Führe Tools auf deinem Server aus und steuere dort die Sitzung.
Weitere Audio-Workflows
Die Auswahlhilfe für Workflows und die gemeinsamen Audiobegriffe findest du jetzt im Leitfaden Audio und Sprache. Für fortlaufende Übersetzungen nutze die Anleitung zur Live-Übersetzung. Für Live-Untertitel nutze die Anleitung zur Live-Transkription, für Audioaufnahmen die Anleitung zur Transkription von Dateien.