livekit-agents

LiveKit Cloud 的 LiveKit Agents 開發

此技能提供使用 LiveKit Cloud 建構語音 AI 代理的明確指引。它假設您使用 LiveKit Cloud（建議路徑），並編碼了如何進行代理開發，而非 API 細節。所有關於 API、方法和組態的事實資訊必須來自即時文件。

此技能適用於 LiveKit Cloud 開發者。 如果您自行託管 LiveKit，部分建議（特別是關於 LiveKit Inference）將不直接適用。

必讀：開始前的檢查清單

在撰寫任何程式碼之前，請完成此檢查清單：

1. 閱讀整份技能文件 - 即使 MCP 可用，也不要跳過任何章節
2. 確保 LiveKit Cloud 專案已連線 - 您需要來自 Cloud 專案的 LIVEKIT_URL、LIVEKIT_API_KEY 和 LIVEKIT_API_SECRET
3. 設定文件存取 - 如果可用，使用 MCP；否則使用網路搜尋
4. 規劃撰寫測試 - 每個代理實作都必須包含測試（請參閱下方測試章節）
5. 對照即時文件驗證所有 API - 切勿依賴模型記憶體來取得 LiveKit API

無論 MCP 是否可用，此檢查清單皆適用。MCP 提供文件存取，但不會取代此技能的指引。

LiveKit Cloud 設定

LiveKit Cloud 是讓語音代理快速上線的最快方式。它提供：

• 受管基礎設施（無需部署伺服器）
• LiveKit Inference 用於 AI 模型（無需額外 API 金鑰）
• 內建噪音消除、語音偵測及其他語音功能
• 簡單的憑證管理

連線至您的 Cloud 專案

1. 前往 cloud.livekit.io 註冊（如果您尚未註冊）

2. 建立一個專案（或使用現有專案）

3. 從專案設定中取得您的憑證：

   • LIVEKIT_URL - 您專案的 WebSocket URL（例如 wss://your-project.livekit.cloud）
   • LIVEKIT_API_KEY - 用於驗證的 API 金鑰
   • LIVEKIT_API_SECRET - 用於驗證的 API 密鑰

4. 將這些設定為環境變數（通常在 .env.local 中）：

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret

LiveKit CLI 可以自動化憑證設定。請查閱 CLI 文件以取得最新指令。

使用 LiveKit Inference 處理 AI 模型

LiveKit Inference 是在 LiveKit Cloud 中使用 AI 模型的建議方式。 它提供對領先 AI 模型提供者的存取——全部透過您的 LiveKit 憑證，無需額外 API 金鑰。

LiveKit Inference 的優點：

• 無需為每個 AI 提供者管理單獨的 API 金鑰
• 帳單整合至您的 LiveKit Cloud 帳戶
• 針對語音 AI 工作負載最佳化

請查閱文件以了解可用模型、支援的提供者及目前的使用模式。文件始終提供最新的資訊。

關鍵規則：切勿信任模型記憶體中的 LiveKit API

LiveKit Agents 是一個快速演進的 SDK。模型訓練資料在建立的瞬間就已過時。使用 LiveKit 時：

• 切勿假設 API 簽章、方法名稱或組態選項來自記憶體
• 切勿猜測 SDK 行為或預設值
• 務必對照即時文件驗證後再撰寫程式碼
• 務必引用實作功能時的文件來源

即使您對某個 API 很有信心，此規則仍然適用。無論如何都要驗證。

必要：使用 LiveKit MCP 伺服器取得文件

在撰寫任何 LiveKit 程式碼之前，請確保可以存取 LiveKit 文件 MCP 伺服器。這能提供最新、經過驗證的 API 資訊，並避免依賴過時的模型知識。

檢查 MCP 是否可用

尋找 livekit-docs MCP 工具。如果可用，請使用它們進行所有文件查詢：

• 在實作任何功能前搜尋文件
• 驗證 API 簽章和方法參數
• 查詢組態選項及其有效值
• 尋找特定任務的可用範例

如果 MCP 不可用

如果 LiveKit MCP 伺服器未設定，請通知使用者並建議安裝。所有支援平台的安裝說明可在以下位置取得：

https://docs.livekit.io/intro/mcp-server/

從該頁面取得適合使用者程式碼代理的安裝說明。

MCP 不可用時的備案

如果無法在目前工作階段安裝 MCP：

1. 立即通知使用者無法即時驗證文件
2. 使用網路搜尋從 docs.livekit.io 取得最新文件
3. 明確標記所有 LiveKit 特定程式碼，加上類似 # UNVERIFIED: Please check docs.livekit.io for current API 的註解
4. 清楚說明何時無法驗證某件事：「我無法對照目前文件驗證此 API 簽章」
5. 建議使用者在使用程式碼前，先至 https://docs.livekit.io 驗證

語音代理架構原則

語音 AI 代理與基於文字的代理或傳統軟體有根本不同的需求。請內化這些原則：

延遲至關重要

語音對話是即時的。使用者期望在數百毫秒內得到回應，而非數秒。每個架構決策都應考慮延遲影響：

• 最小化 LLM 上下文大小以減少推論時間
• 避免在活躍對話中進行不必要的工具呼叫
• 偏好串流回應而非批次回應
• 為非預期路徑（網路延遲、API 逾時）做設計

上下文膨脹會扼殺效能

大型系統提示和大量的工具清單會直接增加延遲。一個有 50 個工具和 10,000 個 token 系統提示的語音代理，無論模型速度多快，都會感覺遲緩。

以最小可行上下文設計代理：

• 僅包含與當前對話階段相關的工具
• 保持系統提示簡潔且重點明確
• 移除非當前需要的工具和上下文

使用者不閱讀，他們聆聽

語音介面的限制與文字不同：

• 長回應會讓使用者感到困擾——保持輸出簡潔
• 使用者無法向上捲動——確保第一次傳達就清楚
• 中斷是正常的——設計優雅的處理方式
• 沉默感覺像故障——必要時告知正在處理

工作流程架構：轉接與任務

複雜的語音代理不應是單體式的。LiveKit Agents 支援結構化的工作流程，能在處理複雜使用案例的同時保持低延遲。

單體式代理的問題

單一代理處理整個對話流程會累積：

• 每個可能動作的工具（工具清單膨脹）
• 每個對話階段的指令（上下文膨脹）
• 所有情境的狀態管理（複雜度）

這會造成延遲並降低可靠性。

轉接：代理之間的轉移

轉接允許一個代理將控制權轉移給另一個代理。使用轉接來：

• 區分不同的對話階段（問候 → 資訊收集 → 解決問題）
• 隔離專業能力（一般支援 → 帳務專員）
• 管理上下文邊界（每個代理只擁有它需要的內容）

圍繞自然的對話邊界設計轉接，在這些邊界處可以總結上下文，而非整體轉移。

任務：範圍限定的操作

任務是範圍緊湊的提示，旨在達成特定結果。使用任務來：

• 處理不需要完整代理能力的離散操作
• 在專注提示優於通用代理的情境
• 在只需要特定能力時減少上下文

請查閱文件以了解轉接和任務的實作細節。

必要：為代理行為撰寫測試

語音代理的行為就是程式碼。每個代理實作都必須包含測試。未經測試就交付代理，等同於交付未經測試的程式碼。

強制性測試工作流程

在建構或修改 LiveKit 代理時：

1. 建立 tests/ 目錄（如果尚未存在）
2. 在認為實作完成前，至少撰寫一個測試
3. 測試使用者要求的核心行為
4. 執行測試以確認它們通過

測試驅動開發流程

修改代理行為（指令、工具描述、工作流程）時，從為期望行為撰寫測試開始：

1. 定義代理在特定情境下應有的行為
2. 撰寫驗證此行為的測試案例
3. 實作功能
4. 迭代直到測試通過

這種方法可以避免交付「看似正常」但在生產環境中失敗的代理。

每個代理測試應涵蓋的內容

至少撰寫測試來驗證：

• 基本對話流程：代理能適當回應問候
• 工具呼叫（如果有工具）：工具以正確參數被呼叫
• 錯誤處理：代理能優雅處理非預期輸入

測試重點應放在：

• 工具呼叫：代理是否以正確參數呼叫正確的工具？
• 回應品質：代理是否針對給定輸入產生適當的回應？
• 工作流程轉換：轉接和任務是否正確觸發？
• 邊界情況：代理如何處理非預期輸入、中斷、沉默？

測試實作模式

使用 LiveKit 的測試框架。透過 MCP 查閱測試文件以取得最新模式：

search: "livekit agents testing"

該框架支援：

• 模擬使用者輸入
• 驗證代理回應
• 工具呼叫斷言
• 工作流程轉換測試

為什麼這是不可妥協的

在人工測試中「看似正常」的代理經常在生產環境中失敗：

• 提示變更會默默破壞行為
• 工具描述會影響工具被呼叫的時機
• 模型更新會改變回應模式

測試能在使用者發現問題之前捕捉到這些問題。

跳過測試

如果使用者明確要求不寫測試，則可以進行但不寫測試，但請告知他們：

「我已按照要求建立不包含測試的代理。我強烈建議在部署到生產環境前加入測試。語音代理難以手動驗證，測試可以防止無聲的退化。」

應避免的常見錯誤

初始代理過載

從一個「什麼都做」的代理開始，然後隨著時間加入工具/指令。相反地，應預先設計工作流程結構，即使初始實作很簡單。

忽略延遲直到問題發生

延遲問題會累積。在開發階段感覺「有點慢」的代理，在真實網路條件下的生產環境中會變得無法使用。持續測量和最佳化延遲。

未經理解就複製範例

文件中的範例展示特定模式。未經理解就複製程式碼會導致代理膨脹且結構不良。在包含任何元件之前，先了解每個元件的用途。

因為「只是提示」而跳過測試

代理行為就是程式碼。提示變更對行為的影響與程式碼變更一樣大。以與傳統軟體相同的嚴謹度測試代理行為。切勿在沒有至少一個測試檔案的情況下交付代理實作。

假設模型知識是最新的

重申關鍵規則：切勿信任模型記憶體中的 LiveKit API。SDK 的演進速度快於模型訓練週期。驗證所有事項。

何時查閱文件

務必查閱文件以取得：

• API 方法簽章和參數
• 組態選項及其有效值
• SDK 版本特定功能或變更
• 部署和基礎設施設定
• 模型提供者整合細節
• CLI 指令和旗標

此技能提供以下指引：

• 架構方法和設計原則
• 工作流程結構決策
• 測試策略
• 應避免的常見陷阱

區別很重要：此技能告訴您如何思考建構語音代理。文件告訴您如何實作特定功能。

回饋迴圈

透過 MCP 使用 LiveKit 文件時，請注意任何遺漏、過時資訊或令人困惑的內容。回報文件問題有助於改善所有開發者的生態系統。

總結

使用 LiveKit Cloud 建構有效的語音代理需要：

1. 以 LiveKit Cloud + LiveKit Inference 為基礎——這是通往生產環境的最快路徑
2. 對照即時文件驗證所有事項——切勿信任模型記憶體
3. 在每個架構決策點最小化延遲
4. 使用轉接和任務結構化工作流程以管理複雜度
5. 在變更前後測試行為——切勿在沒有測試的情況下交付
6. 保持上下文最小化——只包含當前階段需要的內容

無論 SDK 版本或 API 如何變更，這些原則仍然有效。所有實作細節請透過 MCP 查閱 LiveKit 文件。