English 繁體中文 简体中文

如何使用带天气工具的 LiveKit 语音代理?

林邦源 · AI 笔记 · 2026年11月4日 · 阅读时间约 6 分钟

语音代理(Voice Agent)是一种你可以实时对话的 AI 程序:你说话,它先把语音识别成文字(STT,speech-to-text),再把文字交给大语言模型(LLM),最后把答案转成语音播放给你听(TTS,text-to-speech)。LiveKit 是一个开源框架,把这三个部件通过网络串在一起,所以你的代理可以跑在服务器上,接受来自浏览器或电话的通话。

本笔记带你跑起一个精简但完整的语音代理 Python 程序。代理会先问候你、可以告诉你天气(示例工具)。

你需要准备什么

设置 LiveKit Cloud

到 cloud.livekit.io 注册账号。在控制台点 Projects → Create Project,打开项目后到 Keys 页面,复制三个值:

在你的项目文件夹里建立一个名为 .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。

局限

延伸阅读