Grok 语音代理 API：构建实时语音助手的方式

语音 AI 代理正当其时。用户希望通过“说话”而不是“打字”与应用交流，而相关技术也终于足够成熟，让对话听起来更自然。

如果您想动手构建，xAI 的 Grok 语音代理 API 是很好的起点。它提供亚秒级响应时间、成本低于多数替代方案，并且与现有 OpenAI 代码即插即用。

本教程将从零开始带您搭建一个可用的语音代理。您将完成身份验证接入、配置角色与声音选项、添加工具调用，并使用 LiveKit Cloud 部署到生产。该 API 运行在 Grok 3 之上，xAI 针对实时语音对话对其进行了适配，而非传统的“文本输入—文本输出”流程。

什么是 Grok 语音代理 API？

Grok 语音代理 API 是 xAI 的实时语音对话平台，于 2025 年 12 月发布。它直接处理音频，不再进行常规的语音转文本及回转流程，在保持对话自然流畅的同时，显著降低响应延迟。

传统语音 AI 系统将三个独立步骤串联：将语音转录为文本、用语言模型处理该文本、再将响应合成为音频。该方法可行，但组件之间的每次传递都会引入延迟。综合转写、处理与合成的耗时，用户通常要等待 500ms 到 1000ms 才能听到回应。这些停顿叠加起来，会让对话显得生硬。

Grok 语音代理完全跳过了这些转换。系统接收音频、在音频域进行推理，并由单一模型（以会话语音训练）输出音频。该架构平均可实现 0.78 秒的“首段音频到达时间”，并支持全双工通信（即代理可同时“听”和“说”），因此无需严格的轮流发言，代理即可及时响应。

搭建 Grok 语音代理环境

使用 Grok 构建语音代理需要配合 LiveKit（一款开源 WebRTC 平台）。Grok 提供会话式 AI 模型，LiveKit 则管理将用户与代理连接起来的实时音频基础设施。本节将介绍两项服务的搭建。

配置 Grok

访问 console.x.ai，并使用 X、邮箱、Google 或 Apple 进行注册。xAI 控制台在允许调用 API 之前需要预充值额度。请在“Billing（结算）”部分购买额度。

账户有额度后，前往“API Keys”并生成新的密钥。控制台仅显示一次，请立即复制并妥善保存。如果丢失，您需要重新生成并在应用中更新。若想更全面了解 xAI 的 API 生态，请参阅 Grok 3 API 教程。

配置 LiveKit

LiveKit 是用于实时音视频的 WebRTC 基础设施。它处理 Grok 与用户连接所需的音频传输层。构建语音代理时，LiveKit 负责管理对话发生的房间、在参与者间路由音频流，并提供部署基础设施。LiveKit Agents 框架对上述复杂性进行了封装，让您专注于代理行为本身，而由它处理连接管理、音频编码与轮次检测。

该框架支持多家 AI 提供商，包括 xAI。它还提供可通过网页访问的测试操练场，您可以在部署前用它验证代理。

在此注册： cloud.livekit.io。免费套餐足以支持开发与测试。通过控制台创建项目。进入 Settings，然后是 API Keys。复制三项凭据：LIVEKIT_URL（项目的 WebSocket 端点）、LIVEKIT_API_KEY（公开标识）和LIVEKIT_API_SECRET（私有认证密钥）。这些凭据用于让您的代理代码与 LiveKit Cloud 项目进行认证。

安装依赖与配置

安装所需软件包：

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

这将安装包含 xAI 插件和 OpenAI 依赖的 LiveKit Agents 框架（xAI 插件基于 OpenAI 的 Realtime API 兼容层），以及用于环境变量管理的 python-dotenv。

在项目根目录创建一个 .env 文件：

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

将占位值替换为您的实际凭据。在 Python 代码中加载这些凭据：

from dotenv import load_dotenv
 load_dotenv()

这样即可同时为 xAI 与 LiveKit 库提供凭据。将 .env 添加到 .gitignore，以避免凭据在版本控制中泄露。

构建第一个 Grok 语音代理

环境配置完成后，您可以开始构建一个可工作的语音代理。首先，在名为 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.",
 	)

您的 Agent 子类仅包含塑造代理响应方式的指令。这些类似系统提示，告诉代理扮演的角色。实际的模型配置在其他位置完成。

接下来，设置服务器与连接处理器：

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(),
 	)

@server.rtc_session() 装饰器告诉 LiveKit 在有人连接时运行您的入口函数。函数内部，AgentSession 接受模型配置，包括使用 Grok 的七种声音中的哪一种（Ara、Eve、Leo、Sal、Rex、Mika 或 Valentin）。当 session.start() 运行时，它会将您的代理连接到进行对话的 LiveKit 房间。

语音对话需要在等待音频输入和输出时不阻塞程序，因此该函数使用 async def 与 await 来并发处理这些操作。

最后，添加程序入口：

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

以开发模式运行您的代理：

uv run agent.py dev

终端将显示启动过程：工作器初始化、本地端口上的 HTTP 服务器监听，以及向 LiveKit Cloud 项目完成注册。

要测试代理，请前往您的 LiveKit Cloud 控制台 cloud.livekit.io。选择项目，然后点击侧边栏中的 Sandbox 选项卡。在模板中选择 Web Voice Agent。

模板页面会预览语音界面并展示其包含的内容。点击 Create sandbox 按钮。

在弹出的对话框中，您可以配置自定义 URL、启用摄像头与屏幕共享等能力，并调整外观设置。默认设置足以测试，点击 Create，然后 Done。

回到 Sandbox 页面，新的沙盒会出现在 Sandbox apps 下。点击 Launch 打开它。

点击 Start Call，并在提示时授予麦克风权限。留意终端中的以下日志消息，它表示代理已准备好接收音频：

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

出现该消息后，响应会很快到达。

当您询问代理无法访问的信息（例如某个城市的当前天气）时，它会解释自身限制，而不是胡编乱造。

如何为 Grok 语音代理添加工具

基础代理可以进行对话，但无法查询资料。通过工具调用，Grok 能在对话中途运行函数并口述结果。您可以使用 xAI 的内置工具，或定义自定义工具。

使用内置工具

xAI 插件包含用于通用网页查询的 WebSearch 和用于检索 X 上帖文的 XSearch。导入它们并传给 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)

tools 参数接受工具对象的列表。运行代理后，试着提问诸如 “What's the latest news about AI?” 或 “What are people saying about Grok on X?”。终端日志可能会显示关于未知 AI 函数（如 web_search_with_snippets 或 x_semantic_search）的警告，但工具仍会返回最新信息。

在使用工具时，Grok 的全双工音频特性也会更加明显。您可以在代理说话时打断它，它会停止、倾听并调整回应。这让对话比那些必须等对方说完才能插话的系统更不“机械”。

添加自定义工具

内置工具覆盖常见场景，但自定义工具可让您控制参数、错误处理以及要调用的 API。本节演示使用 Firecrawl 的搜索端点 创建自定义工具，它提供诸如 limit、lang 与 country 等过滤选项，而内置网页搜索未暴露这些能力。

在此注册： firecrawl.dev。免费套餐包含 500 点数且无需信用卡。安装 SDK 并将密钥添加到 .env：

uv add firecrawl-py

FIRECRAWL_API_KEY=fc-your-key-here

自定义工具是用 @function_tool() 装饰的方法。更新 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()

新增项包括用于装饰器的 function_tool、传递给工具函数的 RunContext，以及 Firecrawl 客户端 FirecrawlApp。由于自定义工具将取代 WebSearch，因此移除该导入。

将工具定义为代理类的方法：

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 会读取文档字符串以理解工具的用途。当您询问 “What's the current USD to EURO exchange rate?” 时，Grok 会提取查询、调用您的函数，并将结果融入回应。

使用 @function_tool() 装饰的方法会自动注册，因此从工具列表中移除 WebSearch()：

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

运行更新后的代理：

uv run search_agent.py dev

终端会显示工具执行情况：

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

在我的测试中，Firecrawl 大约在两秒内返回结果。您可以在同一代理中将多个自定义工具与内置工具结合使用。比如，客服代理可以将 XSearch 与连接内部数据库的自定义 lookup_order() 和 check_inventory() 工具配合起来。

自定义轮次检测

默认的轮次检测设置足以应对典型对话。当环境或用户行为偏离常态时，可能需要调整。嘈杂环境会导致代理对背景音作出响应；而习惯中途停顿思考的用户，可能在尚未说完时就被打断。

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,
     	),
 	),
 )

threshold 参数用于设置音频被视为语音所需的响度阈值，范围 0.0 到 1.0。在噪声环境中将该值提高到 0.7 或更高，有助于避免背景音误触发响应。

prefix_padding_ms 参数决定在检测到语音起始点前应额外保留多少音频。默认 300ms 可防止首个音节被截断。如果用户反馈开头词被切掉，可相应增大。

silence_duration_ms 参数控制代理在您停止说话后等待多久再响应。设置为 200ms 时，对话会更灵敏。提高至 400 或 500ms 则更适合中途停顿或语速较慢的用户。

对于按键说话（push-to-talk）或需要显式控制对话流的电话系统，可禁用自动轮次检测：

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

此时代理不再依赖静音来判断，而是等待程序发出的信号再进行回应。

将 Grok 语音代理部署到生产

开发模式会将代理绑定在本地机器。若要实现 24/7 运行并可随需求扩展的生产部署，可将代理托管在 LiveKit Cloud 基础设施上。

部署前准备

LiveKit CLI 会通过依赖文件识别您的项目类型。在代理目录创建 requirements.txt：

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

为生产环境密钥创建单独文件。LiveKit Cloud 会自动提供 LIVEKIT_URL、LIVEKIT_API_KEY 与 LIVEKIT_API_SECRET，因此只需包含其他 API 密钥：

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

将其保存为 .env.production，并添加到 .gitignore。

部署代理

使用您的 LiveKit Cloud 账户为 CLI 进行认证：

lk cloud auth

这会在浏览器中打开链接以将 CLI 关联到您的项目。认证完成后，部署代理：

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

CLI 会注册您的代理、生成 Dockerfile、构建容器镜像，并将其部署到 LiveKit Cloud。代理启动时，日志将流式输出到您的终端：

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

查看部署状态：

lk agent status

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

用户如何访问您的代理

部署日志中的 URL（https://your-project.livekit.cloud）是 WebSocket 后端，而不是用户界面。用户需通过一个前端连接到该后端与代理互动。

之前创建的沙盒正好可用作此用途。前往 LiveKit 控制台，打开 Sandbox 部分，复制您的沙盒 URL。该 URL 公开可访问且无需任何认证。将其分享给用户，他们即可立即与您的代理开聊。

如需品牌化体验，可在控制台中自定义沙盒外观（Logo、颜色、按钮文本），或使用 LiveKit 的 JavaScript SDK 自行构建前端。

管理部署

查看已部署代理的实时日志：

lk agent logs

修改代码后部署更新：

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

LiveKit 采用滚动部署。新实例处理新会话，旧实例会完成其活动对话，因此更新不会造成停机。

若出现问题可回滚至先前版本：

lk agent rollback

已部署的代理独立于您的本地机器运行。即使关闭终端、关机，代理仍会持续响应用户。LiveKit Cloud 负责扩缩容，流量激增时会自动启动更多实例。

部署成本

在生产环境运行 Grok 语音代理涉及两部分成本：xAI 的 API 与 LiveKit 的托管。

xAI 按语音对话每分钟 $0.05 收费。LiveKit Cloud 按代理会话时间每分钟 $0.01 收费。两者合计，当您的代理在为用户提供服务时，每分钟约 $0.06。

LiveKit 的免费层（Build 计划）每月包含 1,000 分钟的代理会话时间，无需信用卡。约合 16 小时对话，足以覆盖测试与低流量应用。付费计划从 $50/月起，包含 5,000 分钟与更高并发上限。

代理空闲时不产生成本。仅在活跃对话期间计费，因此夜间无人使用的部署不会产生 LiveKit 费用。xAI 计费同理，仅按实际 API 用量计费。在撰写本文期间的实验中，我在 xAI 上总共花费了 0.78 美元，LiveKit 由免费层覆盖。

结语

现在，您已经拥有一个能“听、想、回”的语音代理。它通过工具连接实时数据，可根据不同环境调整倾听行为，并运行在无需人工干预即可扩展的基础设施上。

这里介绍的代码模式同样适用于其他场景。将“研究助理”指令替换为客服指南，添加查询订单数据库的工具；构建能搜索例句的语言导师；为您现有的 API 创建语音接口。

xAI 计划推出独立的文本转语音与语音转文本端点，届时可构建将 Grok 语音能力与其他语言模型混合的混合架构。当前，语音代理 API 已可覆盖整条处理链。

参阅 LiveKit Agents 文档了解更多功能，如多代理交接与会话持久化；另见 xAI 文档以深入了解音频格式与企业特性。