Tutorial LiveKit Agents: Membangun AI Voice Agent Real-Time dengan Python
Pengantar
LiveKit Agents adalah framework open-source untuk membangun AI agent yang dapat berinteraksi dengan pengguna secara real-time melalui suara, video, dan teks. Framework ini menyediakan abstraksi tingkat tinggi untuk menghubungkan Large Language Model (LLM), Speech-to-Text (STT), dan Text-to-Speech (TTS) ke dalam satu pipeline percakapan yang responsif.
Bayangkan Anda ingin membuat asisten virtual yang bisa menerima panggilan telepon, menjawab pertanyaan pelanggan, atau memandu pengguna melalui proses tertentu, semuanya secara real-time tanpa jeda yang mengganggu. LiveKit Agents memungkinkan hal ini dengan arsitektur yang dioptimalkan untuk latensi rendah.
Dalam tutorial ini, kita akan membahas cara menginstal LiveKit Agents, membangun voice agent pertama Anda, mengintegrasikan berbagai provider AI, dan menerapkan teknik-teknik lanjutan untuk membuat agent yang responsif dan cerdas.
Prasyarat
Sebelum memulai, pastikan Anda memiliki:
- Python 3.9 atau lebih baru
- Akun LiveKit Cloud (gratis untuk development) atau LiveKit server self-hosted
- API key dari salah satu LLM provider (OpenAI, Anthropic, atau Google)
- Pemahaman dasar tentang async programming di Python
Instalasi
Instalasi Package Dasar
pip install livekit-agents
Instalasi Plugin Sesuai Kebutuhan
LiveKit Agents menggunakan sistem plugin untuk integrasi dengan berbagai provider AI. Install plugin sesuai kebutuhan Anda:
# Plugin untuk STT (Speech-to-Text)
pip install livekit-plugins-deepgram
pip install livekit-plugins-google
Plugin untuk LLM
pip install livekit-plugins-openai
pip install livekit-plugins-anthropic
Plugin untuk TTS (Text-to-Speech)
pip install livekit-plugins-cartesia
pip install livekit-plugins-elevenlabs
Plugin untuk VAD (Voice Activity Detection)
pip install livekit-plugins-silero
Atau install semua plugin sekaligus
pip install "livekit-agents[all]"
Setup Environment Variables
Buat file .env di root project Anda:
# LiveKit credentials
LIVEKITURL=wss://your-project.livekit.cloud
LIVEKITAPIKEY=yourapikey
LIVEKITAPISECRET=yourapisecret
AI Provider keys
OPENAIAPIKEY=sk-your-openai-key
DEEPGRAMAPIKEY=your-deepgram-key
CARTESIAAPIKEY=your-cartesia-key
Anda bisa mendapatkan LiveKit credentials secara gratis di LiveKit Cloud.
Konsep Dasar
Arsitektur LiveKit Agents
LiveKit Agents bekerja dengan beberapa komponen utama:
Voice Pipeline
Pipeline percakapan suara terdiri dari:
Audio Input → VAD → STT → LLM → TTS → Audio Output
- VAD (Voice Activity Detection): Mendeteksi kapan pengguna mulai dan berhenti berbicara
- STT (Speech-to-Text): Mengubah suara pengguna menjadi teks
- LLM (Large Language Model): Memproses teks dan menghasilkan respons
- TTS (Text-to-Speech): Mengubah respons teks menjadi suara
Membuat Voice Agent Pertama
Agent Sederhana
Berikut adalah contoh voice agent paling sederhana:
import asyncio
from livekit.agents import AutoSubscribe, JobContext, WorkerOptions, cli
from livekit.agents.voice import AgentSession
from livekit.plugins import deepgram, openai, cartesia, silero
async def entrypoint(ctx: JobContext):
await ctx.connect(autosubscribe=AutoSubscribe.AUDIOONLY)
session = AgentSession(
stt=deepgram.STT(),
llm=openai.LLM(model="gpt-4o-mini"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
)
session.start(ctx.room)
await session.say("Halo! Saya adalah asisten virtual Anda. Ada yang bisa saya bantu?")
if name == "main":
cli.runapp(WorkerOptions(entrypointfnc=entrypoint))
Menjalankan Agent
python myagent.py dev
Command dev akan menjalankan agent dalam development mode, yang secara otomatis membuat room dan menampilkan URL untuk menguji agent Anda di browser.
Menguji di Browser
Setelah agent berjalan, buka URL yang ditampilkan di terminal atau gunakan LiveKit Playground:
https://agents-playground.livekit.io
Masukkan LiveKit credentials Anda dan mulai berbicara dengan agent.
Konfigurasi System Prompt
Mengatur Instruksi Agent
from livekit.agents.llm import ChatContext, ChatMessage
async def entrypoint(ctx: JobContext):
await ctx.connect(autosubscribe=AutoSubscribe.AUDIOONLY)
initialcontext = ChatContext(
messages=[
ChatMessage(
role="system",
content="""Kamu adalah asisten customer service untuk toko online 'TokoMaju'.
Tugasmu adalah membantu pelanggan dengan:
- Informasi produk dan harga
- Status pengiriman pesanan
- Proses pengembalian barang
- Keluhan dan saran
Gunakan bahasa Indonesia yang sopan dan ramah.
Jawab dengan singkat dan jelas, maksimal 2-3 kalimat per respons.
Jika tidak tahu jawabannya, arahkan pelanggan ke customer service manusia.""",
)
]
)
session = AgentSession(
stt=deepgram.STT(language="id"),
llm=openai.LLM(model="gpt-4o-mini"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
chatctx=initialcontext,
)
session.start(ctx.room)
await session.say("Selamat datang di TokoMaju! Ada yang bisa saya bantu hari ini?")
Function Calling (Tool Use)
Mendaftarkan Tools untuk Agent
Salah satu fitur paling powerful dari LiveKit Agents adalah kemampuan untuk menghubungkan agent dengan fungsi-fungsi eksternal:
from livekit.agents import llm
class OrderLookup(llm.FunctionContext):
@llm.aicallable(description="Mencari status pesanan berdasarkan nomor order")
async def checkorderstatus(self, orderid: str) -> str:
# Simulasi lookup database
orders = {
"ORD001": {"status": "Sedang dikirim", "estimasi": "2 hari lagi"},
"ORD002": {"status": "Sudah diterima", "estimasi": "-"},
"ORD003": {"status": "Diproses", "estimasi": "3-5 hari kerja"},
}
order = orders.get(orderid.upper())
if order:
return f"Pesanan {orderid}: Status {order['status']}, Estimasi: {order['estimasi']}"
return f"Pesanan dengan nomor {orderid} tidak ditemukan."
@llm.aicallable(description="Mendapatkan informasi produk berdasarkan nama")
async def getproductinfo(self, productname: str) -> str:
products = {
"laptop gaming": {"harga": "Rp 15.000.000", "stok": 5},
"mouse wireless": {"harga": "Rp 250.000", "stok": 50},
"keyboard mechanical": {"harga": "Rp 800.000", "stok": 20},
}
product = products.get(productname.lower())
if product:
return f"{productname}: Harga {product['harga']}, Stok tersedia: {product['stok']} unit"
return f"Produk '{productname}' tidak ditemukan dalam katalog kami."
async def entrypoint(ctx: JobContext):
await ctx.connect(autosubscribe=AutoSubscribe.AUDIOONLY)
fncctx = OrderLookup()
session = AgentSession(
stt=deepgram.STT(language="id"),
llm=openai.LLM(model="gpt-4o"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
fncctx=fncctx,
)
session.start(ctx.room)
await session.say("Halo! Saya bisa membantu cek status pesanan atau informasi produk. Silakan bertanya!")
Menggunakan Provider Alternatif
Anthropic Claude sebagai LLM
from livekit.plugins import anthropic
session = AgentSession(
stt=deepgram.STT(),
llm=anthropic.LLM(model="claude-sonnet-4-6"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
)
Google Gemini sebagai LLM
from livekit.plugins import google
session = AgentSession(
stt=google.STT(languages=["id-ID"]),
llm=google.LLM(model="gemini-2.0-flash"),
tts=google.TTS(),
vad=silero.VAD.load(),
)
ElevenLabs untuk TTS Berkualitas Tinggi
from livekit.plugins import elevenlabs
session = AgentSession(
stt=deepgram.STT(),
llm=openai.LLM(model="gpt-4o-mini"),
tts=elevenlabs.TTS(
voiceid="your-voice-id",
model="eleventurbov25",
),
vad=silero.VAD.load(),
)
Teknik Lanjutan
Menangani Interupsi (Turn-Taking)
LiveKit Agents secara otomatis menangani interupsi, tetapi Anda bisa mengkustomisasi perilakunya:
session = AgentSession(
stt=deepgram.STT(),
llm=openai.LLM(model="gpt-4o-mini"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
minendpointingdelay=0.5,
allowinterruptions=True,
)
Parameter minendpointingdelay mengatur berapa lama agent menunggu setelah pengguna berhenti berbicara sebelum mulai merespons. Nilai lebih rendah membuat agent lebih responsif, tapi bisa memotong kalimat pengguna yang sedang berpikir.
Event Handlers
Anda bisa mendengarkan berbagai event selama percakapan:
from livekit.agents.voice import AgentSession
async def entrypoint(ctx: JobContext):
await ctx.connect(autosubscribe=AutoSubscribe.AUDIOONLY)
session = AgentSession(
stt=deepgram.STT(),
llm=openai.LLM(model="gpt-4o-mini"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
)
@session.on("userspeechcommitted")
def onuserspeech(msg):
print(f"User berkata: {msg.content}")
@session.on("agentspeechcommitted")
def onagentspeech(msg):
print(f"Agent merespons: {msg.content}")
@session.on("functioncallsfinished")
def onfunctiondone(calledfunctions):
for fn in calledfunctions:
print(f"Function {fn.callinfo.functioninfo.name} selesai: {fn.result}")
session.start(ctx.room)
await session.say("Halo! Saya siap membantu Anda.")
Multi-Modal Agent (Suara + Video)
LiveKit Agents juga mendukung input video untuk agent yang bisa melihat:
from livekit.agents import AutoSubscribe
async def entrypoint(ctx: JobContext):
await ctx.connect(autosubscribe=AutoSubscribe.SUBSCRIBEALL)
session = AgentSession(
stt=deepgram.STT(),
llm=openai.LLM(model="gpt-4o"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
)
session.start(
ctx.room,
agentvideo=True,
)
await session.say("Saya bisa melihat dan mendengar Anda. Tunjukkan sesuatu dan saya akan menjelaskannya!")
Session dengan Memory (Konteks Percakapan)
Untuk menjaga konteks percakapan yang lebih panjang:
from livekit.agents.llm import ChatContext, ChatMessage
async def entrypoint(ctx: JobContext):
await ctx.connect(autosubscribe=AutoSubscribe.AUDIOONLY)
chatctx = ChatContext(
messages=[
ChatMessage(
role="system",
content="Kamu adalah asisten medis yang membantu pasien menjadwalkan appointment.",
)
]
)
session = AgentSession(
stt=deepgram.STT(),
llm=openai.LLM(model="gpt-4o"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
chatctx=chatctx,
maxtoolsteps=5,
)
@session.on("userspeechcommitted")
def onuserspeech(msg):
# Log semua percakapan untuk audit trail
with open("conversationlog.txt", "a") as f:
f.write(f"User: {msg.content}\n")
@session.on("agentspeechcommitted")
def onagentspeech(msg):
with open("conversationlog.txt", "a") as f:
f.write(f"Agent: {msg.content}\n")
session.start(ctx.room)
Telephony Integration (SIP)
LiveKit Agents mendukung integrasi telepon via SIP untuk menerima panggilan telepon:
from livekit.agents import AutoSubscribe, JobContext, WorkerOptions, cli, JobRequest
async def requesthandler(req: JobRequest):
# Filter berdasarkan metadata atau SIP caller
await req.accept()
async def entrypoint(ctx: JobContext):
await ctx.connect(autosubscribe=AutoSubscribe.AUDIOONLY)
# Deteksi apakah ini panggilan telepon
isphonecall = any(
p.kind == "SIP" for p in ctx.room.remoteparticipants.values()
)
systemprompt = """Kamu adalah resepsionis virtual untuk Klinik Sehat Sejahtera.
Bantu pasien untuk:
Membuat janji temu dengan dokter
Mengecek jadwal dokter yang tersedia
Memberikan informasi umum klinik
"""
if isphonecall:
systemprompt += "\nPengguna menelepon via telepon. Gunakan bahasa yang lebih formal."
session = AgentSession(
stt=deepgram.STT(language="id"),
llm=openai.LLM(model="gpt-4o-mini"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
chatctx=ChatContext(
messages=[ChatMessage(role="system", content=systemprompt)]
),
)
session.start(ctx.room)
greeting = "Selamat datang di Klinik Sehat Sejahtera. Ada yang bisa saya bantu?"
await session.say(greeting)
if name == "main":
cli.runapp(
WorkerOptions(
entrypointfnc=entrypoint,
requestfnc=requesthandler,
)
)
Deployment ke Production
Menggunakan Docker
Buat Dockerfile untuk agent Anda:
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "myagent.py", "start"]
# requirements.txt
livekit-agents>=1.0.0
livekit-plugins-openai>=1.0.0
livekit-plugins-deepgram>=1.0.0
livekit-plugins-cartesia>=1.0.0
livekit-plugins-silero>=1.0.0
Deploy ke LiveKit Cloud
LiveKit Cloud menyediakan managed infrastructure untuk menjalankan agent:
# Login ke LiveKit Cloud CLI
lk cloud login
Deploy agent
lk cloud agent deploy --entry myagent.py
Monitoring dan Logging
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("my-agent")
async def entrypoint(ctx: JobContext):
logger.info(f"Agent bergabung ke room: {ctx.room.name}")
await ctx.connect(autosubscribe=AutoSubscribe.AUDIOONLY)
session = AgentSession(
stt=deepgram.STT(),
llm=openai.LLM(model="gpt-4o-mini"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
)
@session.on("userspeechcommitted")
def onuserspeech(msg):
logger.info(f"User input: {msg.content}")
@session.on("agentspeechcommitted")
def onagentspeech(msg):
logger.info(f"Agent output: {msg.content}")
@session.on("error")
def onerror(error):
logger.error(f"Error terjadi: {error}")
session.start(ctx.room)
logger.info("Agent session dimulai")
Best Practices
1. Optimalkan Latensi
Pilih provider yang paling cepat untuk setiap komponen pipeline:
# Konfigurasi untuk latensi minimal
session = AgentSession(
stt=deepgram.STT(
model="nova-2",
language="id",
interimresults=True,
),
llm=openai.LLM(
model="gpt-4o-mini",
temperature=0.7,
),
tts=cartesia.TTS(
modelid="sonic-english",
speed=1.0,
),
vad=silero.VAD.load(
minspeechduration=0.1,
minsilenceduration=0.3,
),
minendpointingdelay=0.3,
)
2. Tangani Error dengan Baik
from livekit.agents.voice import AgentSession
async def entrypoint(ctx: JobContext):
await ctx.connect(autosubscribe=AutoSubscribe.AUDIOONLY)
session = AgentSession(
stt=deepgram.STT(),
llm=openai.LLM(model="gpt-4o-mini"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
)
@session.on("error")
def onerror(error):
logger.error(f"Session error: {error}")
session.start(ctx.room)
try:
await session.say("Halo! Saya siap membantu.")
except Exception as e:
logger.error(f"Gagal menyapa: {e}")
await session.say("Maaf, terjadi gangguan teknis. Silakan coba beberapa saat lagi.")
3. Gunakan Streaming untuk Respons Cepat
LiveKit Agents secara default sudah menggunakan streaming untuk LLM dan TTS. Token dari LLM langsung dikirim ke TTS begitu tersedia, sehingga pengguna mulai mendengar respons sebelum LLM selesai menghasilkan semua teks.
4. Batasi Panjang Respons
Untuk voice agent, respons yang terlalu panjang membuat pengalaman pengguna buruk. Gunakan system prompt yang membatasi panjang respons:
systemprompt = """Jawab pertanyaan dengan singkat dan jelas.
Maksimal 2-3 kalimat per respons.
Jika topik kompleks, tanyakan apakah pengguna ingin penjelasan lebih detail."""
5. Implementasi Graceful Shutdown
import signal
async def entrypoint(ctx: JobContext):
await ctx.connect(autosubscribe=AutoSubscribe.AUDIOONLY)
session = AgentSession(
stt=deepgram.STT(),
llm=openai.LLM(model="gpt-4o-mini"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
)
async def shutdown():
await session.say("Terima kasih telah menghubungi kami. Sampai jumpa!")
await session.close()
ctx.addshutdowncallback(shutdown)
session.start(ctx.room)
await session.say("Halo! Ada yang bisa saya bantu?")
Contoh Project: Asisten Restoran
Berikut contoh lengkap agent untuk menerima pesanan di restoran:
import asyncio
from datetime import datetime
from livekit.agents import AutoSubscribe, JobContext, WorkerOptions, cli, llm
from livekit.agents.voice import AgentSession
from livekit.agents.llm import ChatContext, ChatMessage
from livekit.plugins import deepgram, openai, cartesia, silero
class RestaurantTools(llm.FunctionContext):
def init(self):
super().init()
self.orders = []
@llm.aicallable(description="Menambahkan item ke pesanan pelanggan")
async def addtoorder(self, item: str, quantity: int = 1, notes: str = "") -> str:
self.orders.append({
"item": item,
"quantity": quantity,
"notes": notes,
"time": datetime.now().isoformat(),
})
return f"Berhasil menambahkan {quantity}x {item} ke pesanan. {f'Catatan: {notes}' if notes else ''}"
@llm.aicallable(description="Melihat semua item dalam pesanan saat ini")
async def vieworder(self) -> str:
if not self.orders:
return "Pesanan masih kosong."
orderlist = "\n".join(
f"- {o['quantity']}x {o['item']}{f' ({o['notes']})' if o['notes'] else ''}"
for o in self.orders
)
return f"Pesanan saat ini:\n{orderlist}"
@llm.aicallable(description="Menghitung total estimasi harga pesanan")
async def calculatetotal(self) -> str:
menuprices = {
"nasi goreng": 25000,
"mie goreng": 23000,
"ayam bakar": 35000,
"es teh": 8000,
"jus jeruk": 15000,
}
total = 0
details = []
for o in self.orders:
itemlower = o["item"].lower()
price = menuprices.get(itemlower, 20000)
subtotal = price * o["quantity"]
total += subtotal
details.append(f"{o['quantity']}x {o['item']}: Rp {subtotal:,.0f}")
return f"Rincian:\n" + "\n".join(details) + f"\n\nTotal: Rp {total:,.0f}"
async def entrypoint(ctx: JobContext):
await ctx.connect(autosubscribe=AutoSubscribe.AUDIOONLY)
tools = RestaurantTools()
chatctx = ChatContext(
messages=[
ChatMessage(
role="system",
content="""Kamu adalah asisten pemesanan untuk Restoran Nusantara.
Menu kami:
- Nasi Goreng Special: Rp 25.000
- Mie Goreng: Rp 23.000
- Ayam Bakar: Rp 35.000
- Es Teh Manis: Rp 8.000
- Jus Jeruk Segar: Rp 15.000
Tugasmu:
Sambut pelanggan dengan ramah
Bantu mereka memilih menu
Catat pesanan menggunakan tools yang tersedia
Konfirmasi pesanan dan total harga sebelum finalisasi
Gunakan bahasa Indonesia yang ramah dan natural.""",
)
]
)
session = AgentSession(
stt=deepgram.STT(language="id"),
llm=openai.LLM(model="gpt-4o"),
tts=cartesia.TTS(),
vad=silero.VAD.load(),
chatctx=chatctx,
fncctx=tools,
)
session.start(ctx.room)
await session.say(
"Selamat datang di Restoran Nusantara! Saya siap membantu Anda memesan. "
"Mau pesan apa hari ini?"
)
if name == "main":
cli.runapp(WorkerOptions(entrypoint_fnc=entrypoint))
Kesimpulan
LiveKit Agents menyederhanakan proses pembuatan AI agent real-time yang mampu berinteraksi melalui suara, video, dan teks. Dengan arsitektur pipeline yang modular dan dukungan plugin untuk berbagai provider AI, Anda bisa membangun voice agent yang canggih tanpa harus mengelola infrastruktur WebRTC atau audio processing secara manual.
Poin-poin penting yang telah kita pelajari:
- Instalasi dan setup LiveKit Agents beserta plugin-plugin yang dibutuhkan
- Membuat voice agent sederhana dengan pipeline STT → LLM → TTS
- Function calling untuk menghubungkan agent dengan logika bisnis
- Integrasi multi-provider (OpenAI, Anthropic, Google, Deepgram, dll.)
- Teknik lanjutan seperti telephony integration, multi-modal agent, dan event handling
- Best practices untuk optimasi latensi, error handling, dan deployment
Framework ini sangat cocok untuk membangun customer service automation, virtual receptionist, voice-enabled IoT, interactive tutoring system, dan berbagai use case real-time AI lainnya.
Untuk informasi lebih lanjut, kunjungi dokumentasi resmi LiveKit Agents dan eksplorasi contoh-contoh project yang tersedia di repository GitHub mereka.