API Grok Voice Agent: Cara Membangun Asisten Suara Real-Time

Agen Voice AI sedang naik daun. Pengguna ingin berbicara dengan aplikasi alih-alih mengetik, dan teknologinya kini sudah cukup matang untuk membuat percakapan terasa natural.

Jika Anda ingin membangunnya, API Grok Voice Agent dari xAI adalah tempat yang solid untuk memulai. API ini menawarkan waktu respons di bawah satu detik dan biaya lebih rendah dibandingkan sebagian besar alternatif, ditambah kompatibilitas drop-in dengan kode OpenAI yang sudah ada.

Tutorial ini menunjukkan cara membangun agen suara yang berfungsi dari nol. Anda akan mengatur autentikasi, mengonfigurasi kepribadian dan opsi suara, menambahkan pemanggilan tool, dan melakukan deployment ke produksi dengan LiveKit Cloud. API ini berjalan di atas Grok 3, yang diadaptasi xAI untuk percakapan suara real-time alih-alih alur kerja teks masuk, teks keluar yang biasa.

Apa Itu API Grok Voice Agent?

Grok Voice Agent API adalah platform percakapan suara real-time dari xAI, dirilis pada Desember 2025. API ini memproses audio secara langsung tanpa konversi biasa antara ucapan ke teks dan kembali lagi, sehingga memangkas waktu respons sekaligus membuat percakapan terdengar natural.

Sistem voice AI tradisional merangkai tiga langkah terpisah: transkripsi ucapan menjadi teks, menjalankan teks itu melalui model bahasa, lalu menyintesis respons kembali menjadi audio. Pendekatan ini bekerja, namun setiap perpindahan antar komponen menambah jeda. Setelah Anda memperhitungkan transkripsi, pemrosesan, dan sintesis, Anda akan melihat 500ms hingga 1.000ms sebelum pengguna mendapat respons. Jeda-jeda tersebut menumpuk dan membuat percakapan terasa mekanis.

Grok Voice Agent melewati konversi tersebut sepenuhnya. Sistem menerima audio, melakukan penalaran dalam domain audio, dan mengeluarkan audio menggunakan satu model yang dilatih pada ucapan percakapan. Arsitektur ini menghadirkan time-to-first-audio rata-rata 0,78 detik sambil mendukung komunikasi full-duplex (audio dua arah simultan di mana agen dapat mendengarkan dan berbicara pada saat yang sama), sehingga agen dapat merespons tanpa menunggu giliran bicara yang ketat.

Menyiapkan Lingkungan Grok Voice Agent Anda

Membangun agen suara dengan Grok memerlukan penggabungan dengan LiveKit, platform WebRTC open-source. Grok menyediakan model AI percakapan, sementara LiveKit mengelola infrastruktur audio real-time yang menghubungkan pengguna ke agen Anda. Bagian ini membahas penyiapan kedua layanan.

Menyiapkan Grok

Kunjungi console.x.ai dan buat akun menggunakan autentikasi X, email, Google, atau Apple. Konsol xAI memerlukan kredit prabayar sebelum Anda dapat melakukan panggilan API. Beli kredit melalui bagian Billing.

Setelah ada kredit di akun Anda, buka API Keys dan buat kunci baru. Konsol hanya menampilkan kunci sekali, jadi salin segera dan simpan dengan aman. Jika hilang, Anda perlu membuat pengganti dan memperbarui aplikasi Anda. Untuk panduan lebih dalam tentang ekosistem API xAI, lihat tutorial Grok 3 API.

Menyiapkan LiveKit

LiveKit adalah infrastruktur WebRTC untuk audio dan video real-time. LiveKit menangani lapisan transport audio yang dibutuhkan Grok untuk terhubung dengan pengguna. Saat membangun agen suara, LiveKit mengelola ruang (room) tempat percakapan terjadi, merutekan aliran audio antar peserta, dan menyediakan infrastruktur deployment. Framework LiveKit Agents membungkus kompleksitas ini, memungkinkan Anda fokus pada perilaku agen sementara framework menangani manajemen koneksi, pengodean audio, dan deteksi giliran bicara.

Framework ini mendukung beberapa penyedia AI, termasuk xAI. Framework ini mencakup playground pengujian yang dapat diakses melalui antarmuka web, yang akan Anda gunakan untuk memvalidasi agen sebelum mendistribusikannya.

Daftar di cloud.livekit.io. Paket gratis menyediakan sumber daya yang cukup untuk pengembangan dan pengujian. Buat project melalui dashboard. Arahkan ke Settings, lalu API Keys. Salin tiga kredensial: LIVEKIT_URL (endpoint WebSocket project Anda), LIVEKIT_API_KEY (identifier publik), dan LIVEKIT_API_SECRET (kunci autentikasi privat). Kredensial ini mengautentikasi kode agen Anda dengan project LiveKit Cloud Anda.

Menginstal Dependensi dan Konfigurasi

Instal paket yang diperlukan:

uv add "livekit-agents[xai,openai]>=1.3.10" python-dotenv

Ini menginstal framework LiveKit agents dengan plugin xAI dan dependensi OpenAI (plugin xAI dibangun di atas kompatibilitas Realtime API OpenAI), plus python-dotenv untuk manajemen variabel lingkungan.

Buat file .env di root project Anda:

XAI_API_KEY=xai-YourActualKeyHere
 LIVEKIT_URL=wss://your-project.livekit.cloud
 LIVEKIT_API_KEY=APIYourKeyHere
 LIVEKIT_API_SECRET=YourSecretHere

Ganti nilai placeholder dengan kredensial Anda yang sebenarnya. Muat kredensial ini di kode Python Anda:

from dotenv import load_dotenv
 load_dotenv()

Ini membuat kredensial tersedia untuk pustaka xAI dan LiveKit. Tambahkan .env ke .gitignore Anda untuk mencegah kebocoran kredensial dalam version control.

Membangun Grok Voice Agent Pertama Anda

Dengan lingkungan yang sudah dikonfigurasi, Anda dapat membangun agen suara yang berfungsi. Mulailah dengan import dan kelas agen di file baru bernama agent.py:

from livekit.agents import Agent, AgentSession, AgentServer, JobContext, cli
from livekit.plugins.xai import realtime
from dotenv import load_dotenv

load_dotenv()

class ResearchAssistant(Agent):
	def __init__(self):
    	super().__init__(
        	instructions="You are a research assistant who helps users find information.",
 	)

Subclass Agent Anda hanya memuat instruksi yang membentuk cara agen merespons. Ini bekerja seperti system prompt, memberi tahu agen peran apa yang harus dimainkan. Konfigurasi model yang sebenarnya diletakkan di tempat lain.

Selanjutnya, atur server dan handler koneksi:

server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
	await ctx.connect()

 	session = AgentSession(
         llm=realtime.RealtimeModel(voice="ara"),
 	)

 	await session.start(
     	room=ctx.room,
     	agent=ResearchAssistant(),
 	)

Decorator @server.rtc_session() memberi tahu LiveKit untuk menjalankan fungsi entrypoint Anda setiap kali seseorang terhubung. Di dalamnya, AgentSession menerima konfigurasi model, termasuk suara mana dari tujuh suara Grok yang akan digunakan (Ara, Eve, Leo, Sal, Rex, Mika, atau Valentin). Saat session.start() berjalan, fungsi ini menghubungkan agen Anda ke room LiveKit tempat percakapan berlangsung.

Percakapan suara melibatkan menunggu input dan output audio tanpa membekukan program, jadi fungsi menggunakan async def dan await untuk menangani operasi ini secara konkuren.

Terakhir, tambahkan entry point:

if __name__ == "__main__":
 	cli.run_app(server)

Jalankan agen Anda dalam mode pengembangan:

uv run agent.py dev

Terminal akan menampilkan urutan startup: inisialisasi worker, server HTTP mendengarkan pada port lokal, dan pendaftaran dengan project LiveKit Cloud Anda.

Untuk menguji agen, buka dashboard LiveKit Cloud Anda di cloud.livekit.io. Pilih project Anda, lalu klik tab Sandbox di sidebar. Pilih Web Voice Agent dari template yang tersedia.

Halaman template menampilkan pratinjau antarmuka suara beserta detail tentang komponennya. Klik tombol Create sandbox.

Di modal yang muncul, Anda dapat mengonfigurasi URL khusus, mengaktifkan kapabilitas seperti kamera dan berbagi layar, serta menyesuaikan tampilan. Pengaturan default sudah memadai untuk pengujian, jadi klik Create, lalu Done.

Kembali ke halaman Sandbox, sandbox baru Anda muncul di bawah Sandbox apps. Klik Launch untuk membukanya.

Klik Start Call dan berikan izin mikrofon saat diminta. Perhatikan terminal untuk pesan log ini, yang menunjukkan agen siap menerima audio:

DEBUG livekit.agents start reading stream {"participant": "...", "source": "SOURCE_MICROPHONE", ...}

Setelah pesan ini muncul, respons akan datang dengan cepat.

Saat Anda menanyakan sesuatu yang tidak dapat diakses agen (seperti cuaca saat ini di kota tertentu), agen akan menjelaskan keterbatasannya alih-alih mengarang.

Cara Menambahkan Tools ke Grok Voice Agent Anda

Agen dasar dapat bercakap-cakap tetapi tidak memiliki cara untuk mencari informasi. Pemanggilan tool memungkinkan Grok menjalankan fungsi di tengah percakapan dan membicarakan hasilnya. Anda dapat menggunakan tool bawaan xAI atau mendefinisikan tool Anda sendiri.

Menggunakan tool bawaan

Plugin xAI menyertakan WebSearch untuk kueri web umum dan XSearch untuk mencari posting di X. Impor keduanya dan teruskan ke AgentSession:

from livekit.agents import Agent, AgentSession, AgentServer, JobContext, cli
from livekit.plugins.xai import realtime
from livekit.plugins.xai.realtime import WebSearch, XSearch
from dotenv import load_dotenv

load_dotenv()


class ResearchAssistant(Agent):
 	def __init__(self):
     	super().__init__(
             instructions="""You are a research assistant with access to web search and X search.

- Use web search for general queries and current information
- Use X search when users ask about posts or what people are saying on X/Twitter

Always mention your sources when providing information.""",
     	)


server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
	await ctx.connect()

	session = AgentSession(
         llm=realtime.RealtimeModel(voice="ara"),
     	tools=[
         	WebSearch(),
         	XSearch(),
     	],
 	)

 	await session.start(
     	room=ctx.room,
     	agent=ResearchAssistant(),
 	)


if __name__ == "__main__":
 	cli.run_app(server)

Parameter tools menerima daftar objek tool. Jalankan agen dan uji dengan pertanyaan seperti "Apa berita terbaru tentang AI?" atau "Apa yang orang-orang katakan tentang Grok di X?" Log terminal mungkin menampilkan peringatan tentang fungsi AI yang tidak dikenal seperti web_search_with_snippets atau x_semantic_search, namun tool tetap mengembalikan informasi terkini.

Audio full-duplex Grok juga terasa jelas saat menggunakan tool. Anda dapat menyela agen saat ia berbicara, dan agen akan berhenti, mendengarkan, serta menyesuaikan responsnya. Ini membuat percakapan terasa kurang robotik dibandingkan sistem yang mengharuskan menunggu agen selesai sebelum Anda bisa berbicara.

Menambahkan tool kustom

Tool bawaan mencakup use case umum, tetapi mendefinisikan tool Anda sendiri memberi Anda kendali atas parameter, penanganan error, dan API mana yang akan dipanggil. Bagian ini mendemonstrasikan pembuatan tool kustom menggunakan endpoint pencarian Firecrawl, yang menawarkan opsi pemfilteran seperti limit, lang, dan country yang tidak diekspos oleh web search bawaan.

Daftar di firecrawl.dev. Paket gratis mencakup 500 kredit dan tidak memerlukan kartu kredit. Instal SDK dan tambahkan kunci Anda ke .env:

uv add firecrawl-py

FIRECRAWL_API_KEY=fc-your-key-here

Tool kustom adalah method yang didekorasi dengan @function_tool(). Perbarui import di search_agent.py:

from livekit.agents import (
 	Agent,
 	AgentSession,
 	AgentServer,
 	JobContext,
 	cli,
 	function_tool,
 	RunContext,
 )

from livekit.plugins.xai import realtime
from livekit.plugins.xai.realtime import XSearch
from firecrawl import FirecrawlApp
from dotenv import load_dotenv

import os 
load_dotenv()

Tambahan yang digunakan adalah function_tool untuk decorator, RunContext yang diteruskan ke fungsi tool, dan FirecrawlApp untuk klien Firecrawl. WebSearch dihapus karena tool kustom menggantikannya.

Definisikan tool sebagai method pada kelas agen Anda:

class ResearchAssistant(Agent):
 	def __init__(self):
     	super().__init__(
             instructions="""You are a research assistant with access to web search and X search.

 - Use Firecrawl search for general queries and current information
 - Use X search when users ask about posts or what people are saying on X/Twitter

 Always mention your sources when providing information.""",
     	)
     	self.firecrawl = FirecrawlApp(api_key=os.getenv("FIRECRAWL_API_KEY"))

 	@function_tool()
     async def search_web(
     	self,
     	context: RunContext,
     	query: str,
 	) -> dict:
     	"""Search the web for current information using Firecrawl.

     	Args:
         	query: The search query
     	"""
     	result = self.firecrawl.search(query, limit=3)
     	return {
         	"results": [
             	{
                 	"title": item.title,
                 	"url": item.url,
                     "description": item.description,
             	}
             	for item in result.web
         	]
     	}

Grok membaca docstring untuk memahami fungsi tool. Saat Anda bertanya "Berapa kurs USD ke EURO saat ini?", Grok mengekstrak kueri, memanggil fungsi Anda, dan memasukkan hasilnya ke dalam respons.

Method yang didekorasi dengan @function_tool() terdaftar secara otomatis, jadi hapus WebSearch() dari daftar tools:

session = AgentSession(
     llm=realtime.RealtimeModel(voice="ara"),
 	tools=[
     	XSearch(),
 	],
 )

Jalankan agen yang telah diperbarui:

uv run search_agent.py dev

Terminal akan menampilkan eksekusi tool:

DEBUG livekit.agents executing tool {
 	"function": "search_web",
 	"arguments": "{\"query\":\"current USD to EURO exchange rate\"}",
 	...
 }
DEBUG livekit.agents tools execution completed {...}

Dalam pengujian saya, Firecrawl mengembalikan hasil sekitar dua detik. Anda dapat menggabungkan beberapa tool kustom dengan tool bawaan dalam agen yang sama. Misalnya, agen dukungan pelanggan dapat menggunakan XSearch bersama tool kustom lookup_order() dan check_inventory() yang terhubung ke basis data internal.

Menyesuaikan Deteksi Giliran Bicara

Pengaturan deteksi giliran bicara default sudah menangani percakapan tipikal dengan baik. Penyesuaian diperlukan saat lingkungan atau perilaku pengguna berbeda dari biasanya. Ruangan bising dapat menyebabkan agen merespons suara latar, sementara pengguna yang berhenti sejenak untuk berpikir mungkin disela sebelum selesai.

from livekit.plugins.xai import realtime
from openai.types.beta.realtime.session import TurnDetection

session = AgentSession(
 	llm=realtime.RealtimeModel(
     	voice="ara",
     	turn_detection=TurnDetection(
         	type="server_vad",
         	threshold=0.5,
         	prefix_padding_ms=300,
         	silence_duration_ms=200,
     	),
 	),
 )

Parameter threshold menentukan seberapa keras audio agar dihitung sebagai ucapan, rentangnya dari 0,0 hingga 1,0. Menaikkan nilai ini ke 0,7 atau lebih tinggi membantu di lingkungan bising di mana suara latar dapat memicu respons.

Parameter prefix_padding_ms menentukan berapa banyak audio yang ditangkap sebelum awal ucapan terdeteksi. Default 300ms mencegah suku kata pertama terpotong. Tingkatkan jika pengguna melaporkan kata pembuka mereka terpotong.

Parameter silence_duration_ms mengontrol berapa lama agen menunggu setelah Anda berhenti berbicara sebelum merespons. Pada 200ms, percakapan terasa responsif. Menaikkannya ke 400 atau 500ms mengakomodasi pengguna yang berhenti di tengah kalimat atau berbicara lebih lambat.

Untuk antarmuka push-to-talk atau sistem teleponi di mana Anda memerlukan kontrol eksplisit atas alur percakapan, nonaktifkan deteksi giliran otomatis:

session = AgentSession(
 	llm=realtime.RealtimeModel(
     	voice="ara",
     	turn_detection=None,
 	),
 )

Agen kemudian menunggu sinyal programatik sebelum merespons alih-alih mendengarkan jeda.

Mendeploy Grok Voice Agent ke Produksi

Mode pengembangan mengikat agen ke mesin lokal Anda. Untuk deployment produksi yang berjalan 24/7 dan menskalakan sesuai permintaan, LiveKit Cloud menjadi host agen Anda di infrastrukturnya.

Menyiapkan untuk Deployment

LiveKit CLI mendeteksi tipe project Anda melalui file dependensi. Buat requirements.txt di direktori agen Anda:

livekit-agents[xai,openai]>=1.3.10
python-dotenv>=1.2.1
firecrawl-py>=4.12.0

Buat file terpisah untuk secret produksi. LiveKit Cloud secara otomatis menyediakan LIVEKIT_URL, LIVEKIT_API_KEY, dan LIVEKIT_API_SECRET, jadi Anda hanya perlu memasukkan kunci API lainnya:

XAI_API_KEY=xai-your-key-here
FIRECRAWL_API_KEY=fc-your-key-here

Simpan ini sebagai .env.production dan tambahkan ke .gitignore.

Mendeploy Agen

Autentikasi CLI dengan akun LiveKit Cloud Anda:

lk cloud auth

Ini akan membuka browser untuk menautkan CLI Anda ke project. Setelah diautentikasi, deploy agen:

lk agent create --secrets-file .env.production

CLI mendaftarkan agen Anda, menghasilkan Dockerfile, membangun image kontainer, dan mendeploy-nya ke LiveKit Cloud. Log mengalir ke terminal Anda saat agen mulai berjalan:

{"message": "registered worker", "level": "INFO", "name": "livekit.agents", "url": "https://your-project.livekit.cloud", "region": "Germany 2", ...}

Periksa status deployment:

lk agent status

┌─────────────────┬─────────────────┬────────────┬─────────┬────────┬─────────┬───────────┐
 │ ID          	│ Version     	│ Region 	│ Status  │ CPU	│ Mem 	│ Replicas  │
 ├─────────────────┼─────────────────┼────────────┼─────────┼────────┼─────────┼───────────┤
 │ CA_AAVy5WbUYpmA │ v20260109102531 │ eu-central │ Running │ 0m / 2 │ 0 / 4GB │ 0 / 1 / 1 │
 └─────────────────┴─────────────────┴────────────┴─────────┴────────┴─────────┴───────────┘

Cara Pengguna Mengakses Agen Anda

URL dalam log deployment (https://your-project.livekit.cloud) adalah backend WebSocket, bukan antarmuka pengguna. Pengguna berinteraksi dengan agen Anda melalui frontend yang terhubung ke backend ini.

Sandbox yang Anda buat sebelumnya berfungsi untuk tujuan ini. Buka dashboard LiveKit Anda, buka bagian Sandbox, dan salin URL sandbox Anda. URL ini dapat diakses publik dan berfungsi tanpa autentikasi. Bagikan kepada pengguna dan mereka dapat langsung berbicara dengan agen Anda.

Untuk pengalaman bermerek, sesuaikan tampilan sandbox di dashboard (logo, warna, teks tombol) atau bangun frontend Anda sendiri menggunakan SDK JavaScript LiveKit.

Mengelola Deployment

Lihat log real-time dari agen Anda yang ter-deploy:

lk agent logs

Deploy pembaruan setelah memodifikasi kode Anda:

lk agent deploy --secrets-file .env.production

LiveKit menggunakan rolling deployment. Instance baru menangani sesi baru sementara instance yang ada menyelesaikan percakapan aktifnya, sehingga pembaruan tidak menimbulkan downtime.

Kembalikan ke versi sebelumnya jika terjadi kerusakan:

lk agent rollback

Agen yang ter-deploy berjalan secara independen dari mesin lokal Anda. Tutup terminal, matikan komputer, dan agen tetap merespons pengguna. LiveKit Cloud menangani penskalaan, jadi lonjakan trafik akan secara otomatis menambah instance.

Biaya Deployment

Menjalankan Grok voice agent di produksi melibatkan dua biaya: API xAI dan hosting LiveKit.

xAI mengenakan biaya $0,05 per menit percakapan suara. LiveKit Cloud menambahkan $0,01 per menit waktu sesi agen. Jika digabung, perkirakan sekitar $0,06 per menit saat agen Anda aktif melayani pengguna.

Paket gratis LiveKit (Build plan) mencakup 1.000 menit sesi agen per bulan tanpa memerlukan kartu kredit. Ini mencakup sekitar 16 jam percakapan, cukup untuk pengujian dan aplikasi bertrafik rendah. Paket berbayar mulai $50/bulan dengan 5.000 menit termasuk dan batas konkurensi lebih tinggi.

Agen tidak menimbulkan biaya saat idle. Biaya hanya berlaku selama percakapan aktif, sehingga deployment yang tidak digunakan semalaman tidak menimbulkan biaya LiveKit. Penagihan xAI mengikuti pola yang sama, hanya menghitung penggunaan API aktual. Sepanjang eksperimen saya saat menulis artikel ini, saya menghabiskan total 78 sen untuk xAI, dengan LiveKit ditanggung oleh paket gratisnya.

Kesimpulan

Sekarang Anda memiliki agen suara yang mendengarkan, berpikir, dan membalas. Agen terhubung ke data live melalui tools, menyesuaikan perilaku mendengarkan untuk berbagai lingkungan, dan berjalan di infrastruktur yang menskalakan tanpa intervensi manual.

Pola kode yang dibahas di sini dapat diperluas ke use case lain. Ganti instruksi asisten riset dengan pedoman dukungan pelanggan dan tambahkan tool yang melakukan kueri database pesanan Anda. Bangun tutor bahasa yang mencari kalimat contoh. Ciptakan antarmuka suara untuk API Anda yang sudah ada.

xAI berencana merilis endpoint text-to-speech dan speech-to-text mandiri, yang akan membuka arsitektur hibrida tempat Anda mencampur kapabilitas suara Grok dengan model bahasa lain. Untuk saat ini, voice agent API menangani keseluruhan pipeline.

Dokumentasi LiveKit Agents mencakup fitur tambahan seperti handoff multi-agen dan persistensi sesi. Dokumentasi xAI membahas lebih dalam format audio dan fitur enterprise.