Utwórz głosowego agenta Gemini Realtime

Wprowadzenie

Przykładowy skrypt geminivoiceagent.cs łączy przychodzące połączenie 3CX z sesją głosową Google Gemini Live. Agent może witać dzwoniących, korzystać z dozwolonych obiektów książki telefonicznej, kierować połączenia, oferować pocztę głosową lub czat, a po odpowiedniej konfiguracji – zapisywać przydatny kontekst rozmówcy.

Skrypt zawiera również wyłączone domyślnie niestandardowe narzędzie get_department_hours, które pokazuje, jak zarejestrować bezpieczną funkcję możliwą do wywołania przez sztuczną inteligencję.

Skrypt wymaga licencji 3CX AI, centrali PBX w wersji Update 10 oraz konta API Gemini.

Tworzenie skryptu połączenia w systemie 3CX

• Zaloguj się do Konsoli Administracyjnej 3CX.
• Przejdź do „Admin” > „Integrations” (Integracje) > „Call Scripts” (Skrypty połączeń).
• Wybierz „+Add from Store” (Dodaj ze sklepu).

• Wybierz plik geminivoiceagent.cs.

• Wprowadź nazwę skryptu pisaną małymi literami bez spacji, na przykład geminireception.
• Wybierz sposób uruchamiania skryptu i przypisz wymagany numer DID, trasę łącza TRUNK lub wewnętrzny punkt docelowy.
• Wybierz dział (Department), do którego należy skrypt.
• Przejdź do edytora kodu.

Konfiguracja Gemini oraz skryptu

Dodaj następujące chronione parametry w centrali PBX:

• GEMINI_API_KEY - klucz API dla Twojego projektu Google AI.
• GEMINI_REALTIME_MODEL - model Gemini Realtime.

Pozostaw pola ApiKeyOverride oraz ModelOverride w skrypcie puste. Gdy te wartości są puste, skrypt automatycznie odczytuje klucz API i model z parametrów centrali PBX.

Nie wprowadzaj klucza Gemini API bezpośrednio w skrypcie, zwłaszcza jeśli skrypt będzie udostępniany, eksportowany lub publikowany. Wartość skonfigurowana w ApiKeyOverride lub ModelOverride ma priorytet nad odpowiadającym jej parametrem PBX.

Następnie przejrzyj poniższe ustawienia znajdujące się w górnej części skryptu:

Ustaw AllowAllVisibilityForTesting na false przed wdrożeniem produkcyjnym i skonfiguruj możliwie najmniejszą praktyczną listę widoczności.

Aby włączyć opcjonalny przykład funkcji (custom tool), przejrzyj jego dane i odkomentuj w kodzie:

RegisterExampleCustomTool();



Kliknij Save (Zapisz) i zweryfikuj pomyślną kompilację skryptu.

Jak to działa

1. Połączenie przychodzące dociera do punktu trasowania skryptu.
2. Skrypt czyści i odbudowuje dozwoloną listę widoczności obiektów 3CX dla Gemini.
3. System 3CX przygotowuje kanał mediów.
4. Skrypt uruchamia sesję głosową Gemini Live ze skonfigurowanymi instrukcjami, głosem, nazwą agenta, kluczem API oraz modelem.
5. Zatwierdzone narzędzia wykonują akcje związane z książką telefoniczną, transferem, pocztą głosową, czatem oraz kontekstem.
6. Awarie są kierowane do skonfigurowanej trasy zapasowej (Fallback), a następnie używają komunikatu ERROR, jeśli trasowanie jest niedostępne.

Testowanie skryptu

• Zweryfikuj wybrany głos Gemini oraz zachowanie dotyczące języka rozmówcy.
• Wyszukaj dozwolone obiekty w książce telefonicznej.
• Potwierdź, że ukryte punkty docelowe nie mogą być wybrane.
• Przetestuj potwierdzenie transferu, pocztę głosową oraz czat.
• Przetestuj naturalne zakończenie rozmowy i pożegnanie.
• Zasymuluj awarię dostawcy i potwierdź działanie trasowania zapasowego (Fallback).

Rozwiązywanie problemów

• Sesja Gemini nie powodzi się: Potwierdź klucz Gemini API, obsługiwany model realtime, licencję, wersję kompilacji PBX oraz łączność wychodzącą.
• Głos został odrzucony: Użyj głosu obsługiwanego przez skonfigurowany model Gemini.
• Brak wyników z książki telefonicznej: Sprawdź widoczność numerów, działów i ról.
• Udostępniono zbyt wiele obiektów: Wyłącz AddAll().
• Trasa zapasowa (Fallback) lub komunikat nie działa: Sprawdź punkt docelowy oraz aktywny komunikat ERROR.

Zobacz również

• Tworzenie skryptu przetwarzania połączeń
• Przykładowy skrypt przetwarzania połączeń dla kodu PIN
• Podręcznik administratora 3CX

Ostatnia aktualizacja
Ten dokument został ostatnio zaktualizowany 9 września 2026 r..
https://www.3cx.pl/docs/gemini-voice-agent/