connic Voice

Agenten konfigurieren

version: "1.0"
name: voice-assistant
type: llm
model: openai/gpt-realtime-2.1
description: "Ein hilfreicher Sprachassistent"
system_prompt: |
  Antworte kurz und natürlich in der Sprache des Nutzers.
  Sage vor einem Tool-Aufruf kurz, was du prüfst,
  und rufe das Tool in derselben Antwort auf.
  Verabschiede dich, bevor du das Gespräch beendest.
voice_config:
  transcription_model: gpt-realtime-whisper
  greeting: "Hallo! Wie kann ich helfen?"
  thinking_sound: true

Stelle den Agenten bereit und verknüpfe ihn mit einer Verbindung, die Voice unterstützt. Eine Voice-Verbindung im Sync-Modus nimmt Anrufe an; im Outbound-Modus ruft jeder Run des Agenten die Nummer aus seiner Eingabe an.

voice_config: {} aktiviert Voice mit den Standardeinstellungen. Ohne greeting wartet der Agent, bis die andere Seite zuerst spricht, bei eingehenden wie bei ausgehenden Anrufen.

Voice-Konfiguration

Dieses Beispiel zeigt alle Einstellungen unter voice_config. Die angegebenen Werte überschreiben die Standardeinstellungen. Die Stimme muss zum gewählten Provider passen; alloy ist hier eine Stimme für OpenAI.

model: openai/gpt-realtime-2.1
voice_config:
  voice: alloy
  language: de
  transcription_model: gpt-realtime-whisper
  greeting: "Hallo! Wie kann ich helfen?"
  thinking_sound: true
  hang_up_allowed: true
  press_keys_allowed: true
  wait_on_hold_allowed: true
  max_hold_seconds: 1800
  turn_detection:
    silence_ms: 500
  interruptions:
    enabled: true
    min_speech_ms: 500
  idle_timeout_seconds: 60

Alle Felder sind optional. Wenn interruptions angegeben wird, ist darin enabled erforderlich.

Modelle und Provider

Auf connic/ folgt ein verwaltetes Voice-Modell; dafür brauchst du keine Zugangsdaten eines Providers. Mit eigenen Zugangsdaten folgt auf openai/, azure/, gemini/ oder vertex_ai/ der Modellname beziehungsweise der Name des Azure-Deployments. Der Provider prüft dann, ob das Modell verfügbar ist und Realtime-Audio unterstützt. Welche Stimmen zur Auswahl stehen, hängt vom Modell ab. Ohne voice gilt seine Standardstimme. connic/gemini-3.8-live nutzt die Stimmnamen von Gemini, etwa Kore.

Über reasoning_effort am Agenten lässt sich eine Reasoning-Stufe anfordern. connic gibt die Einstellung an den Provider weiter. Dieser lehnt nicht unterstützte Einstellungen oder Werte ab. Ohne Angabe oder mit auto gilt der Modellstandard. Zum Beispiel unterstützt gemini/gemini-3.8-live-extended-thinking die Stufen low, medium und high.

Datenstandort

Wo das Modell und der Telefonanbieter einen Anruf verarbeiten, hängt von deren eigenen Einstellungen ab:

• connic führt seine Voice-Modelle in der EU aus. Der Provider bewahrt die Sitzung eines Anrufs bis zu 24 Stunden auf, damit lange Anrufe weiterlaufen, wenn die Verbindung zum Modell erneuert wird.
• Vertex AI führt das Modell an dem Standort aus, der mit den Vertex-AI-Zugangsdaten des Projekts gespeichert ist. Mit eu, der EU-Multiregion, bleibt die Verarbeitung in der EU.
• Azure OpenAI führt das Modell in der Region deiner Azure-Ressource aus. Lege die Ressource in einer EU-Region an und stelle das Modell als Data-Zone-Deployment bereit.
• OpenAI nimmt Anrufe über seinen Standard-Endpunkt an, der keine Regionseinstellung hat.
• Gemini mit API-Schlüssel hat keine Regionseinstellung. Den Standort wählst du über Vertex AI.
• Twilio: Die Region der Verbindung legt nur fest, welche Twilio-API connic nutzt. Welche Twilio-Region einen Anruf verarbeitet, stellst du an der Nummer in Twilio ein.
• Telnyx leitet das Audio eines Anrufs über die AnchorSite seiner Call-Control-Anwendung. Stelle an der Anwendung im Telnyx-Portal einen europäischen Standort ein; connic ändert diese Einstellung nicht.
• SIP-Anrufe nehmen den Weg deiner Telefonanlage oder deines Anbieters.

Abrechnung

Ein Anruf ist ein Run. connic berechnet den Start des Runs und die Laufzeit sekundengenau, vom Start des Runs bis zum Ende des Anrufs. Das Klingeln eines ausgehenden Anrufs und die Zeit in einer Warteschleife zählen also mit. Eine eigene Voice-Gebühr gibt es nicht. Bei einem Voice-Modell unter connic/* rechnet connic die Audio- und Text-Tokens zu den Preisen im Modellkatalog über das Projektguthaben ab. Ist das Guthaben aufgebraucht, endet der Anruf. Mit eigenen Zugangsdaten rechnet der Modell-Provider die Tokens über dein Konto ab. Den Anruf rechnet dein Telefonanbieter ab. Siehe Preise.

Tools und Gesprächsablauf

Während des Gesprächs kann der Agent Python-Tools ausführen, Wissen per Retrieval abrufen, MCP-Tools nutzen und Aufgaben an andere Agenten delegieren. Tool Hooks, bedingte Tools und die Tool-Suche funktionieren wie bei anderen Agenten. Die before- und after-Middleware läuft zu Beginn und am Ende des gesamten Runs.

Der Agent sollte einen Tool-Aufruf kurz ankündigen, etwa mit „Ich schaue kurz nach“. Standardmäßig ist ein leiser, wiederkehrender Ton zu hören, während Tools laufen oder der Provider Arbeit im Hintergrund meldet. Der Ton pausiert, sobald der Nutzer oder der Agent spricht. Mit thinking_sound: false lässt er sich ausschalten.

connic speichert kein Audio von Anrufen. Das Transkript ist die Ausgabe des Runs: In den Run-Details lassen sich die Antworten des Agenten und bei aktivierter Transkription auch die Nutzerbeiträge nachlesen. Fehler bei der Transkription werden dort angezeigt; das Gespräch läuft weiter. Die Traces zeigen, welche Tools der Agent genutzt hat und wie lange die einzelnen Schritte gedauert haben. Wenn der Provider Reasoning-Zusammenfassungen zurückgibt, erscheinen sie ebenfalls im Trace. Die Audio- und Text-Tokens, die der Provider für jede Antwort meldet, erscheinen in der Token-Nutzung des Runs und unter Token Usage.

Anrufdaten

Ein ausgehender Anruf gehört zu dem Run, der ihn ausgelöst hat, und dieser behält seine eigene Eingabe. Sein Kontext enthält weder eine Anruf-ID noch Rufnummern, und context["connector_id"] ist die Verbindung, die den Run gestartet hat, nicht die Voice-Verbindung. Was der Agent wissen muss, etwa den Grund des Anrufs, gehört in die Eingabe des Runs. Ein eingehender Anruf startet den Run mit diesen Anrufdaten als Eingabe:

{
  "call_id": "<Anruf-ID des Providers>",
  "from": "+4915112345678",
  "to": "+4930123456789",
  "provider": "<Voice-Verbindung>",
  "caller_name": "Alex Beispiel",
  "forwarded_from": "+4940123456789",
  "raw": {}
}

call_id ist die Kennung des Anrufs beim Provider, provider nennt die Voice-Verbindung, die den Anruf empfangen hat. caller_name und forwarded_from sind nur enthalten, wenn der Provider einen Anrufernamen oder die weiterleitende Nummer sendet. raw enthält die vollständige Anfrage des Providers zum eingehenden Anruf. Die Seite der jeweiligen Voice-Verbindung beschreibt, was ihr Provider sendet.

Middleware liest die Daten aus context["payload"], Tools über ihren context-Parameter. Das Modell erhält sie als erste Nachricht, sofern die before-Middleware sie nicht ersetzt. Die Middleware kann den Anrufer identifizieren, das Ergebnis in context speichern und über bedingte Tools festlegen, welche Tools der Agent erhält.

Anruf weiterleiten

Ein Tool oder Tool Hook leitet den Anrufer weiter, indem es TransferCall mit einer Rufnummer im E.164-Format auslöst. Bereits laufende Sprachausgabe wird zuerst zu Ende gespielt. Die Nummer muss zu den Weiterleitungsnummern der Voice-Verbindung gehören. Andernfalls gibt der Tool-Aufruf einen Fehler zurück und der Agent kann den Anrufer darüber informieren.

from connic import TransferCall


def transfer_to_sales(context: dict) -> str:
    """Leitet den Anrufer an das Vertriebsteam weiter."""
    raise TransferCall("+4930123456789")

Bedingungen für die Weiterleitung gehören in das Tool. Im Playground endet die Sitzung und zeigt die Nummer an, statt sie zu wählen. Meldet sich unter der Weiterleitungsnummer niemand, endet der Anruf. Voice-Verbindungen im Sync-Modus können eingehende Anrufer außerdem an eine Ausweichnummer weiterleiten, wenn der Agent einen Anruf nicht annehmen oder nicht zu Ende führen kann. Für Weiterleitungen und ausgehende Anrufe gilt die Ausweichnummer nicht.

Die Weiterleitung beendet den Run regulär, die after-Middleware läuft also weiterhin. Der Trace zeigt die Weiterleitung und ihre Nummer im Schritt des Tools. context hält sie nicht fest. Muss after von der Weiterleitung wissen, setzt das Tool vor TransferCall einen Schlüssel wie context["transferred_to"].

Tastatureingaben

keypad ordnet Tasten Tools zu. Ein Tastendruck führt sein Tool direkt aus, ohne Modellantwort. Das funktioniert jederzeit während des Anrufs, auch während der Begrüßung. Jedes Tool muss unter tools stehen und darf keine Pflichtparameter haben. Löst ein Tastatur-Tool TransferCall aus, bricht die aktuelle Sprachausgabe ab und der Anruf wird sofort weitergeleitet.

tools:
  - phone.transfer_to_sales
  - phone.transfer_to_operator
voice_config:
  greeting: "Willkommen. Um die Zentrale zu erreichen, drücken Sie jederzeit die 0."
  keypad:
    "0": phone.transfer_to_operator

Jeder Tastendruck wird im Run festgehalten. Tasten ohne Zuordnung und Tasten, deren bedingtes Tool für den Anruf nicht ausgewählt wurde, lösen nichts aus. Der Playground zeigt während Voice-Sitzungen eine Tastatur.

Telefonmenüs

Mit dem integrierten Tool press_keys drückt der Agent Telefontasten, etwa um in einem Telefonmenü eine Option zu wählen oder eine abgefragte Nummer einzugeben. Es nimmt die Tasten 0-9, * und # sowie w für eine halbe Sekunde Pause, bis zu 64 auf einmal, zum Beispiel 1w2#. Die Tasten erklingen der Reihe nach im Anruf, danach wartet der Agent auf die Antwort des Menüs. Jeder Tastendruck wird im Run festgehalten, und die Traces zeigen die Tasten im Schritt des Tools.

Das Tool funktioniert mit jeder Voice-Verbindung gleich. Im Playground werden die Tasten angezeigt statt gesendet. Mit press_keys_allowed: false entfällt das Tool.

Warteschleifen

Mit wait_on_hold_allowed: true erhält der Agent das integrierte Tool wait_on_hold. Er ruft es auf, sobald der Anruf in einer Warteschleife landet. Während er wartet, bekommt das Voice-Modell kein Audio, der Provider berechnet also keine Tokens, und der Agent antwortet nicht. Die Wartezeit zählt weder für max_iterations noch für idle_timeout_seconds.

system_prompt: |
  Du rufst Lieferanten an und fragst, wann eine offene Bestellung verschickt wird.
  Wähle im Telefonmenü mit press_keys die Option für den Bestellstatus.
  Wenn du in die Warteschleife kommst, rufe wait_on_hold auf. Sobald sich
  jemand meldet, sag, wer du bist und um welche Bestellung es geht.
voice_config:
  language: de-DE
  wait_on_hold_allowed: true
  max_hold_seconds: 2400

connic hört in die Leitung, bis sich jemand meldet. Ein Mensch grüßt und macht dann eine Pause, um auf eine Antwort zu warten. Musik und Bandansagen spielen dagegen weiter. Folgt auf Sprache eine ruhige Leitung, weckt connic den Agenten und gibt ihm das Gesagte weiter, damit er auf die Begrüßung antworten kann. Weckt eine Ansage den Agenten und geht er wieder in die Warteschleife, ohne zu sprechen, erkennt connic diese Ansage und weckt ihn ihretwegen nicht noch einmal. Die Erkennung funktioniert bei jedem Provider gleich. Der Run hält jedes Wecken fest und wie lange der Agent gewartet hat.

Eine Ansage, auf die eine ruhige Pause folgt, etwa in einer Warteschleife ohne Musik, weckt den Agenten beim ersten Abspielen. Meldet sich ein Mensch bei lauten Hintergrundgeräuschen, kann es einen Moment länger dauern, bis connic ihn erkennt. Weise den Agenten im Prompt an, erneut wait_on_hold aufzurufen, wenn ihn Musik oder eine Ansage geweckt hat.

max_hold_seconds beendet den Anruf, sobald eine Wartezeit so lange dauert, und der Run schlägt mit diesem Grund fehl. Eine Wartezeit reicht vom ersten wait_on_hold, bis der Agent nach dem Wecken spricht.

Gespräch beenden

Der Agent kann das Gespräch selbst beenden. Die Verabschiedung wird vollständig abgespielt, bevor das Gespräch endet. Im Prompt lässt sich festlegen, wann der Agent das Gespräch beenden soll. Diese Einstellung deaktiviert die Funktion:

voice_config:
  hang_up_allowed: false

Anrufdauer

Ein Gespräch ist ein Run. Seine maximale Dauer bestimmt daher der timeout des Agenten, begrenzt durch das Run-Timeout deines Plans. Bei Pro sind das 60 Minuten. Ist sie erreicht, endet der Anruf. Jede Antwort des Agenten zählt für max_iterations; Antworten, mit denen er nur wieder in die Warteschleife geht, zählen nicht.

Anrufe, die bei Gemini, Vertex AI und connic/gemini-3.8-live länger als etwa 15 Minuten dauern, brauchen context_compression; ohne diese Einstellung beendet der Provider den Anruf. Mit Komprimierung verwirft oder fasst der Provider den ältesten Teil des Anrufs zusammen und behält die Anweisungen. Bei Voice-Agenten nimmt context_compression die Einstellungen enabled und max_prompt_tokens. Mit max_prompt_tokens startet die Komprimierung, sobald der Anruf so viele Tokens erreicht. OpenAI und Azure OpenAI verwerfen die ältesten Beiträge, sobald ein Anruf das Kontextfenster füllt; max_prompt_tokens legt fest, wie viele Tokens sie behalten.

context_compression:
  max_prompt_tokens: 20000

Aktuelle Einschränkungen

Voice ist nur für Agenten mit type: llm und einem Voice-Modell von connic, OpenAI, Azure OpenAI, Google Gemini oder Google Vertex AI verfügbar. Andere Modelle unter connic/* unterstützen Voice nicht. connic lehnt Voice-Konfigurationen mit Input- oder Output-Guardrails, menschlichen Freigaben, strukturierter Ausgabe (output_schema oder output_schema_dict) oder fallback_model ab. Der Audiostream erreicht das Modell und den Nutzer direkt. Guardrails können ihn deshalb nicht vor der Übertragung prüfen.

Automatisierte Agententests unterstützen Voice noch nicht. Teste den bereitgestellten Agenten im Gespräch.