API Grok Voice Agent: Cách xây trợ lý giọng nói thời gian thực

Các agent AI giọng nói đang bùng nổ. Người dùng muốn trò chuyện với ứng dụng thay vì gõ phím, và công nghệ nay đã đủ tốt để những cuộc đối thoại trở nên tự nhiên.

Nếu bạn muốn xây một agent như vậy, API Grok Voice Agent của xAI là điểm khởi đầu vững chắc. API này cho thời gian phản hồi dưới một giây và chi phí thấp hơn phần lớn lựa chọn khác, đồng thời tương thích thả-vào với mã OpenAI hiện có.

Hướng dẫn này chỉ bạn cách xây một agent giọng nói hoạt động được từ con số 0. Bạn sẽ cấu hình xác thực, tuỳ chỉnh tính cách và giọng, thêm khả năng gọi công cụ, và triển khai sản xuất với LiveKit Cloud. API chạy trên Grok 3, được xAI điều chỉnh cho hội thoại giọng nói thời gian thực thay vì quy trình văn bản-vào, văn bản-ra thông thường.

Grok Voice Agent API là gì?

Grok Voice Agent API là nền tảng hội thoại giọng nói thời gian thực của xAI, ra mắt tháng 12/2025. Nó xử lý âm thanh trực tiếp không cần chuyển đổi qua lại giữa giọng nói và văn bản như thường lệ, giúp rút ngắn thời gian phản hồi mà vẫn giữ cuộc trò chuyện tự nhiên.

Các hệ thống AI giọng nói truyền thống ghép ba bước riêng: chuyển giọng nói thành văn bản, cho văn bản qua mô hình ngôn ngữ, rồi tổng hợp phản hồi trở lại âm thanh. Cách này hoạt động, nhưng mỗi lần chuyển tiếp đều thêm độ trễ. Khi tính cả phiên âm, xử lý và tổng hợp, người dùng phải chờ 500ms đến 1.000ms trước khi có phản hồi. Những khoảng dừng đó tích lại khiến hội thoại trở nên máy móc.

Grok Voice Agent bỏ qua toàn bộ chuyển đổi này. Hệ thống nhận âm thanh, suy luận trong miền âm thanh, và xuất âm thanh bằng một mô hình duy nhất được huấn luyện trên lời nói hội thoại. Kiến trúc này mang lại thời gian tới-khối-âm-thanh-đầu-tiên trung bình 0,78 giây, đồng thời hỗ trợ giao tiếp song công đầy đủ (âm thanh hai chiều đồng thời, agent vừa nghe vừa nói), nên agent có thể phản hồi mà không cần chờ lượt nói nghiêm ngặt.

Thiết lập môi trường Grok Voice Agent

Xây agent giọng nói với Grok cần ghép với LiveKit, một nền tảng WebRTC mã nguồn mở. Grok cung cấp mô hình AI hội thoại, còn LiveKit quản lý hạ tầng âm thanh thời gian thực kết nối người dùng với agent của bạn. Phần này hướng dẫn thiết lập cả hai dịch vụ.

Thiết lập Grok

Truy cập console.x.ai và tạo tài khoản qua X, email, Google, hoặc Apple. Bảng điều khiển xAI yêu cầu nạp tín dụng trả trước trước khi bạn có thể gọi API. Mua tín dụng trong mục Billing.

Sau khi có tín dụng, vào API Keys và tạo khoá mới. Bảng điều khiển chỉ hiển thị khoá một lần, nên hãy sao chép ngay và lưu an toàn. Nếu mất, bạn cần tạo khoá thay thế và cập nhật ứng dụng. Để xem hướng dẫn chi tiết hơn về hệ sinh thái API của xAI, xem hướng dẫn Grok 3 API.

Thiết lập LiveKit

LiveKit là hạ tầng WebRTC cho âm thanh và video thời gian thực. Nó xử lý lớp truyền tải âm thanh mà Grok cần để kết nối với người dùng. Khi xây agent giọng nói, LiveKit quản lý các phòng nơi hội thoại diễn ra, định tuyến luồng âm thanh giữa những người tham gia, và cung cấp hạ tầng triển khai. Khung LiveKit Agents bao bọc độ phức tạp này, cho phép bạn tập trung vào hành vi của agent trong khi nó xử lý kết nối, mã hoá âm thanh và phát hiện lượt nói.

Khung này hỗ trợ nhiều nhà cung cấp AI, bao gồm xAI. Nó có sân chơi thử nghiệm qua giao diện web, bạn sẽ dùng để kiểm tra agent trước khi triển khai.

Đăng ký tại cloud.livekit.io. Gói miễn phí đủ cho phát triển và thử nghiệm. Tạo một dự án trong bảng điều khiển. Vào Settings, rồi API Keys. Sao chép ba thông tin xác thực: LIVEKIT_URL (điểm cuối WebSocket của dự án), LIVEKIT_API_KEY (định danh công khai), và LIVEKIT_API_SECRET (khoá xác thực riêng). Các thông tin này xác thực mã agent của bạn với dự án LiveKit Cloud.

Cài đặt phụ thuộc và cấu hình

Cài các gói cần thiết:

uv add "livekit-agents[xai,openai]>=1.3.10" python-dotenvĐược hỗ trợ bởi

Lệnh này cài khung LiveKit agents kèm plugin xAI và các phụ thuộc OpenAI (plugin xAI xây trên khả năng tương thích với Realtime API của OpenAI), cùng python-dotenv để quản lý biến môi trường.

Tạo tệp .env ở thư mục gốc dự án:

XAI_API_KEY=xai-YourActualKeyHere
 LIVEKIT_URL=wss://your-project.livekit.cloud
 LIVEKIT_API_KEY=APIYourKeyHere
 LIVEKIT_API_SECRET=YourSecretHereĐược hỗ trợ bởi

Thay các giá trị giữ chỗ bằng thông tin thực tế của bạn. Nạp các thông tin này trong mã Python:

from dotenv import load_dotenv
 load_dotenv()Được hỗ trợ bởi

Điều này giúp cả thư viện xAI lẫn LiveKit đọc được thông tin xác thực. Thêm .env vào .gitignore để tránh lộ thông tin qua hệ thống quản lý phiên bản.

Xây Grok Voice Agent đầu tiên của bạn

Sau khi cấu hình môi trường, bạn có thể xây một agent giọng nói hoạt động. Bắt đầu với các import và lớp agent trong tệp mới tên 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.",
 	)Được hỗ trợ bởi

Lớp con Agent của bạn chỉ giữ phần hướng dẫn định hình cách agent phản hồi. Chúng hoạt động như một nhắc hệ thống, nói cho agent biết vai trò cần đóng. Cấu hình mô hình thực tế nằm ở nơi khác.

Tiếp theo, thiết lập máy chủ và bộ xử lý kết nối:

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(),
 	)Được hỗ trợ bởi

Decorator @server.rtc_session() báo cho LiveKit chạy hàm entrypoint khi có ai đó kết nối. Bên trong, AgentSession nhận cấu hình mô hình, bao gồm chọn một trong bảy giọng của Grok (Ara, Eve, Leo, Sal, Rex, Mika hoặc Valentin). Khi session.start() chạy, nó kết nối agent với phòng LiveKit nơi hội thoại diễn ra.

Hội thoại giọng nói đòi hỏi chờ đầu vào/ra âm thanh mà không làm treo chương trình, nên hàm dùng async def và await để xử lý đồng thời.

Cuối cùng, thêm điểm vào chương trình:

if __name__ == "__main__":
 	cli.run_app(server)Được hỗ trợ bởi

Chạy agent ở chế độ phát triển:

uv run agent.py devĐược hỗ trợ bởi

Terminal hiển thị chuỗi khởi động: khởi tạo worker, máy chủ HTTP lắng nghe trên cổng cục bộ, và đăng ký với dự án LiveKit Cloud của bạn.

Để kiểm thử agent, vào bảng điều khiển LiveKit Cloud tại cloud.livekit.io. Chọn dự án, rồi nhấp tab Sandbox ở thanh bên. Chọn Web Voice Agent từ các mẫu.

Trang mẫu hiển thị bản xem trước giao diện giọng nói cùng chi tiết những gì đi kèm. Nhấp nút Create sandbox.

Trong hộp thoại hiện ra, bạn có thể cấu hình URL tuỳ chỉnh, bật các khả năng như camera và chia sẻ màn hình, và điều chỉnh giao diện. Mặc định là đủ để thử nghiệm, nên nhấp Create, rồi Done.

Quay lại trang Sandbox, sandbox mới của bạn xuất hiện dưới mục Sandbox apps. Nhấp Launch để mở.

Nhấp Start Call và cấp quyền micro khi được hỏi. Quan sát terminal để thấy thông báo log này, cho biết agent đã sẵn sàng nhận âm thanh:

DEBUG livekit.agents start reading stream {"participant": "...", "source": "SOURCE_MICROPHONE", ...}Được hỗ trợ bởi

Sau khi thông báo xuất hiện, phản hồi sẽ đến rất nhanh.

Khi bạn hỏi về điều agent không thể truy cập (như thời tiết hiện tại ở một thành phố cụ thể), nó sẽ giải thích giới hạn thay vì bịa ra.

Cách thêm công cụ cho Grok Voice Agent

Agent cơ bản có thể trò chuyện nhưng không thể tra cứu. Gọi công cụ cho phép Grok chạy hàm giữa cuộc đối thoại và nói về kết quả. Bạn có thể dùng công cụ tích hợp sẵn của xAI hoặc tự định nghĩa.

Dùng công cụ tích hợp sẵn

Plugin xAI có WebSearch cho truy vấn web chung và XSearch để tìm bài đăng trên X. Import chúng và truyền vào 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)Được hỗ trợ bởi

Tham số tools nhận danh sách đối tượng công cụ. Chạy agent và thử các câu hỏi như "Tin tức mới nhất về AI là gì?" hoặc "Mọi người đang nói gì về Grok trên X?" Log terminal có thể hiển thị cảnh báo về các hàm AI không rõ như web_search_with_snippets hoặc x_semantic_search, nhưng các công cụ vẫn trả về thông tin hiện thời.

Âm thanh song công đầy đủ của Grok cũng thể hiện rõ khi dùng công cụ. Bạn có thể ngắt lời khi agent đang nói, và nó sẽ dừng, lắng nghe, rồi điều chỉnh phản hồi. Điều này khiến hội thoại bớt máy móc hơn so với các hệ thống buộc phải chờ agent nói xong.

Thêm công cụ tuỳ chỉnh

Công cụ tích hợp sẵn bao phủ các trường hợp phổ biến, nhưng tự định nghĩa công cụ giúp bạn kiểm soát tham số, xử lý lỗi và lựa chọn API để gọi. Phần này minh hoạ tạo công cụ tuỳ chỉnh dùng điểm cuối tìm kiếm của Firecrawl, cung cấp các tuỳ chọn lọc như limit, lang và country mà tìm kiếm web tích hợp sẵn không mở ra.

Đăng ký tại firecrawl.dev. Gói miễn phí gồm 500 tín dụng và không cần thẻ. Cài SDK và thêm khoá vào .env:

uv add firecrawl-pyĐược hỗ trợ bởi

FIRECRAWL_API_KEY=fc-your-key-hereĐược hỗ trợ bởi

Công cụ tuỳ chỉnh là các phương thức được trang trí với @function_tool(). Cập nhật import trong 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()Được hỗ trợ bởi

Bổ sung gồm function_tool cho decorator, RunContext được truyền vào các hàm công cụ, và FirecrawlApp cho client Firecrawl. WebSearch được bỏ vì công cụ tuỳ chỉnh thay thế nó.

Định nghĩa công cụ như một phương thức trên lớp agent của bạn:

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
         	]
     	}Được hỗ trợ bởi

Grok đọc docstring để hiểu công cụ làm gì. Khi bạn hỏi "Tỷ giá USD sang EURO hiện tại là bao nhiêu?", Grok trích xuất truy vấn, gọi hàm của bạn và đưa kết quả vào phản hồi.

Các phương thức được trang trí với @function_tool() sẽ tự động đăng ký, nên hãy bỏ WebSearch() khỏi danh sách công cụ:

session = AgentSession(
     llm=realtime.RealtimeModel(voice="ara"),
 	tools=[
     	XSearch(),
 	],
 )Được hỗ trợ bởi

Chạy agent đã cập nhật:

uv run search_agent.py devĐược hỗ trợ bởi

Terminal hiển thị việc thực thi công cụ:

DEBUG livekit.agents executing tool {
 	"function": "search_web",
 	"arguments": "{\"query\":\"current USD to EURO exchange rate\"}",
 	...
 }
DEBUG livekit.agents tools execution completed {...}Được hỗ trợ bởi

Trong thử nghiệm của tôi, Firecrawl trả kết quả khoảng hai giây. Bạn có thể kết hợp nhiều công cụ tuỳ chỉnh với công cụ tích hợp trong cùng một agent. Ví dụ, agent hỗ trợ khách hàng có thể dùng XSearch cùng các công cụ tuỳ chỉnh lookup_order() và check_inventory() kết nối cơ sở dữ liệu nội bộ.

Tuỳ chỉnh phát hiện lượt nói

Thiết lập phát hiện lượt nói mặc định xử lý tốt các cuộc hội thoại điển hình. Cần điều chỉnh khi môi trường hoặc hành vi người dùng khác thường. Phòng ồn có thể khiến agent phản hồi âm thanh nền, trong khi người dùng dừng lại để suy nghĩ có thể bị ngắt lời trước khi nói xong.

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,
     	),
 	),
 )Được hỗ trợ bởi

Tham số threshold thiết lập âm lượng cần đạt để được tính là lời nói, từ 0,0 đến 1,0. Tăng giá trị này lên 0,7 hoặc cao hơn sẽ hữu ích trong môi trường ồn, nơi âm thanh nền có thể kích hoạt phản hồi.

Tham số prefix_padding_ms quyết định bao nhiêu âm thanh được ghi lại trước thời điểm phát hiện bắt đầu nói. Mặc định 300ms giúp không bị cắt âm tiết đầu. Tăng giá trị nếu người dùng phản ánh bị cắt từ mở đầu.

Tham số silence_duration_ms kiểm soát thời gian agent chờ sau khi bạn ngừng nói trước khi phản hồi. Ở 200ms, hội thoại rất nhạy. Tăng lên 400 hoặc 500ms phù hợp với người dùng hay ngắt câu giữa chừng hoặc nói chậm.

Với giao diện nhấn-để-nói hoặc hệ thống thoại nơi bạn cần kiểm soát luồng hội thoại rõ ràng, hãy tắt phát hiện lượt nói tự động:

session = AgentSession(
 	llm=realtime.RealtimeModel(
     	voice="ara",
     	turn_detection=None,
 	),
 )Được hỗ trợ bởi

Khi đó agent sẽ chờ tín hiệu theo lập trình trước khi phản hồi thay vì lắng nghe khoảng lặng.

Triển khai Grok Voice Agent lên môi trường sản xuất

Chế độ phát triển gắn agent với máy cục bộ của bạn. Để triển khai sản xuất chạy 24/7 và tự mở rộng theo nhu cầu, LiveKit Cloud sẽ lưu trữ agent của bạn trên hạ tầng của họ.

Chuẩn bị cho triển khai

LiveKit CLI nhận diện loại dự án qua tệp phụ thuộc. Tạo requirements.txt trong thư mục agent:

livekit-agents[xai,openai]>=1.3.10
python-dotenv>=1.2.1
firecrawl-py>=4.12.0Được hỗ trợ bởi

Tạo tệp riêng cho bí mật sản xuất. LiveKit Cloud tự động cung cấp LIVEKIT_URL, LIVEKIT_API_KEY và LIVEKIT_API_SECRET, nên bạn chỉ cần thêm các API key khác của mình:

XAI_API_KEY=xai-your-key-here
FIRECRAWL_API_KEY=fc-your-key-hereĐược hỗ trợ bởi

Lưu tệp này thành .env.production và thêm vào .gitignore.

Triển khai agent

Xác thực CLI với tài khoản LiveKit Cloud của bạn:

lk cloud authĐược hỗ trợ bởi

Lệnh này mở trình duyệt để liên kết CLI với dự án của bạn. Sau khi xác thực, triển khai agent:

lk agent create --secrets-file .env.productionĐược hỗ trợ bởi

CLI đăng ký agent của bạn, tạo Dockerfile, build image container và triển khai lên LiveKit Cloud. Log sẽ stream về terminal khi agent khởi động:

{"message": "registered worker", "level": "INFO", "name": "livekit.agents", "url": "https://your-project.livekit.cloud", "region": "Germany 2", ...}Được hỗ trợ bởi

Kiểm tra trạng thái triển khai:

lk agent statusĐược hỗ trợ bởi

┌─────────────────┬─────────────────┬────────────┬─────────┬────────┬─────────┬───────────┐
 │ ID          	│ Version     	│ Region 	│ Status  │ CPU	│ Mem 	│ Replicas  │
 ├─────────────────┼─────────────────┼────────────┼─────────┼────────┼─────────┼───────────┤
 │ CA_AAVy5WbUYpmA │ v20260109102531 │ eu-central │ Running │ 0m / 2 │ 0 / 4GB │ 0 / 1 / 1 │
 └─────────────────┴─────────────────┴────────────┴─────────┴────────┴─────────┴───────────┘Được hỗ trợ bởi

Người dùng truy cập agent của bạn như thế nào

URL trong log triển khai (https://your-project.livekit.cloud) là backend WebSocket, không phải giao diện người dùng. Người dùng tương tác với agent thông qua frontend kết nối tới backend này.

Sandbox bạn tạo trước đó phục vụ đúng mục đích này. Vào bảng điều khiển LiveKit, mở phần Sandbox và sao chép URL sandbox của bạn. URL này công khai và hoạt động không cần xác thực. Chia sẻ với người dùng và họ có thể bắt đầu trò chuyện với agent ngay lập tức.

Để có trải nghiệm gắn thương hiệu, tuỳ chỉnh giao diện sandbox trong bảng điều khiển (logo, màu sắc, văn bản nút) hoặc tự xây frontend bằng SDK JavaScript của LiveKit.

Quản lý triển khai

Xem log thời gian thực từ agent đã triển khai:

lk agent logsĐược hỗ trợ bởi

Triển khai bản cập nhật sau khi sửa mã:

lk agent deploy --secrets-file .env.productionĐược hỗ trợ bởi

LiveKit dùng triển khai cuốn chiếu. Phiên bản mới xử lý các phiên mới trong khi phiên bản hiện tại hoàn tất các cuộc trò chuyện đang diễn ra, vì vậy cập nhật không gây gián đoạn.

Khôi phục phiên bản trước nếu có sự cố:

lk agent rollbackĐược hỗ trợ bởi

Agent đã triển khai chạy độc lập với máy cục bộ của bạn. Đóng terminal, tắt máy, agent vẫn phản hồi người dùng. LiveKit Cloud xử lý mở rộng, nên lưu lượng tăng đột biến sẽ tự động khởi chạy thêm phiên bản.

Chi phí triển khai

Chạy Grok voice agent trong sản xuất gồm hai chi phí: API của xAI và lưu trữ của LiveKit.

xAI tính $0,05 mỗi phút hội thoại giọng nói. LiveKit Cloud tính $0,01 mỗi phút thời gian phiên agent. Gộp lại, ước khoảng $0,06 mỗi phút khi agent đang phục vụ người dùng.

Gói miễn phí (Build) của LiveKit bao gồm 1.000 phút phiên agent mỗi tháng, không cần thẻ. Điều này đủ cho khoảng 16 giờ hội thoại, phù hợp thử nghiệm và ứng dụng lưu lượng thấp. Các gói trả phí bắt đầu từ $50/tháng với 5.000 phút kèm theo và giới hạn đồng thời cao hơn.

Agent không tốn phí khi nhàn rỗi. Chỉ tính phí trong lúc hội thoại đang hoạt động, nên triển khai để không dùng qua đêm sẽ không phát sinh phí LiveKit. Hoá đơn xAI theo cùng nguyên tắc, chỉ đo lường mức sử dụng API thực tế. Trong suốt quá trình thử nghiệm khi viết bài này, tôi chỉ tốn tổng cộng 78 xu cho xAI, còn LiveKit nằm trong gói miễn phí.

Kết luận

Giờ bạn đã có một agent giọng nói biết lắng nghe, suy nghĩ và hồi đáp. Agent kết nối dữ liệu trực tiếp qua công cụ, điều chỉnh hành vi lắng nghe cho các môi trường khác nhau, và chạy trên hạ tầng tự mở rộng không cần can thiệp thủ công.

Các mẫu mã trong bài có thể mở rộng cho nhiều trường hợp khác. Thay chỉ dẫn trợ lý nghiên cứu bằng hướng dẫn hỗ trợ khách hàng và thêm công cụ truy vấn cơ sở dữ liệu đơn hàng. Xây gia sư ngôn ngữ tìm câu ví dụ. Tạo giao diện giọng nói cho API hiện có của bạn.

xAI dự định phát hành các điểm cuối chuyển văn bản-thành-giọng nói và giọng nói-thành-văn bản độc lập, mở ra kiến trúc lai nơi bạn kết hợp khả năng giọng nói của Grok với các mô hình ngôn ngữ khác. Hiện tại, API voice agent xử lý toàn bộ chu trình.

Tài liệu LiveKit Agents bao gồm các tính năng bổ sung như bàn giao đa-agent và lưu phiên. Tài liệu xAI đi sâu về định dạng âm thanh và tính năng doanh nghiệp.