如何使用带天气工具的 LiveKit 语音代理?
语音代理(Voice Agent)是一种你可以实时对话的 AI 程序:你说话,它先把语音识别成文字(STT,speech-to-text),再把文字交给大语言模型(LLM),最后把答案转成语音播放给你听(TTS,text-to-speech)。LiveKit 是一个开源框架,把这三个部件通过网络串在一起,所以你的代理可以跑在服务器上,接受来自浏览器或电话的通话。
本笔记带你跑起一个精简但完整的语音代理 Python 程序。代理会先问候你、可以告诉你天气(示例工具)。
你需要准备什么
- 一台 Mac(同样步骤也适用于 Windows 和 Linux)。
- 已安装 Homebrew 以及
uv包管理器——若尚未安装uv,执行brew install uv。 - 一个 LiveKit Cloud 账号(免费的 Build 计划就够)。
- LiveKit Cloud 的 API 凭证,复制到一个名为
.env的文件——见下方步骤。
设置 LiveKit Cloud
到 cloud.livekit.io 注册账号。在控制台点 Projects → Create Project,打开项目后到 Keys 页面,复制三个值:
LIVEKIT_URL— 格式像wss://your-project.livekit.cloud。LIVEKIT_API_KEY— 短字符串,例如APIxxxxxxxxxxxxx。LIVEKIT_API_SECRET— 较长的字符串,只显示一次。
在你的项目文件夹里建立一个名为 .env 的文件,内容如下:
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxxxxxxx
LIVEKIT_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
注意:千万不要把 .env 放上 GitHub 或任何公开网站——里面有真实凭证。
在自己电脑上运行
下载 zip 文件,解压到一个文件夹里。zip 里包含程序和 pyproject.toml 项目配置文件。把你的 .env 凭证文件放到同一文件夹(如上面「设置 LiveKit Cloud」步骤所示)。然后在 Visual Studio Code 里打开这个文件夹,在终端逐条输入以下两行:
uv sync
uv run main.py console
uv sync 读取 pyproject.toml,如果你的电脑还没有 Python 3.13,它会自动下载安装,然后装好所有依赖包。uv run main.py console 会在终端启动代理,让你直接说话、并听到代理的回答。你只需要跑一次 uv sync——只有在修改了 main.py 或依赖包之后才需要重新跑。
程序文件
zip 里包含两个文件:pyproject.toml 和 main.py。下面是它们的完整内容供参考。
pyproject.toml
[project]
name = "folder-ai-livekit-agent"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
"livekit-agents>=1.8.4,<2",
"python-dotenv",
"requests",
]
[build-system]
requires = ["uv_build>=0.13.6,<0.14.0"]
build-backend = "uv_build"
main.py
from dotenv import load_dotenv
from livekit.agents import (
Agent,
AgentServer,
AgentSession,
JobContext,
RunContext,
cli,
function_tool,
inference,
)
load_dotenv()
@function_tool
async def lookup_weather(
context: RunContext,
location: str,
):
"""Used to look up weather information."""
return {"weather": "sunny", "temperature": 70}
server = AgentServer()
@server.rtc_session()
async def entrypoint(ctx: JobContext):
session = AgentSession(
vad=inference.VAD(),
stt=inference.STT("deepgram/nova-3", language="multi"),
llm=inference.LLM("google/gemma-4-31b-it"),
tts=inference.TTS("cartesia/sonic-3", voice="9626c31c-bec5-4cca-baa8-f8ba9e84c8bc"),
)
agent = Agent(
instructions="You are a friendly voice assistant built by LiveKit.",
tools=[lookup_weather],
)
await session.start(agent=agent, room=ctx.room)
await session.generate_reply(instructions="greet the user and ask about their day")
if __name__ == "__main__":
cli.run_app(server)
main.py 的运作原理(白话版)
STT、LLM、TTS。AgentSession 那行把三个部件串起来:Deepgram(deepgram/nova-3)把语音转文字,Google Gemma 4(google/gemma-4-31b-it)回答问题,Cartesia(cartesia/sonic-3)把答案念出来。三者都跑在 LiveKit Cloud 上,所以你不用分别向三家模型商申请 key——一个 LiveKit 账号就搞定。
工具函数。lookup_weather 函数前的 @function_tool 告诉 LLM:「用户问天气时可以调用这个函数」。目前它只会硬编码回答 "sunny", 70°F;真正的代理应该去调用 Open-Meteo 之类的天气 API。
主动问候。会话开始后,generate_reply(instructions="greet the user and ask about their day") 会让代理先说一句话,所以打电话进来的人听到的是问候,而不是沉默。
跟你的代理对话
让 uv run main.py console 在终端执行中,程序会请求 Mac 的麦克风权限——按 Allow。然后对着麦克风说话:你应该会听到代理回你问候,接着就可以自由对话。想停止时按 Ctrl+C。
如果终端一直没反应,或显示缺少凭证的错误信息,按 Ctrl+C 停止,检查 .env 是否在项目文件夹,再执行一次 uv run main.py console。
局限
- 需要 LiveKit Cloud 账号和正确的
.env凭证。没有它们程序不会启动。 - 免费 Build 计划的限制(截至撰写本 AI 笔记之时):每月 1,000 分钟通话、$2.50 LiveKit Inference 额度(约 50 分钟通话)、以及冷启动——闲置一阵子后第一次通话可能要等几秒才回应。付费计划每月 $50 起。
- 示例天气工具是假的。永远回
sunny和70°F。要让代理能真正查天气,请改写成调用真实的 API。
延伸阅读
- livekit.io — LiveKit 官方首页,含定价与文档。
- livekit/agents — LiveKit Agents Python 示例仓库。
- LiveKit Cloud Agents 文档 — 构建与部署代理的官方指南。
- 如何在 macOS 安装 Homebrew 包管理器? — 若尚未安装
uv,用这篇的一条命令就能装好。 - 如何用检索增强生成(RAG)在没有幻觉的情况下回答问题? — 语音代理的 LLM 同样会幻觉;RAG 就是解决方案。