Onboarding-Handbuch — Aigonex VoiceAgent¶
Zielgruppe: IT-Verantwortliche des Auftraggebers Vorausgesetzt: Grundkenntnisse SIP-Telefonie, eine bestehende Telefonanlage mit SIP-Trunk-Schnittstelle Stand: 2026-06-02
Dieses Handbuch führt Sie Schritt für Schritt von der Registrierung bis zum ersten produktiven Anruf. Wenn Sie unsicher sind, melden Sie sich bei hallo@aigonex.de — wir helfen kostenfrei beim Erst-Setup.
Inhalt¶
- Voraussetzungen
- Konto anlegen und aktivieren
- SIP-Trunk im Dashboard anlegen
- 3CX-Seite konfigurieren
- Andere Telefonanlagen
- Agent anlegen
- Wissensbasis befüllen
- Tools / Webhooks anbinden
- Test-Anruf
- Prompt-Optimierung
- Häufige Probleme & Lösungen
- Nächste Schritte
1. Voraussetzungen¶
Bevor Sie loslegen, sammeln Sie folgende Daten:
- [ ] Externe Rufnummer (DID), unter der der Agent erreichbar sein soll
(z. B.
+49 6322 9564895) - [ ] Zugang zur eigenen Telefonanlage (3CX, Asterisk, FreePBX o. ä.) mit Administrator-Rechten
- [ ] Öffentliche IP-Adresse Ihrer Telefonanlage (für IP-Whitelist
auf Aigonex-Seite). Diese erhalten Sie z. B. über
https://whatismyip.comvon einem Endgerät im selben Netz, oder vom Hosting-Provider Ihrer Cloud-PBX. - [ ] Optional: einen Account bei einem Workflow-Tool wie n8n, Make oder Zapier, falls der Agent Tickets erstellen, CRM-Einträge machen oder Termine buchen soll
- [ ] Optional: einen eigenen LLM-API-Schlüssel (Mistral, OpenAI, Anthropic), falls Sie BYOK statt des Aigonex-Pool-Schlüssels nutzen möchten
2. Konto anlegen und aktivieren¶
2.1 Registrierung¶
- Öffnen Sie
https://dashboard.aigonex.de - Klicken Sie auf „Kostenlos registrieren"
- Tragen Sie ein:
- Firmenname (z. B. „Mustermann GmbH")
- Subdomain / Slug — wird in URLs verwendet, nur Kleinbuchstaben,
Ziffern und Bindestrich (z. B.
mustermann-gmbh) - E-Mail — die Adresse des Haupt-Administrators
- Passwort (mindestens 8 Zeichen)
- Datenschutzerklärung bestätigen → „Account erstellen"
2.2 E-Mail bestätigen¶
Sie erhalten eine Bestätigungs-E-Mail. Klicken Sie auf den Link darin, um Ihr Konto zu aktivieren. Der Link ist 24 Stunden gültig.
2.3 Plan auswählen¶
Nach dem ersten Login erscheint der Plan-Picker. Wählen Sie den für Sie passenden Plan und schließen Sie die Bezahlung ab. Erst danach können Sie Agenten und Trunks live schalten.
2.4 Optional: MFA aktivieren¶
Für mehr Sicherheit empfehlen wir Multi-Faktor-Authentisierung:
- Im Dashboard oben rechts auf das Benutzer-Menü → „Sicherheit"
- „MFA aktivieren" → QR-Code mit einer Authenticator-App (Google Authenticator, 1Password, Bitwarden o. ä.) scannen
- Backup-Codes ausdrucken und sicher verwahren
3. SIP-Trunk im Dashboard anlegen¶
Der SIP-Trunk verbindet Ihre Telefonanlage mit dem Aigonex-VoiceAgent. Sie legen einen Eintrag im Dashboard an, Aigonex bekommt dadurch eine LiveKit-Trunk-ID und eine Dispatch-Rule, mit der wir Anrufe Ihrem Mandanten zuordnen können.
3.1 Neuen Trunk anlegen¶
- Navigation links → „SIP-Trunks" → „+ Trunk hinzufügen"
- Felder ausfüllen:
| Feld | Bedeutung | Beispielwert |
|---|---|---|
| Name | Frei wählbar — Anzeigetitel im Dashboard | 3CX Hauptanlage |
| Status | Aktiv belassen |
Aktiv |
| PBX-Typ | 3CX / Asterisk / FreePBX / Sonstiges |
3CX |
| PBX-Host | DNS-Name oder IP Ihrer Anlage | firma.on3cx.de |
| SIP-Port | In aller Regel 5060 | 5060 |
| Auth-Username | Optional, wenn 3CX einen Benutzer-Authentication erwartet | livekit-agent |
| Auth-Passwort | Zugehöriges Passwort | (Klartext) |
| Richtung | Inbound (Anrufe → Agent), Outbound (Agent → externe Nummer) oder Both |
Inbound |
| Erlaubte IPs | Öffentliche IP Ihrer PBX, mit /32 als CIDR |
87.138.218.2/32 |
| Telefonnummern | PFLICHT bei Inbound! Die externe DID, die im SIP-INVITE als To-Header steht. Mehrere kommagetrennt | +4963229564895 |
- „Speichern"
Wichtig zum Feld „Telefonnummern": Aigonex matched eingehende Anrufe anhand dieser Nummer. Tragen Sie hier die exakte Nummer ein, die Ihre Telefonanlage im SIP-INVITE als To-Adresse sendet — nicht die externe Anrufer-DID, sondern die Ziel-Adresse, die 3CX in der Outbound-Regel für den Trunk konfiguriert. Bei Unsicherheit: einen Testanruf machen und im Aktivitätsprotokoll der PBX die To-Zeile lesen. Stimmt die Nummer hier nicht mit dem überein, was 3CX schickt, wird der Anruf nicht angenommen (siehe Abschnitt 11).
3.2 Trunk-Daten für die PBX¶
Nach dem Speichern zeigt das Dashboard die Aigonex-seitige Konfiguration:
- Aigonex-SIP-Host:
rtc.aigonex.de(entspricht49.12.74.6) - Port:
5060 - Protokoll: UDP oder TCP
- Trunk-ID (intern, wird in der Trunk-Liste angezeigt)
Diese Werte tragen Sie nun in Ihre Telefonanlage ein (Abschnitt 4 für 3CX).
4. 3CX-Seite konfigurieren¶
4.1 SIP-Trunk-Provider in 3CX anlegen¶
- 3CX-Verwaltungs-Konsole → „SIP-Trunks" → „+ SIP-Trunk hinzufügen"
- Provider-Auswahl: „Generic SIP Trunk"
- Felder:
| 3CX-Feld | Wert |
|---|---|
| Hauptrufnummer des Trunks | Ihre externe DID (z. B. +4963229564895) |
| Anzahl gleichzeitiger Anrufe | Gemäß gebuchtem Aigonex-Plan |
| SIP-Server | rtc.aigonex.de |
| SIP-Server-Port | 5060 |
| Outbound-Proxy | (leer lassen) |
| Type of Authentication | „Do not require — IP based" — Aigonex authentifiziert per IP-Whitelist |
| Benutzer-Name | Den im Aigonex-Dashboard hinterlegten Auth-Username (falls Sie Auth nutzen) |
| Authentication ID / Passwort | Wie im Dashboard hinterlegt |
- „OK" → Trunk speichern
4.2 Inbound-Regel anlegen (eingehende Anrufe an den Agent leiten)¶
Pro DID, die auf den Agent gehen soll:
- In 3CX: „Inbound-Regeln" → „Hinzufügen"
- „DID/DDI"-Nummer: die externe Nummer (z. B.
+4963229564895) - „Wenn alle Büros geschlossen / während der Arbeitszeit": beide Fälle auf „An den Trunk weiterleiten" → den eben angelegten Aigonex-Trunk wählen
- Speichern
4.3 Outbound-Regel für Outbound-Kampagnen (optional)¶
Nur falls Sie Outbound-Kampagnen nutzen wollen:
- „Outbound-Regeln" → „Hinzufügen"
- Routing-Pattern: definieren Sie, welche Nummern über den
Aigonex-Trunk gewählt werden sollen (z. B. „beginnt mit
+49") - Routes: Aigonex-Trunk als erstes Ziel
- Speichern
4.4 Verifizieren¶
Im 3CX-Aktivitätsprotokoll (Logs) sollten Sie nach einem Testanruf
SIP-INVITE-Pakete sehen, die an rtc.aigonex.de:5060 gesendet werden.
Die im Feld „To" stehende Nummer muss exakt mit der im
Aigonex-Dashboard hinterlegten Trunk-Telefonnummer übereinstimmen.
5. Andere Telefonanlagen¶
Aigonex VoiceAgent funktioniert mit jeder SIP-2.0-konformen Anlage. Spezifische Hinweise:
Asterisk / FreePBX¶
Im pjsip.conf (oder über die FreePBX-GUI):
[aigonex]
type=endpoint
transport=transport-udp
context=from-aigonex
disallow=all
allow=ulaw,alaw,opus
aors=aigonex
direct_media=no
[aigonex]
type=aor
contact=sip:rtc.aigonex.de:5060
[aigonex]
type=identify
endpoint=aigonex
match=49.12.74.6
Sonstige¶
Die folgenden Eckdaten sollten in jeder PBX konfigurierbar sein:
- SIP-Endpunkt:
rtc.aigonex.de:5060 - Authentifizierung: IP-basiert (Aigonex whitelisted Ihre PBX-IP) oder optional Username/Passwort
- Codecs: G.711 (ulaw/alaw), Opus
- DTMF: RFC 2833
- NAT: Aigonex steht selbst hinter einem öffentlichen Netz; wenn Ihre PBX hinter NAT steht, aktivieren Sie SIP-NAT-Traversal in der PBX
6. Agent anlegen¶
6.1 Neuen Agent anlegen¶
- Navigation → „Agenten" → „+ Agent erstellen"
- Tab „Allgemein":
| Feld | Empfehlung |
|---|---|
| Name | Wie Sie den Agent intern nennen wollen (z. B. „Telefonzentrale") |
| Status | Aktiv |
| SIP-Trunk | Den eben angelegten Trunk auswählen |
| LLM-Provider | Mistral (EU-Empfehlung) oder Azure OpenAI |
| LLM-Modus | Managed (Aigonex stellt den Pool-Key) oder BYOK |
| LLM-Modell | mistral-large-latest / gpt-4o / claude-opus-4-7 |
| Temperatur | 0.6 für natürliche Antworten, 0.3 für striktere Befolgung |
| TTS-Stimme | Seraphina (multilingual, weiblich) oder Katja |
| STT-Sprache | Deutsch (Deutschland) |
| Sprechgeschwindigkeit | 100 % (Normal) — bei Bedarf zwischen 80 und 130 % experimentieren |
| Sprechstil | customerservice oder friendly |
6.2 Ansagen¶
- Tab „Ansagen":
| Feld | Beispiel |
|---|---|
| Wer beginnt das Gespräch? | Agent spricht zuerst für Inbound |
| Begrüßungsansage | Guten Tag, Sie sind bei der Mustermann GmbH. Was kann ich für Sie tun? |
| Abschlussansage | Vielen Dank für Ihren Anruf, einen schönen Tag noch. |
6.3 System-Prompt¶
- Tab „System-Prompt" — die Verhaltensanweisung für den Agenten. Ein Minimal-Beispiel:
Du bist die KI-Telefonassistentin der Mustermann GmbH. Sieze alle Anrufer.
Sprich natürlich und in kurzen Sätzen. Sage niemals "z.B." sondern "zum
Beispiel". Beende jedes Gespräch mit "Vielen Dank für Ihren Anruf" und
rufe dann end_call auf.
## Routing
- Technische Fragen → Ticket aufnehmen über das Tool ticket_erstellen
- Buchhaltung → transfer_call(department="Buchhaltung")
- Vertrieb → transfer_call(department="Vertrieb")
## Regeln
- Maximal ein Satz pro Antwort
- Keine Bestätigungs-Floskeln vor Tool-Calls
- E-Mail-Adressen 1:1 übernehmen, nie korrigieren
Eine ausführliche Vorlage finden Sie im Dashboard unter „Hilfe → Prompt-Vorlagen" (sofern verfügbar) oder über den Support.
6.4 Erweiterte Einstellungen¶
- Tab „Spracherkennung (VAD)" und „Stille-Erkennung" — die Default-Werte sind für die meisten Fälle gut, ändern Sie nur bei Bedarf.
- „Voicemail-Erkennung": bei Outbound-Kampagnen aktivieren, bei reinen Inbound-Agenten kann sie deaktiviert bleiben.
-
Mehrsprachiger Anruf: aktivieren Sie, wenn Anrufer in mehreren Sprachen erwartet werden — wählen Sie bis zu drei zusätzliche Sprachen.
-
„Speichern"
7. Wissensbasis befüllen¶
Die Wissensbasis liefert dem Agenten die Fakten über Ihr Unternehmen, die er im Gespräch wiedergibt.
- Navigation → „Wissensbasis" → „+ Eintrag hinzufügen"
- Pflichtfelder:
| Feld | Beschreibung |
|---|---|
| Kategorie | hintergrundwissen, oeffnungszeiten, datenschutz, eskalation, produkte, sonstiges |
| Titel | Kurzbezeichnung |
| Inhalt | Freier Text, den der Agent dem Anrufer mitteilen darf |
| Aktiv | Aktiv |
Empfehlung: legen Sie diese Einträge gleich am Anfang an:
- Kategorie
hintergrundwissen: Firmenname, Anschrift, Branche, Kerngeschäft, USP - Kategorie
oeffnungszeiten: Geschäftszeiten genau, inkl. Mittagspausen, Wochenenden, Feiertage. Wird vom Agent geprüft, bevor er weiterverbindet. - Kategorie
eskalation: Vorgehen bei verärgerten oder unverständlichen Anrufern (z. B. „freundlich auflegen", „Notfall- Nummer durchgeben", „immer Ticket anlegen")
8. Tools / Webhooks anbinden¶
Tools sind HTTP-Endpunkte, die der Agent während des Gesprächs aufruft — z. B. um ein Ticket im CRM anzulegen oder einen Termin zu buchen. Aigonex liefert vorhandene Endpunkte selbst nicht, der Auftraggeber bringt sie mit (n8n, Make, Zapier, eigene API).
8.1 Tool anlegen¶
- Navigation → „Tools & Integrationen" → „+ Tool hinzufügen"
- Felder:
| Feld | Beschreibung |
|---|---|
| Name | Wie der LLM das Tool im System-Prompt referenzieren soll (z. B. ticket_erstellen). Keine Leerzeichen, Kleinbuchstaben |
| Beschreibung | Erklärung für den LLM, wann das Tool aufgerufen werden soll |
| URL | Ihr Webhook-Endpunkt (HTTPS) |
| Methode | POST (Standard) |
| Auth-Typ | none / bearer / basic |
| Auth-Wert | Token oder user:pass |
| Trigger | Manuell (LLM entscheidet) / Bei Anrufstart / Bei Anrufende |
| Zusätzliche Header (JSON) | Optional, z. B. {"X-API-Version":"2"} |
| Input-Schema (JSON) | Beschreibt dem LLM die erwarteten Felder, z. B. {"name":"string","datum":"YYYY-MM-DD"} |
| Status | Aktiv |
8.2 Tool dem Agent zuweisen¶
Tools werden pro Agent zugeordnet — Sie können also für unterschiedliche Agenten unterschiedliche Tool-Sets aktivieren.
- Im Agent-Bearbeiten-Modus → Abschnitt „Tools für diesen Agent"
- Die gewünschten Tools per Klick auf die Karte aktivieren
- „Speichern"
8.3 Beispiel: Ticket-Erstellung mit n8n¶
Ein einfacher n8n-Workflow:
- Webhook-Trigger → POST, URL kopieren
- Datenverarbeitung → die Felder aus dem JSON-Body extrahieren
- CRM-Knoten (z. B. Nextcloud Deck, HubSpot, Pipedrive) → Ticket mit den extrahierten Feldern anlegen
- Webhook-Response → eine bestätigende Antwort an den Agent
zurückgeben (z. B.
{"message":"Ticket #1234 angelegt"}).
Der Agent liest die message aus der Antwort und sagt sie dem Anrufer
vor.
8.4 Aigonex Termine (optional)¶
Falls Sie zusätzlich das Aigonex-Termine-Produkt nutzen: im Agent
unter „Aigonex Termine" aktivieren und den event_path eintragen.
Der Agent kann dann ohne weitere Tool-Konfiguration freie Slots
abfragen und Termine buchen.
9. Test-Anruf¶
Bevor Sie die Produktivnummer umstellen, testen Sie mit einer Test-Nummer:
- Im Dashboard → „Anrufe (Live-Monitor)" öffnen, damit Sie den Anruf in Echtzeit sehen
- Vom Mobiltelefon die Test-DID anrufen
- Erwartetes Verhalten:
- Verbindung kommt zustande (kein Freizeichen-Endlosschleifen)
- Agent meldet sich mit dem konfigurierten Greeting
- Dialog läuft natürlich, Tools werden aufgerufen
- Bei
end_calllegt der Agent freundlich auf - Im Anrufprotokoll sollten Sie nach Ende des Anrufs sehen:
- Anrufzeitpunkt, Dauer, Status
completed - Vollständiges Transkript
- Im API-Log: alle ausgehenden Tool-Aufrufe inkl. Request- und Response-Body (Zeile zum Aufklappen anklicken)
Wenn etwas nicht funktioniert: Abschnitt 11 (Häufige Probleme).
10. Prompt-Optimierung¶
Der System-Prompt entscheidet maßgeblich, wie der Agent klingt. Tipps aus der Praxis:
10.1 Aussprache erzwingen¶
Die TTS liest Texte wörtlich. Wenn ein Akronym anders ausgesprochen werden soll, schreiben Sie es phonetisch:
| Falsch (TTS liest als Wort) | Richtig (phonetisch) |
|---|---|
IT |
Eiti |
PC |
Pehzeh |
CEO |
Sieh-Ie-Ou |
GmbH |
Geh-Em-Beh-Ha |
Wichtig: die phonetische Variante muss im literalen Text des Prompts stehen — eine bloße Regel „Schreibe IT als Eiti" wird vom LLM nur unregelmäßig befolgt.
10.2 Latenz reduzieren¶
Lange Pausen zwischen Agent-Antworten haben in der Regel zwei Ursachen:
- Unnötige Tool-Aufrufe: Wenn der Agent vor jeder Weiterleitung die Geschäftszeiten neu abruft, dauert das. Laden Sie die Wissensbasis einmal am Gesprächsanfang und nutzen Sie das Ergebnis im Gespräch.
- Bestätigungs-Floskeln vor Tool-Calls: „Einen Moment, ich prüfe das" doppelt die Wartezeit. Im Prompt explizit verbieten: „Keine Bestätigungs-Floskeln vor Tool-Calls. Tool sofort aufrufen."
10.3 Ein-Ticket-Regel¶
Wenn der Anrufer mehrere Anliegen nennt, kann der LLM dazu neigen, für jedes ein separates Ticket anzulegen. Lösung im Prompt:
- ticket_erstellen NUR EINMAL pro Anruf aufrufen. Sobald das Tool
ein erfolgreiches Ergebnis liefert, ist das Anliegen erfasst.
- Wenn der Anrufer mehrere Anliegen hat, frage explizit: "Soll ich
beides als separate Tickets anlegen, oder zusammen?" und warte auf
eine eindeutige Antwort.
10.4 Antwort-Länge begrenzen¶
Lange Agent-Antworten klingen unnatürlich am Telefon. Im Prompt:
- Maximal ein Satz pro Antwort, ausser bei Zusammenfassungen.
- Keine Wiederholung der Anrufer-Aussage.
11. Häufige Probleme & Lösungen¶
„Ich rufe an, aber höre nur ein endloses Freizeichen"¶
Ursache 1 — Telefonnummern-Mismatch: Die Nummer, die Ihre PBX im SIP-INVITE als To-Header sendet, stimmt nicht mit dem Feld „Telefonnummern" im Aigonex-Trunk überein.
Lösung: Im 3CX-Aktivitätsprotokoll die To-Zeile suchen
(To: <sip:+4963229564895@rtc.aigonex.de:5060>), die Nummer dahinter
muss exakt im Dashboard-Trunk-Feld stehen.
Ursache 2 — IP nicht in der Whitelist: Die öffentliche IP Ihrer PBX ist nicht im Feld „Erlaubte IPs" eingetragen.
Lösung: IP nachtragen (x.x.x.x/32), Trunk speichern.
„Der Agent nimmt ab, aber sagt nichts"¶
Ursache: Greeting-Modus steht auf user_first, aber der Anrufer
spricht nicht von selbst.
Lösung: Im Agent-Modal → Tab „Ansagen" → „Wer beginnt das
Gespräch?" auf Agent spricht zuerst umstellen.
„Der Agent versteht meine Aussprache schlecht"¶
- STT-Sprache richtig gewählt?
Deutsch (Deutschland)für DE,Deutsch (Österreich)für AT, etc. - Wenn der Anrufer Englisch spricht: Mehrsprachiger Anruf aktivieren und Englisch als zusätzliche Sprache eintragen.
„Der Agent ruft das Tool nicht auf"¶
- Ist das Tool dem Agent zugewiesen? (Agent → Tab „Tools für diesen Agent" → Karte muss angehakt sein)
- Ist die Beschreibung des Tools aussagekräftig? Der LLM entscheidet anhand der Beschreibung, wann er das Tool aufruft. „Sendet Daten an X" ist zu vage — schreiben Sie wann das Tool genutzt werden soll: „Lege ein Ticket im CRM an, wenn der Anrufer ein Problem schildert".
- Steht das Tool auf
Aktiv?
„Akronyme werden falsch ausgesprochen"¶
Siehe Abschnitt 10.1 — phonetische Schreibweise direkt im Prompt-Text.
„Anrufprotokoll zeigt drei Tickets für einen Anruf"¶
Siehe Abschnitt 10.3 — Ein-Ticket-Regel in den Prompt aufnehmen.
„Die Pausen zwischen den Agent-Antworten sind zu lang"¶
Siehe Abschnitt 10.2 — unnötige Tool-Aufrufe vermeiden, keine Bestätigungs-Floskeln vor Tools.
12. Nächste Schritte¶
Nach dem ersten erfolgreichen Anruf:
- [ ] Mehrere Test-Szenarien durchspielen (technische Anfrage, Buchhaltungs-Anfrage, Sales-Anfrage, schwieriger Anrufer)
- [ ] Prompt iterativ anpassen — kleine Änderungen, je ein Test-Anruf, Transkript prüfen
- [ ] Tickets/CRM-Anbindung vollständig durchziehen — n8n-Workflow anlegen, Webhook-Tool im Dashboard, im Prompt referenzieren
- [ ] MFA für alle Admin-Konten aktivieren
- [ ] Datenexport-Test durchführen (Konto-Menü → Daten → Export) damit Sie wissen, wie Sie im Ernstfall Ihre Daten holen
- [ ] AVV-Vertrag mit Aigonex unterschreiben, falls noch nicht geschehen — Pflicht vor produktivem Einsatz
Bei Fragen oder Problemen: hallo@aigonex.de
Anhang: Glossar siehe Leistungsbeschreibung (leistungsbeschreibung.md), Abschnitt 10.