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

Sprachagenten

Wähle zwischen GPT-Live, Sitzungen mit der Realtime API und mehrstufigen Sprachpipelines.

Mit Sprachagenten können Menschen im Gespräch mit deiner Anwendung Fragen stellen und Aufgaben erledigen. Beim Entwurf entscheidest du, wie du Sprache mit Reasoning und Tools verbindest. Du kannst ein fortlaufendes Gespräch mit einem separaten Backend unterstützen, ein einziges Modell für den Sprachdialog einsetzen oder eine Pipeline verwenden, in der du jede Stufe selbst steuerst.

Die passende Architektur wählen

Architektur Geeignet für Vorteile
GPT-Live Vollduplex-Gespräche mit separatem Backend Du kannst deinen bestehenden Text-Workflow beibehalten und das Backend unabhängig wählen. Das Gespräch läuft während der Verarbeitung weiter.
Realtime API Sprache, Reasoning und Tool-Nutzung in einer Sitzung Ein einziges Modell interpretiert die Audioeingabe, entscheidet über das weitere Vorgehen und antwortet in gesprochener Sprache.
Mehrstufige Sprachpipeline Kontrolle über jede Stufe der Sprach- und Textverarbeitung Du kannst Zwischenergebnisse in Textform prüfen oder bearbeiten und jede Komponente einzeln austauschen.

Einen Vollduplex-Sprachagenten entwickeln

GPT-Live kann gleichzeitig zuhören und sprechen. Diese Fähigkeit heißt Vollduplex. Das Live-Modell führt das Gespräch und überlässt Reasoning und Tool-Aufrufe einem separaten Backend. Während das Backend arbeitet, können die Gesprächsteilnehmenden weitersprechen.

Du kannst deinen bestehenden Text-Workflow samt Geschäftslogik und Tools beibehalten und GPT-Live als Sprachschnittstelle ergänzen. Der Delegationsmodus bestimmt, wer die Aufgaben im Backend ausführt und den Gesprächskontext dafür bereitstellt.

  • Client-Delegation: Binde deinen eigenen Agenten oder Workflow an. Backend-Modell und Anbieter wählst du selbst. Deine Anwendung führt die Aufgaben aus und gibt die Ergebnisse an GPT-Live zurück.
  • Responses-Delegation: Wähle für Reasoning und Tool-Nutzung im Backend ein von OpenAI gehostetes Responses-Modell. GPT-Live liefert den Gesprächskontext und verwaltet die Aufrufe dieses Modells. Eigene Funktionen führt weiterhin deine Anwendung aus.

In beiden Modi verwaltet deine Anwendung die Berechtigungen und Geschäftsdaten. Lege im Prompt des Live-Modells fest, wie es sprechen soll. Die Geschäftsregeln gehören in den Backend-Prompt.

Beginne mit dem Leitfaden Erste Schritte mit GPT-Live. Wie du das Backend einrichtest, erfährst du in Delegation und Tools. Wie du das Sprechverhalten steuerst, erklärt der Leitfaden Prompts für Sprachmodelle.

Einen Sprachagenten mit Speech-to-Speech entwickeln

Für den Einstieg mit der Realtime API im Browser verwendest du einen RealtimeAgent und eine RealtimeSession. Die Sitzung verwaltet gesprochene Gesprächsbeiträge, Tools, Unterbrechungen und Übergaben. Das vollständige Einstiegsbeispiel findest du jetzt im Leitfaden Erste Schritte mit der Realtime API.

Einen mehrstufigen Sprach-Workflow entwickeln

Wähle eine mehrstufige Pipeline, wenn du den Text zwischen Spracherkennung, Agent und Sprachausgabe prüfen oder bearbeiten möchtest. Deine Anwendung steuert drei Stufen:

  1. Sprache in Text umwandeln
  2. Den Agenten-Workflow ausführen
  3. Text in Sprache umwandeln
Eine mehrstufige Sprachpipeline ausführen
import asyncio
import numpy as np

from agents import Agent, function_tool
from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline


@function_tool
def get_weather(city: str) -> str:
    """Get the weather for a given city."""
    return f"The weather in {city} is sunny."


agent = Agent(
    name="Assistant",
    instructions="You are a helpful voice assistant.",
    model="gpt-6-astra",
    tools=[get_weather],
)


async def main() -> None:
    pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
    audio_input = AudioInput(buffer=np.zeros(24000 * 3, dtype=np.int16))
    result = await pipeline.run(audio_input)
    async for event in result.stream():
        if event.type == "voice_stream_event_audio":
            print("Received audio bytes", event.data.nbytes)


if __name__ == "__main__":
    asyncio.run(main())

Dieser Ansatz eignet sich, wenn jede Stufe einsehbar oder austauschbar sein muss. Du kannst zum Beispiel das Transkript speichern, die Einhaltung von Richtlinien prüfen, bevor der Textagent antwortet, und interne Systeme aufrufen. Erst wenn im Workflow eine freigegebene Antwort vorliegt, erzeugst du die Sprachausgabe.

Deinen Sprachagenten evaluieren

Teste sowohl das Gespräch als auch das Ergebnis der Aufgabe. Bei einem Buchungsassistenten hörst du dir beispielsweise die Bestätigung an und prüfst, ob der richtige Termin gespeichert wurde.

  1. Wähle repräsentative Szenarien und lege die erwarteten Ergebnisse, Tool-Aufrufe und Berechtigungen fest.
  2. Speichere die Audiodaten, Ereignisse, Tool-Ergebnisse und den Anwendungszustand, die du zum Prüfen des jeweiligen Ergebnisses brauchst. Unterscheide zwischen einem fehlgeschlagenen Testlauf und einem gültigen Testlauf, in dem der Agent die Aufgabe nicht erfüllt.
  3. Wiederhole die Szenarien und vergleiche, ob der Agent die Aufgabe erfüllt, wie lange es bis zur hörbaren Antwort dauert, wann Unterbrechungen auftreten und wann unerwünschte Gesprächspausen entstehen. Führe die Vergleichstests mit derselben anrufenden Person, derselben Modellkonfiguration, denselben Tools und derselben Transportmethode durch.

Bewerte bei GPT-Live die folgenden Aspekte getrennt:

  • Aufgabenerfüllung und Tool-Ergebnisse: Prüfe, ob die Absicht der anrufenden Person bei der Verarbeitung erhalten bleibt. Kontrolliere die delegierten Aufgaben, die Tool-Argumente, die Berechtigungen und den abschließenden Anwendungszustand. Gleiche die gesprochenen Bestätigungen mit den tatsächlich ausgeführten Aktionen ab.
  • Zeitlicher Gesprächsverlauf: Miss die Zeit bis zur hörbaren Antwort und erfasse unerwünschte Pausen und überlappende Gesprächsbeiträge. Prüfe, ob der Agent bei Unterbrechungen aufhört zu sprechen, auch wenn jemand während der Backend-Verarbeitung eine Angabe korrigiert.
  • Spracherkennung und Sprachausgabe: Teste die Erkennung bei unterschiedlichen Akzenten, Hintergrundgeräuschen, Sprachwechseln, Namen und Zahlen. Beurteile unabhängig von der Erkennung, wie verständlich die Ausgabe ist und welche Sprache der Agent für die Antwort wählt.
  • Zuverlässigkeit der Sitzung: Erfasse Verbindungsfehler, Audioaussetzer, Zeitüberschreitungen und unvollständige Sitzungen getrennt von der Bewertung der Aufgabenerfüllung.

Steigere die Komplexität in drei Teststufen:

  1. Einstieg: Verwende synthetische Sprache, um Anfragen mit nur einer Gesprächsrunde unter kontrollierten Bedingungen zu testen. Nutze für wiederholbare Vergleiche dieselben generierten Audiodaten, denselben Anwendungskontext und dasselbe erwartete Ergebnis.
  2. Erweiterter Test: Spiele repräsentative Aufnahmen von Menschen ab, die Anfragen in einer einzigen Gesprächsrunde stellen. So testest du, wie sich Stimmen, Mikrofone, Pausen und akustische Bedingungen auf das Verhalten auswirken.
  3. Fortlaufender Dialog: Simuliere die anrufende Person unabhängig vom getesteten Agenten und führe fortlaufende Gespräche über mehrere Gesprächsrunden. Teste Rückfragen, geänderte Anforderungen, Unterbrechungen und die Wiederaufnahme des Dialogs, während Gespräch und Backend-Verarbeitung parallel laufen.

Ergänze automatische Bewertungen durch Hörtests mit Menschen. So kannst du die Aussprache, die Natürlichkeit und die Angemessenheit des Gesprächstempos beurteilen.

Ein Evaluierungs-Harness für GPT-Live findest du im Cookbook-Beispiel zur Evaluierung von Sprachagenten.

Ein Evaluierungs-Harness für Realtime und ausgearbeitete Beispiele findest du im Realtime-Evaluierungsleitfaden im OpenAI Cookbook.

Latenz messen

Miss, wie lange Anrufende auf eine hilfreiche gesprochene Antwort warten. Erfasse die Verarbeitungszeit im Backend separat, um Verzögerungen zu lokalisieren. Vergleiche bei ähnlichen Anrufen den Median und das 95. Perzentil.

Vergleiche Frontend-Modelle mit derselben anrufenden Person und derselben Aufnahme. Halte auch das Backend-Modell, den Prompt, die Transportmethode, die Taktung der Audiodaten und die Bewertungsinstanz konstant.

Erfasse bei GPT-Live die Zeitpunkte, die deine Anwendung beobachten kann: Eingang der delegierten Aufgabe, Start der Backend-Anfrage, erstes verwertbares Ergebnis, Beginn und Ende eines Tool-Aufrufs, Übermittlung des Ergebnisses, Eingang der Audiodaten und Wiedergabe auf dem Client. Bei der Client-Delegation kann deine Anwendung ihre Backend-Anfragen direkt einsehen. Bei der Responses-Delegation sind verschachtelte Antwortereignisse und die von deiner Anwendung ausgeführten benutzerdefinierten Tools sichtbar.

Ermittle anhand dieser Messwerte, ob Verzögerungen beim Verbindungsaufbau, bei der Modellverarbeitung, bei Tool-Aufrufen, beim Puffern oder bei der Wiedergabe entstehen. Miss die Zeit bis zu einer kurzen Rückmeldung wie „Ich prüfe das“ getrennt von der Zeit bis zur benötigten Antwort.

Ändere jeweils nur einen Faktor und wiederhole dieselben Szenarien. Prüfe, ob sich schnellere Antworten auch auf die Aufgabenerfüllung, den korrekten Einsatz der Tools oder Unterbrechungen auswirken. Weitere Hinweise findest du im Abschnitt Backend-Latenz reduzieren.

Sprachagenten verwenden dieselben Grundbausteine wie andere Agenten

Mit einer Sprachschnittstelle ändern sich die Datenübertragung und der Ablauf der Audioein- und -ausgabe. Beim Entwurf des Workflows triffst du weiterhin dieselben grundlegenden Entscheidungen.

Wähle zuerst die Audioarchitektur. Gestalte den übrigen Agenten-Workflow anschließend genauso wie für eine textbasierte Anwendung.

Nächste Schritte

Audio- und Sprachfunktionen im Überblick

Finde den passenden Realtime- oder Audioleitfaden für deinen Anwendungsfall.

Gespräche verwalten

Arbeite mit dem Lebenszyklus und dem Ereignismodell von Realtime-Sitzungen.

WebRTC-Verbindung

Binde Audio aus Browsern und von Mobilgeräten direkt an eine Realtime-Sitzung an.

Leitfaden für Realtime-Prompts

Passe Reasoning, einleitende Äußerungen, Tool-Nutzung, die Erfassung von Entitäten und das Sprechverhalten an.