Anrufskript: Erstellen eines Gemini-Echtzeit-Sprachagenten

Einführung

Das Beispielskript geminivoiceagent.cs verbindet einen eingehenden 3CX-Anruf mit einer Google Gemini Live-Sprachsitzung. Der Agent kann Anrufer begrüßen, zulässige Verzeichnisobjekte verwenden, Anrufe weiterleiten, Mailbox oder Chat anbieten und, sofern konfiguriert, nützliche Anruferkontexte speichern.

Das Skript enthält außerdem ein deaktiviertes benutzerdefiniertes Tool namens get_department_hours, das die Registrierung einer sicheren, KI-aufrufbaren Funktion demonstriert.

Für dieses Skript benötigen Sie eine 3CX AI Edition-Lizenz, eine PBX-Version Update 10 und ein Gemini API-Konto.

Erstellen des Anrufskripts in 3CX

  • Melden Sie sich in der 3CX-Administrationskonsole an.
  • Gehen Sie zu Integrationen > Anrufskripte.
  • Wählen Sie „+Aus Store hinzufügen“.

+Aus Store hinzufügen

  • Wählen Sie geminivoiceagent.cs.

Skript hinzufügen

  • Geben Sie einen Skriptnamen in Kleinbuchstaben ohne Leerzeichen ein, z. B. geminireception.
  • Wählen Sie aus, wie das Skript ausgeführt werden soll, und weisen Sie die gewünschte DID, Trunk-Route oder das interne Ziel zu.
  • Wählen Sie die Abteilung aus, der das Skript gehört.
  • Bestätigen Sie Ihre Auswahl, um den Code-Editor zu öffnen.

Gemini und das Skript konfigurieren

Fügen Sie der Telefonanlage die folgenden Parameter hinzu:

  • GEMINI_API_KEY - der API-Schlüssel für Ihr Google AI-Projekt.
  • GEMINI_REALTIME_MODEL - das Gemini Realtime-Modell.

Lassen Sie ApiKeyOverride und ModelOverride im Skript leer. Wenn diese Werte leer sind, liest das Skript den API-Schlüssel und das Modell automatisch aus den PBX-Parametern.

Geben Sie den Gemini-API-Schlüssel nicht direkt im Skript ein, insbesondere wenn das Skript geteilt, exportiert oder veröffentlicht werden soll. Ein in ApiKeyOverride oder ModelOverride konfigurierter Wert hat Vorrang vor dem entsprechenden PBX-Parameter.

Überprüfen Sie als Nächstes diese Kundeneinstellungen im oberen Bereich des Skripts:

Einstellung

Zweck

Beispielwert

FallbackDestination

Route, die verwendet wird, wenn die Medien- oder die KI-Sitzung fehlschlägt

102

VoiceName

Gemini Live Stimme

Capella

AgentName

Name der Agentensitzung

Capella

AllowAllVisibilityForTesting

Stellt alle unterstützten Verzeichnisobjekte bereit

true

VisibleNumbers

Explizite Ziele, die die KI verwenden kann

100, 102

VisibleDepartments

Genehmigte Abteilungen

Sales, Support

VisibleRoles

Optional zulässige Rollen

empty

AgentInstructions

Unternehmensidentität, Verhalten und Routingregeln

Example Company

Setzen Sie AllowAllVisibilityForTesting vor der Produktion auf false und konfigurieren Sie die kleinstmögliche Sichtbarkeitsliste.

Agentenkonsole

Um die optionale Beispielfunktion zu aktivieren, überprüfen Sie deren Daten und entfernen Sie die Kommentarzeichen:

RegisterExampleCustomTool();

Wählen Sie „Speichern“ und überprüfen Sie, ob die Kompilierung erfolgreich war.

So funktioniert es

  • Ein eingehender Anruf erreicht den Skript-Routingpunkt.
  • Das Skript löscht und aktualisiert die zulässige 3CX-Verzeichnissichtbarkeit von Gemini.
  • 3CX bereitet den Medienkanal vor.
  • Das Skript startet die Gemini Live-Sprachsitzung mit den konfigurierten Anweisungen, der Stimme, dem Agentennamen, dem API-Schlüssel und dem Modell.
  • Zugelassene Tools führen Verzeichnis-, Weiterleitungs-, Voicemail-, Chat- und Kontextaktionen durch. Bei Fehlern wird der konfigurierte Fallback verwendet.
  • Ist die Weiterleitung nicht möglich, wird die Fehlermeldung angezeigt.

Testen Sie das Skript

  • Überprüfen Sie das ausgewählte Gemini-Sprach- und Anrufersprachenverhalten.
  • Suchen Sie nach zulässigen Verzeichniseinträgen.
  • Stellen Sie sicher, dass versteckte Ziele nicht ausgewählt werden können.
  • Testen Sie die Weiterleitungsbestätigung, Voicemail und Chat.
  • Testen Sie eine natürliche Verabschiedung.
  • Simulieren Sie einen Providerausfall und bestätigen Sie die alternative Weiterleitung.

Fehlerbehebung

  • Gemini-Sitzung fehlgeschlagen: Überprüfen Sie den Gemini-API-Schlüssel, das unterstützte Live-Modell, die Lizenz, die PBX-Konfiguration und die ausgehende Konnektivität.
  • Eine Stimme wurde abgelehnt: Verwenden Sie eine vom konfigurierten Gemini-Modell unterstützte Stimme.
  • Verzeichnisergebnisse fehlen: Überprüfen Sie die Sichtbarkeit von Nummer, Abteilung und Rolle.
  • Zu viele Objekte werden angezeigt: Deaktivieren Sie AddAll().
  • Fallback oder Prompt fehlgeschlagen: Überprüfen Sie das Ziel und die aktive Fehlermeldung.

Siehe auch

Letztes Update

Dieser Leitfaden wurde zuletzt am 31. Juli 2026 aktualisiert.

https://www.3cx.de/docs/gemini-voice-agent/