如何使用帶天氣工具的 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 就是解決方案。