Sprach-KI-Agenten auf localhost: Twilio Media Streams und OpenAI Realtime über einen Tunnel

Ein telefonbasierter Sprach-KI-Agent ist das am wenigsten nachsichtige Ding, das Sie auf einem Laptop betreiben können. Ein Webhook kann erneut versuchen. Eine Seite kann neu geladen werden. Ein Telefonanruf kann das nicht: Wenn Audio für eine halbe Sekunde stockt, hört der Anrufer es.

Twilio Media Streams plus OpenAI’s Realtime API ist eine gängige Methode, um diese Agenten zu erstellen. Eine klassische Sprach-zu-Text → LLM → Text-zu-Sprache-Pipeline ist die andere. Die eigenen Dokumentationen von Twilio listen AI-Agenten als Anwendungsfall für Media Streams auf, und ihre Beispiele verwenden ngrok-ähnliche Hostnamen, weil die Stream-URL öffentlich über TLS erreichbar sein muss. Dieser Leitfaden behandelt, was durch den Tunnel geht, wie das WebSocket-Upgrade durch einen Edge-Proxy funktioniert, wie man sich an ein Turn-Budget von rund 800 ms hält, und warum eine stabile Subdomain die Durchführung von Testanrufen erleichtert.

Warum Sprach-Agenten eine andere Tunnel-Belastung darstellen

Der Großteil des Tunnelverkehrs besteht aus Anfragen und Antworten: Ein Webhook trifft ein, Ihr Server antwortet. Sprach-Übertragung ist ein kontinuierlicher, bidirektionaler Strom aus kleinen Audio-Nachrichten. Twilio sendet das Audio des Anrufers an Ihren Server, und Ihr Server sendet das Audio des Agenten während des gesamten Anrufs über denselben WebSocket zurück.

Im Gegensatz zu einseitigem Streaming wie Server-Sent Events sind Rund-um-Latenz und Jitter in beiden Richtungen gleichzeitig relevant.

Das Audio-Format ist eng und festgelegt. Laut Twilio-Dokumentation meldet die start-Nachricht immer audio/x-mulaw, 8.000 Hz, ein Kanal, und Payloads sind Base64 in JSON codiert. μ-law bei 8 kHz entspricht 8.000 Bytes pro Sekunde, daher hat ein 20 ms-Frame 160 Bytes. Twilio dokumentiert, dass Audio, das Sie zurücksenden, beliebig groß sein kann. Bandbreite ist trivial; Verzögerung ist es nicht.

Die Architektur: zwei URLs, ein Host

Ein Twilio-Sprach-Agent benötigt zwei öffentliche Endpunkte:

1. Ein HTTPS Webhook, den Twilio bei eintreffendem Anruf aufruft. Er gibt TwiML zurück.
2. Ein wss://-Endpunkt, zu dem Twilio nach dem Lesen dieses TwiML verbindet.

Beide können auf demselben Tunnel-Hostname leben:

Caller ──PSTN──> Twilio ──POST /voice──> tunnel edge ──> localhost:5050/voice   (returns TwiML)
                   │
                   └────wss://your-subdomain.example/media ── edge ──> localhost:5050/media
                                                                                   │
                                                              outbound wss to OpenAI Realtime

Die TwiML für einen bidirektionalen Stream verwendet ConnectStream:

Response
  Connect
    Stream url="wss://your-subdomain.example/media"\u003e
      Parameter name="caller" value="+15551230000" /
    /Stream
  /Connect
/Response

Diese Regeln aus Twilio-Dokumentationen gelten für Tunnel-Einrichtungen:

• wss ist das einzige unterstützte Protokoll. Eine einfache ws://-URL funktioniert nicht.
• Die url unterstützt keine Abfragezeichenfolgen. Per-Aufruf-Daten werden stattdessen mit Parameter-Elementen übertragen. Sie landen im WebSocket-start-Nachrichtenfeld unter customParameters. Die kombinierte Länge von Name und Wert jedes Parameters muss unter 500 Zeichen bleiben.
• ConnectStream erzeugt einen bidirektionalen Stream, und Twilio führt spätere TwiML nicht aus, bis Ihr Server die WebSocket-Verbindung schließt.
• Ein Anruf kann gleichzeitig nur einen bidirektionalen Stream aktiv haben, und bidirektionale Streams können nur den inbound_track empfangen.
• Ihr Server muss sichere WebSocket-Verbindungen von Twilio auf TCP-Port 443 akzeptieren, von jeder öffentlichen IP aus, und muss den Header X-Twilio-Signature validieren.
• Sie können keinen bidirektionalen Stream über die REST-Route Stream starten. Er muss von ConnectStream kommen.

Was Twilio sendet und was es zurückerwartet

Twilio sendet connected, start, media, dtmf, mark und stop-Nachrichten. dtmf und mark erscheinen nur bei bidirektionalen Streams. DTMF wird nur in der inbound-Direction unterstützt, sodass Sie Tastenanschläge lesen, aber keine Töne zurücksenden können. Ihr Server kann drei Nachrichtentypen zurücksenden: media, mark und clear.

Eine outbound Audio-Nachricht ist minimal:

{ 
  "event": "media",
  "streamSid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "media": { "payload": "\u003cbase64 mulaw/8000\u003e" }
}

Drei Details verursachen die meisten Bugs wie „es verbindet sich, klingt aber schlecht“:

• Keine Dateikopfzeilen. Die Payload muss rohes μ-law sein. Twilio warnt, dass Header-Bytes den Medienstrom fehlerhaft darstellen können, was normalerweise wie statisches Rauschen oder Klacken klingt.
• Audio wird gepuffert. Twilio spielt media-Nachrichten in der Reihenfolge ab, in der sie empfangen werden. Wenn Sie Audio schneller als Echtzeit senden, was Modell-APIs üblicherweise tun, wird es auf Twilios Seite in die Warteschlange gestellt.
• clear leert den Puffer. Wenn ein Anrufer unterbricht, senden Sie clear. Twilio gibt dann mark-Nachrichten für alle Markierungen zurück, die Sie gesendet hatten und noch nicht abgespielt wurden, damit Sie feststellen können, welches Audio verworfen wurde.

Da der Stream bidirektional ist, stoppt er, wenn der Anruf beendet wird oder wenn Ihr Server die WebSocket-Verbindung schließt. Sie können ihn nicht mit \u003cStop\u003e stoppen. Wenn Ihr Server die Verbindung schließt, fordert Twilio die \u003cConnect\u003e-action-URL an, falls Sie eine festgelegt haben. Andernfalls setzt er mit dem fort, was TwiML nach \u003cConnect\u003e folgt.

Verkabelung von OpenAI Realtime ohne Transkodierung

Der schnellste Weg, Ihr Turn-Budget zu schützen, besteht darin, Resampling zu vermeiden. OpenAI’s PCM-Format unterstützt nur eine Abtastrate von 24 kHz. Die Brücke von Twilio zu PCM bedeutet daher, 8 kHz μ-law hochzuziehen und 24 kHz Audio wieder abzuziehen bei jedem Frame. Eine veröffentlichte Anleitung maß etwa 80 ms zusätzlicher Aufwand pro Turn durch einen naiven Resampler im heißen Pfad.

Stattdessen bitten Sie Realtime direkt um G.711 μ-law und leiten Twilios Payloads unverändert durch. Die GA API akzeptiert audio/pcmu (μ-law) und audio/pcma (A-law) als Session-Audio-Formate. Twilio verwendet μ-law, daher möchten Sie audio/pcmu.

Die beta-Ära flache Felder (input_audio_format: "g711_ulaw") wurden im GA-Schema durch verschachtelte Objekte audio.input.format und audio.output.format ersetzt. Wenn Sie ein älteres Twilio-Beispiel portieren und Schema-Fehler sehen, beginnen Sie dort.

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1",
    "output_modalities": ["audio"],
    "instructions": "You are a concise phone agent.",
    "audio": {
      "input":  { "format": { "type": "audio/pcmu" }, "turn_detection": { "type": "semantic_vad" } },
      "output": { "format": { "type": "audio/pcmu" }, "voice": "marin" }
    }
  }
}

Am 6. Juli 2026 veröffentlichte OpenAI gpt-realtime-2.1 und gpt-realtime-2.1-mini. Das Vollmodell aktualisiert GPT-Realtime-2 mit besserer alphanumerischer Erkennung, Stille- und Rauschbehandlung sowie Verhalten bei Unterbrechungen. Das Mini-Modell ist ein kostengünstigeres Modell für Sprachlogik. OpenAI sagte auch, es habe die p95-Latenz über seine Realtime-Sprachmodelle durch verbessertes Caching um mindestens 25% gesenkt. Modellnamen ändern sich schnell, prüfen Sie daher die aktuelle ID und Preise in OpenAI’s Dokumentation, bevor Sie Code kopieren.

Beide 2.1-Modelle nutzen eine Einstellung für den Reasoning-Effort. Zusammenfassungen von OpenAI’s Richtlinien und ein veröffentlichter Test zeigen denselben Weg: Beginnen Sie niedrig, denn höherer Aufwand erhöht die Latenz. In diesem Test (auf gpt-realtime-2) führte eine Erhöhung des Aufwands von Low zu Medium dazu, dass die mittlere Antwortzeit von ca. 1,1 s auf ca. 1,8 s stieg.

Eine minimale Brücke hat zwei Schleifen, die die Stream-ID gemeinsam nutzen:

# Twilio <- OpenAI Realtime Bridge (FastAPI + websockets); error handling omitted
state = {"stream_sid": None}

async def twilio_to_openai(twilio_ws, openai_ws):
    async for raw in twilio_ws.iter_text():
        msg = json.loads(raw)
        if msg["event"] == "start":
            state["stream_sid"] = msg["start"]["streamSid"]
        elif msg["event"] == "media":
            await openai_ws.send(json.dumps({
                "type": "input_audio_buffer.append",
                "audio": msg["media"]["payload"],   # already base64 mulaw
            }))
        elif msg["event"] == "stop":
            break

async def openai_to_twilio(twilio_ws, openai_ws):
    async for raw in openai_ws:
        ev = json.loads(raw)
        if ev["type"] == "response.output_audio.delta":
            await twilio_ws.send_text(json.dumps({
                "event": "media",
                "streamSid": state["stream_sid"],
                "media": {"payload": ev["delta"]},  # forward untouched
            }))
        elif ev["type"] == "input_audio_buffer.speech_started":
            # caller is talking over the agent: flush what Twilio has queued
            await twilio_ws.send_text(json.dumps({
                "event": "clear",
                "streamSid": state["stream_sid"],
            }))

# run both with asyncio.gather(...)

Die OpenAI-Verbindung geht von Ihrem Rechner aus, sodass nur die Twilio-Seite den Tunnel durchquert. Das hat Auswirkungen auf die untenstehende Latenzbetrachtung.

WebSocket-Upgrade durch den Tunnel-Edge

Ein WebSocket beginnt als HTTP-Anfrage. Der Client sendet einen GET mit Upgrade: websocket, Connection: Upgrade, einem Sec-WebSocket-Key und Sec-WebSocket-Version: 13. Der Server antwortet mit 101 Switching Protocols, und von da an tauschen beide Seiten Frames über dieselbe TCP-Verbindung aus.

Für einen Tunnel-Edge bedeutet das, dass er:

• TLS-Termination, damit Twilio sich zu einer wss://-URL mit gültigem Zertifikat verbinden kann, auf Port 443.
• Die Upgrade-Header weiterleiten an Ihren lokalen Ursprung, statt Upgrade und Connection zu entfernen.
• Frames in beiden Richtungen ohne Pufferung übertragen, denn Pufferung verwandelt beständige Frames in Burst-Übertragungen.
• Die Verbindung während des gesamten Anrufs offen halten. Sprachverkehr ist nie inaktiv, solange der Anruf läuft, daher sind Inaktivitäts-Timeouts selten relevant, aber eine feste Lebensdauer pro Verbindung wäre es.

Testen Sie dies, bevor Sie die Agentenlogik debuggen: Richten Sie einen WebSocket-Client auf Ihre öffentliche wss://-URL, und bestätigen Sie eine 101-Antwort und zurückgesendete Nachrichten. Das schließt die gesamte Edge-Ebene in einer Minute aus.

Die Signaturvalidierung benötigt eine zusätzliche Prüfung. Twilio berechnet X-Twilio-Signature über die öffentliche URL, die sie aufgerufen hat, daher müssen Schema und Host, die Ihr Validierungscode rekonstruiert, mit der öffentlichen Tunnel-URL übereinstimmen, nicht mit localhost. Wenn die Validierung bei einer Direktverbindung klappt, durch den Tunnel jedoch fehlschlägt, vergleichen Sie zuerst diese Werte.

Das Turnbudget im Subsekundenbereich

Die Kennzahl, an der man sich orientieren sollte, ist die Lücke zwischen dem Ende der Aussprache des Anrufers und dem Start der Agentenantwort. AssemblyAI’s Telefon-Agenten-Leitfaden nennt ein realistisches Ziel bei etwa 800 ms, was Anrufer als aufmerksam empfinden. Es heißt, dass der Agent sich ab 1.500 ms gestört anfühlt. Das Beispielbudget reserviert 50–150 ms für Netzwerk und Telefondienste, 150–300 ms für Endpunktermittlung, und mehrere Hundert Millisekunden jeweils für den ersten Token des LLM und das erste Byte der TTS-Ausgabe.

Ein Techsy-Tutorial maß einen Median von ca. 1,1 s und einen p95 von ca. 1,9 s über 40 Twilio-Anrufe auf gpt-realtime-2 mit semantic_vad und geringer Reasoning-Intensität. Ihr Server war in der Nähe der OpenAI-Region gehostet, und der Test lag vor den 2.1-Modellen. Das ist eine Messung eines Anbieters, also betrachten Sie sie als Referenzpunkt, nicht als Benchmark. Die Erkenntnis lautet: 800 ms sind ein Ziel für eine gut optimierte Stack, nicht eine Standard, die Sie kostenlos erhalten.

Was der Tunnel hinzufügt

Nur die Twilio‑Seite durchquert den Tunnel. Der Anrufer-Audio reist Twilio → Edge → Ihren Laptop, und die Antwort reist Laptop → Edge → Twilio. Im Vergleich zu einem Relay, das in der Nähe von Twilio installiert ist, resultiert die zusätzliche Kosten durch den zusätzlichen Hop durch das Edge-Gerät und Ihre letzte Meile, in beide Richtungen. Es hängt von drei Dingen ab, die Sie kontrollieren:

• Entfernung. Die Standard-Region von Twilio ist US1. Media Streams sind außerdem in Ireland (IE1) und Australia (AU1) verfügbar. Wählen Sie die Tunnel-Region, die der Twilio-Region, die Ihre Anrufe verwenden, am nächsten liegt.
• Ihre letzte Meile. WLAN-Jitter oder ein VPN schaden mehr als der Edge-Hop. Verwenden Sie für Tests kabelgebundenes Ethernet.
• Jitter, nicht der Durchschnitt. Ein Pfad, der gelegentlich 200 ms stockt, erzeugt hörbare Lücken, auch wenn der Durchschnitt gut aussieht.

Ich konnte keine veröffentlichte, vendor-neutrale Angabe für das Tunnel-Overhead bei Sprachverkehr verifizieren, messen Sie es daher selbst. Protokollieren Sie, wann input_audio_buffer.speech_stopped ankommt, wann das erste response.output_audio.delta ankommt, und wann Sie die erste media-Nachricht zurück an Twilio senden. Vergleichen Sie es mit einer ausgerollten Basislinie.

Barge-in vermeiden – nicht dem Anrufer ins Wort fallen

Da Twilio ausgehendes Audio puffert, erfolgt die Unterbrechung in drei Schritten:

1. Wenn Realtime meldet, dass der Anrufer zu sprechen begonnen hat (input_audio_buffer.speech_started), senden Sie Twilio eine clear-Nachricht, damit die wartenden Audios stoppen. Die OpenAI‑Session-Konfiguration steuert außerdem, ob ein erkannter Sprachbeginn automatisch die laufende Antwort unterbricht.
2. Senden Sie nach jeder media-Nachricht eine mark-Nachricht, und verwenden Sie die von Twilio zurückgegebenen Markierungen, um zu verfolgen, was tatsächlich abgespielt wurde.
3. Teilen Sie dem Modell mit, was gehört wurde, indem Sie ein conversation.item.truncate-Ereignis für den unterbrochenen Eintrag senden, damit der Verlauf der Konversation mit dem übereinstimmt, was der Anrufer erlebt hat.

Überspringen Sie Schritt 1, beendet der Agent seinen Satz, während der Anrufer spricht. Überspringen Sie Schritt 3, und das Modell glaubt, es habe Dinge gesagt, die der Anrufer nie gehört hat.

Warum eine stabile Subdomain und eine 24-Stunden-Sitzung hilfreich sind

Sprach-Debugging bedeutet viele kurze Anrufe über den Tag verteilt: Prompt anpassen, anrufen, zuhören, wiederholen. Zwei Dinge in der Twilio-Konfiguration sind schmerzhaft mit einer zufälligen, wechselnden URL:

• Der Voice-WebHook der Telefonnummer wird in der Twilio-Konsole konfiguriert. Ändern Sie den Host, und Sie müssen ihn erneut anpassen.
• Die \u003cStream\u003e-URL in Ihrem TwiML muss ein vollständiger wss://-Host sein, und da Abfragezeichenfolgen nicht unterstützt werden, können Sie Routing-Daten nicht in der URL verstecken.

Ein Tunnel, der Ihnen eine stabile Subdomain bietet, löst beide Probleme. Dasselbe Host dient POST /voice und wss://…/media, Sie registrieren den Webhook einmal und das TwiML liest seinen eigenen Host aus der Anfrage. Per-Call-Daten gehen in \u003cParameter\u003e-Werten, und Sie schlüsseln den Status anhand der streamSid- und Call-SID aus der start-Nachricht.

Nach den veröffentlichten Materialien von InstaTunnel dauern kostenlose Sitzungen bis zu 24 Stunden und beinhalten eine benutzerdefinierte, persistent Subdomain, mit längeren Limits in Pro. Prüfen Sie vor dem Vertrauen auf exakte Zahlen die aktuelle Preisübersicht. Für Spracharbeit ist der Nutzen einfach: Ein Tunnel, der einen Arbeitstag übersteht, bedeutet kein erneutes Verbinden oder erneutes Einfügen von URLs während des Tests.

Eine Einschränkung liegt auf der OpenAI-Seite. Eine einzelne Realtime-Sitzung hat eine maximale Dauer von 60 Minuten, daher führt ein langlebiger Tunnel nicht zu einem langlebigen Anruf. Planen Sie Neustarts bei sehr langen Anrufen.

Sicherheit für einen Tunnel, der Telefonverkehr akzeptiert

Ein offener WebSocket, der an eine kostenpflichtige Modell-API bridgt, ist ein Kostenrisiko, wenn ihn jemand findet.

• Validieren Sie X-Twilio-Signature beim Webhook und dem WebSocket-Handshake, und lehnen Sie Fehler ab, bevor der Upstream OpenAI-Socket geöffnet wird.
• Halten Sie API-Schlüssel in Ihrem Serverprozess, niemals in TwiML oder in einem Browser.
• Schließen Sie den Tunnel, wenn Sie fertig sind, und setzen Sie Ausgabenlimits auf Ihrem Modellkonto.
• Verwenden Sie kein Browser-Login-Gate vor Twilio. Es kann kein interaktives Login durchführen, daher ist Signaturvalidierung Ihre Authentifizierung.

Fehlerbehebungs-Checkliste

Legen Sie während des Debuggens eine statusCallback-URL auf \u003cStream\u003e fest. Twilio sendet dort stream-started, stream-stopped und stream-error-Ereignisse, mit einer Fehlermeldung bei Fehlern. Die URL muss absolut und öffentlich erreichbar sein, damit sie denselben Tunnel durchläuft.

Symptom	Wahrscheinliche Ursache
Anruf verbindet sich, trennt sich danach	url ist nicht wss://, Handshake schlägt fehl, oder Signaturvalidierung lehnt die Anfrage ab
Statisch oder Klicks auf der Leitung	Header-Bytes in der Payload, oder falsche Codierung (nicht μ-law 8 kHz)
Chipmunk- oder verzerrte Audio	OpenAI-Sitzung läuft noch auf 24 kHz PCM, während Sie rohes μ-law weiterleiten
Agent spricht über den Anrufer	Kein clear bei Unterbrechung gesendet
Lange, ungleichmäßige Pausen	Resampling im Hot Path, entfernte Tunnel-Region, oder Laptop-Jitter
Funktioniert lokal, scheitert durch Tunnel	Edge leitet Upgrade-Header nicht weiter, oder Signatur-Host-Abweichung
Webhook funktioniert, Stream verbindet sich nie	TLS- oder Port-443-Erreichbarkeit zum WebSocket-Pfad
Schema-Fehler bei session.update	Beta-Stil flache Audiodatenfelder an GA API gesendet

Wann man den Tunnel verlassen sollte

Ein Tunnel dient der Entwicklung. Für die Produktion deployen Sie das Relay in einer Cloud-Region nahe den Twilio-Media-Servern, um Ihren Laptop und einen Hop aus dem Anrufpfad zu entfernen.

Zwei weitere Möglichkeiten, den Relais- oder Audio-Teil zu verkürzen:

• Verlassen Sie das WebSocket-Relay mit SIP. OpenAI’s Realtime API akzeptiert SIP-Anrufe. In Twilios Anleitung verwendet ein Elastic SIP Trunk eine Origination-URI der Form sip:proj_<your_project_id>@sip.api.openai.com;transport=tls. OpenAI löst dann einen realtime.call.incoming-Webhook an Ihren Server aus, und Ihr Server akzeptiert den Anruf über die Realtime Calls API. Sie tauschen die Kontrolle des Audio-Pfads gegen weniger bewegliche Teile ein. Ein Tunnel hilft trotzdem, weil dieser Webhook während der Entwicklung eine öffentliche URL benötigt.
• Lassen Sie Twilio die Spracherkennung übernehmen. Wenn Sie kein rohes Audio benötigen, verweist Twilio auf ConversationRelay, wo Twilio Spracherkennung und Text-to-Speech für Sie übernimmt.

FAQ

Braucht Twilio Media Streams zwingend wss://? Ja. wss ist das einzige unterstützte Protokoll für \u003cStream\u003e, und Twilio erwartet, dass Ihr Server sichere WebSocket-Verbindungen über TCP-Port 443 akzeptiert.

Welches Audio-Format verwendet Twilio? μ-law (audio/x-mulaw), 8.000 Hz, mono, base64-kodiert in JSON. Ausgehendes Audio muss roh sein, ohne Dateikopfzeilen.

Kann OpenAI Realtime Twilio-Audio direkt verwenden? Ja. Stellen Sie das GA-Audioformat auf audio/pcmu für Eingabe und Ausgabe ein, und Sie können Payloads ohne Transkodierung weiterleiten.

Kann ich Abfrageparameter an die Stream-URL anhängen? Nein. Verwenden Sie \u003cParameter\u003e-Elemente, die in der start-Nachricht ankommen.

Wie schnell sollte ein Sprach-Agent reagieren? Rund 800 ms ist das üblicherweise genannte Ziel, und jenseits von 1.500 ms wirkt es fehlerhaft. Veröffentlichten Tutorial-Messungen liegen näher bei einer Sekunde; messen Sie daher Ihre eigene Stack-Performance.

Quellen

• Twilio: TwiML \u003cStream\u003e
• Twilio: Media Streams WebSocket-Messages
• Twilio: Media Streams Überblick
• Twilio: Connect the OpenAI Realtime SIP Connector with Elastic SIP Trunking
• OpenAI Developer Community: gpt-realtime-2.1 release
• OpenAI: Realtime-Konversationsleitfaden
• OpenAI API-Referenz: Realtime calls
• AssemblyAI: How to create a phone-based voice agent
• Techsy: OpenAI Realtime API voice agent tutorial
• InstaTunnel on DEV: ngrok alternatives in 2026