Membangun Agen Telepon Masuk

Membangun Agen Telepon Masuk

Implementasi referensi untuk membangun agen suara telepon masuk yang aman menggunakan API Voice Agent dan penyedia layanan telepon. Menggunakan Flux untuk speech-to-text dengan pengaturan giliran bicara asli yang dioptimalkan untuk percakapan agen suara real-time. Termasuk perlindungan endpoint webhook dan validasi tanda tangan permintaan bawaan.

Penelepon menghubungi nomor telepon dan berbicara dengan resepsionis AI yang dapat memeriksa ketersediaan janji, membuat janji, mencari janji yang sudah ada, dan membatalkan janji, semuanya melalui percakapan suara alami. Meskipun contoh ini khusus untuk klinik gigi, ini adalah titik awal yang baik untuk kasus penggunaan telepon masuk lainnya – cukup edit perintah dan panggilan fungsi sesuai kebutuhan.

Arsitektur

Aliran Audio

1. Penelepon berbicara ke telepon mereka
2. Penyedia layanan telepon menangkap audio dan mengalirkannya sebagai mulaw yang di-encode base64 melalui WebSocket
3. Server aplikasi mendekode base64 dan mengirim byte mulaw mentah ke API Voice Agent
4. Platform menangani seluruh pipeline: speech-to-text, penalaran LLM, text-to-speech
5. Platform mengirim kembali byte audio mulaw mentah
6. Server aplikasi mengenkode ke base64 dan mengirim sebagai JSON ke penyedia layanan telepon
7. Penyedia layanan telepon memutar audio ke penelepon

Konsep Teknis Utama

Jembatan WebSocket Tunggal

Inti dari sistem adalah VoiceAgentSession, yang menjembatani dua koneksi WebSocket (satu ke penyedia layanan telepon, satu ke platform). Ini menerjemahkan antara protokol berbasis JSON dari penyedia layanan telepon dan protokol audio biner platform.

Interupsi

Ketika agen suara mendeteksi bahwa pengguna mulai berbicara, server mengirim acara "clear" ke penyedia layanan telepon untuk segera menghentikan pemutaran audio agen. Ini mencegah agen berbicara di atas penelepon.

Panggilan Fungsi

API Voice Agent mendukung penggunaan alat. Ketika LLM memutuskan untuk memanggil fungsi (seperti memeriksa ketersediaan janji), platform mengirim acara panggilan fungsi. Server mengeksekusinya terhadap layanan backend dan mengirim hasilnya kembali ke platform, yang menggabungkannya ke dalam respons agen berikutnya.

Server Agnostik Protokol

Server tidak tahu apakah audio berasal dari panggilan nyata atau dari klien pengembangan lokal. Keduanya mengirim pesan WebSocket yang identik. Ini berarti Anda dapat mengembangkan dan menguji tanpa telepon atau akun penyedia layanan telepon.

Untuk tampilan lebih dalam tentang alur panggilan, siklus sesi, dan detail komponen, lihat dokumentasi arsitektur.

Mulai Cepat

Jalur tercepat menuju agen suara telepon yang berfungsi adalah wizard pengaturan, yang mengonfigurasi penyedia layanan telepon dan menyebarkan ke platform cloud.

Prasyarat

• Python 3.12+
• Akun platform dan kunci API (kredit gratis $200, tidak perlu kartu kredit)
• Akun penyedia layanan telepon (akun baru disertai kredit uji coba)
• Akun platform cloud dan alat baris perintah terinstal serta diautentikasi. Tunjangan gratis platform cloud lebih dari cukup untuk implementasi referensi ini dengan konfigurasi default penangguhan saat idle.

Catatan: Akun uji coba penyedia layanan telepon memutar penafian singkat sebelum menghubungkan penelepon.

1. Kloning dan Instal

$git clone github$cd voice-agent-inbound-telephony$python -m venv venv$source venv/bin/activate$pip install -r requirements

2. Konfigurasi

$cp .enve .env

Edit .env dan tambahkan kunci API platform Anda.

3. Jalankan Wizard Pengaturan

$python setup

Wizard akan:

1. Meminta kredensial akun penyedia layanan telepon Anda
2. Membiarkan Anda memilih nomor telepon yang sudah ada atau membeli yang baru
3. Menyebarkan agen suara Anda ke platform cloud
4. Secara otomatis mengonfigurasi penyedia layanan telepon untuk merutekan panggilan ke agen suara yang telah disebarkan

Setelah selesai, hubungi nomor telepon Anda dan bicara dengan agen Anda.

$# Mode wizard pengaturan lainnya:$python setup --twilio-only # Lewati platform cloud, berikan URL Anda sendiri$python setup --update-url URL # Pembaruan URL webhook cepat$python setup --status # Tampilkan konfigurasi saat ini$python setup --teardown # Bersihkan penyebaran

Melihat Log

Setelah penyebaran, lihat log aplikasi Anda dengan:

$flyctl logs --app <nama-aplikasi-anda>

Nama aplikasi ditampilkan di output wizard pengaturan dan di python setup --status.

Cold Start

Konfigurasi default menggunakan mode penangguhan platform cloud. Server Anda ditangguhkan saat idle dan bangun dalam 1-3 detik pada permintaan masuk.

Jika Anda menginginkan waktu respons instan untuk demo atau penggunaan produksi, setel min_machines_running = 1 di fly dan sebarkan ulang untuk menjaga satu VM tetap aktif.

# flyn_machines_running = 1

Persyaratan Regulasi Penyedia Layanan Telepon

Tergantung pada wilayah Anda, penyedia layanan telepon mungkin memerlukan verifikasi alamat sebelum Anda dapat membeli nomor telepon. Wizard pengaturan akan menampilkan kesalahan apa pun dari penyedia layanan telepon. Ikuti instruksi di konsol penyedia layanan telepon jika diminta.

Alternatif: Tunnel + Penyedia Layanan Telepon

Jika Anda lebih suka menjalankan server secara lokal daripada menyebarkan ke platform cloud, Anda dapat menggunakan tunnel untuk mengekspos server agen suara yang berjalan secara lokal melalui URL publik.

1. Mulai Tunnel

$# ngrok$ngrok http 8080$# atau zrok$zrok share public localhost:8080

Salin URL publik (mis., ngrok).

2. Perbarui Konfigurasi

Tambahkan ke .env:

PUBLIC_URL=ngrok

3. Mulai Server

$python main

4. Konfigurasi Penyedia Layanan Telepon

Anda dapat menggunakan wizard pengaturan dengan --twilio-only untuk menangani konfigurasi penyedia layanan telepon:

$python setup --twilio-only

Atau konfigurasi secara manual:

1. Dapatkan nomor telepon di konsol penyedia layanan telepon
2. Di pengaturan nomor telepon, setel webhook untuk panggilan masuk ke: Metode: HTTP POST
3. Hubungi nomor penyedia layanan telepon Anda dari telepon mana pun

Log server akan menunjukkan panggilan terhubung di terminal Anda.

Pengembangan Lokal (Tidak Perlu Penyedia Layanan Telepon)

Anda dapat menguji percakapan agen suara penuh tanpa telepon atau akun penyedia layanan telepon menggunakan dev_client.py, yang terhubung ke server melalui WebSocket dan mengalirkan audio dari mikrofon Anda.

$pip install -r requirements-dev # Menambahkan sounddevice, numpy, websockets$# Terminal 1:$python main$# Terminal 2:$python dev_client.py

Bicaralah ke mikrofon Anda untuk melakukan percakapan dengan agen. Lihat dokumentasi pengembangan lokal untuk detail lebih lanjut dan pemecahan masalah.

Catatan: dev_client.py hanya untuk pengembangan lokal. Jika Anda telah menyebarkan ke platform cloud, hubungi nomor telepon secara langsung.

Kustomisasi

Ubah Kepribadian Agen

Edit SYSTEM_PROMPT di voice_agent/agent_config.py. Di sinilah Anda mendefinisikan siapa agen itu, apa yang diketahuinya, dan bagaimana perilakunya. Lihat panduan perintah untuk praktik terbaik perintah khusus suara.

Tambah atau Modifikasi Fungsi

1. Definisikan fungsi di voice_agent/agent_config.py (dalam daftar FUNCTIONS)
2. Tambahkan handler di voice_agent/function_handlers.py
3. Implementasikan logika backend di backend/scheduling_service.py

Lihat panduan fungsi untuk praktik terbaik definisi fungsi.

Ganti LLM atau Suara

Setel variabel lingkungan di .env:

LLM_MODEL=gpt-4oVOICE=aura-hera-en

Dukungan Multibahasa

Implementasi referensi ini dikonfigurasi untuk bahasa Inggris menggunakan Flux (flux-general-en) untuk STT, yang menyediakan pengaturan giliran bicara asli yang dioptimalkan untuk agen suara. Untuk menambahkan dukungan multibahasa, ganti model STT ke flux-general-multi dan terapkan nilai language_hint untuk membiasakan ke bahasa yang diharapkan. Untuk membangun agen suara dalam bahasa lain, lihat panduan agen suara multibahasa.

Ganti Backend Mock

Direktori backend/ berisi mock dalam memori. Untuk terhubung ke sistem penjadwalan nyata:

1. Pertahankan tanda tangan metode yang sama di scheduling_service.py
2. Ganti isi metode dengan panggilan HTTP ke API nyata Anda
3. Lapisan agen suara tidak perlu diubah

Pengiriman fungsi di voice_agent/function_handlers.py menggunakan impor malas, membuat batas antara agen suara dan backend menjadi eksplisit.

Sumber Daya Tambahan

• Dokumentasi arsitektur - Arsitektur terperinci, diagram aliran data, dan detail komponen
• Panduan perintah - Praktik terbaik untuk menulis perintah agen suara
• Panduan fungsi - Praktik terbaik untuk mendefinisikan fungsi agen
• Panduan pengembangan lokal - Pengaturan pengembangan lokal langkah demi langkah
• Dokumentasi API Voice Agent - Dokumentasi API resmi