livekit-agents by livekit/agent-skills
npx skills add https://github.com/livekit/agent-skills --skill livekit-agents本技能为使用 LiveKit Cloud 构建语音 AI 智能体提供了有主见的指导。它假定您正在使用 LiveKit Cloud(推荐路径),并阐述了如何着手智能体开发,而非具体的 API 细节。所有关于 API、方法和配置的事实信息都必须来自实时文档。
本技能适用于 LiveKit Cloud 开发者。 如果您是自托管 LiveKit,部分建议(特别是关于 LiveKit Inference 的)将不直接适用。
在编写任何代码之前,请完成此清单:
LIVEKIT_URL、LIVEKIT_API_KEY 和 LIVEKIT_API_SECRET无论 MCP 是否可用,此清单都适用。MCP 提供文档访问,但不能替代本技能中的指导。
LiveKit Cloud 是运行语音智能体的最快方式。它提供:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
LIVEKIT_URL - 您项目的 WebSocket URL(例如,wss://your-project.livekit.cloud)LIVEKIT_API_KEY - 用于身份验证的 API 密钥LIVEKIT_API_SECRET - 用于身份验证的 API 密钥.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 是 LiveKit Cloud 使用 AI 模型的推荐方式。 它提供对领先 AI 模型供应商的访问——全部通过您的 LiveKit 凭证完成,无需单独的 API 密钥。
LiveKit Inference 的优势:
请查阅文档以了解可用模型、支持的供应商和当前的使用模式。文档始终包含最新的信息。
LiveKit Agents 是一个快速发展的 SDK。模型训练数据在创建的那一刻就已经过时了。在使用 LiveKit 时:
即使对某个 API 很有信心,此规则也适用。无论如何都要验证。
在编写任何 LiveKit 代码之前,请确保可以访问 LiveKit 文档 MCP 服务器。这提供了当前、经过验证的 API 信息,并防止依赖过时的模型知识。
查找 livekit-docs MCP 工具。如果可用,请使用它们进行所有文档查找:
如果 LiveKit MCP 服务器未配置,请告知用户并建议安装。所有支持平台的安装说明可在以下位置找到:
从该页面获取适用于用户编码代理的安装说明。
如果无法在当前会话中安装 MCP:
# UNVERIFIED: Please check docs.livekit.io for current API语音 AI 智能体具有与基于文本的智能体或传统软件根本不同的要求。请内化这些原则:
语音对话是实时的。用户期望在几百毫秒内得到响应,而不是几秒钟。每个架构决策都应考虑延迟影响:
庞大的系统提示和大量的工具列表会直接增加延迟。一个拥有 50 个工具和 10,000 个令牌系统提示的语音智能体,无论模型速度多快,都会感觉迟钝。
以最小可行上下文设计智能体:
语音界面约束与文本不同:
复杂的语音智能体不应是单一的整体。LiveKit Agents 支持结构化工作流,在保持低延迟的同时处理复杂的用例。
一个处理整个对话流程的单一智能体会积累:
这会造成延迟并降低可靠性。
移交允许一个智能体将控制权转移给另一个。使用移交来:
围绕自然的对话边界设计移交,在这些边界处上下文可以被总结,而不是整体转移。
任务是范围严格限定的提示,旨在实现特定结果。使用任务来处理:
请查阅文档以获取关于移交和任务的实现细节。
语音智能体行为就是代码。每个智能体实现必须包含测试。交付没有测试的智能体就是交付未经测试的代码。
在构建或修改 LiveKit 智能体时:
tests/ 目录(如果不存在)当修改智能体行为——指令、工具描述、工作流时——首先为期望的行为编写测试:
这种方法可以防止交付那些"似乎能工作"但在生产环境中失败的智能体。
至少,为以下内容编写测试:
测试应关注:
使用 LiveKit 的测试框架。通过 MCP 查阅测试文档以获取当前模式:
search: "livekit agents testing"
该框架支持:
在手动测试中"似乎能工作"的智能体在生产中经常失败:
测试能在用户发现问题之前捕捉到这些问题。
如果用户明确要求不编写测试,可以继续但不编写测试,但要告知他们:
"我已按您的要求构建了没有测试的智能体。我强烈建议在部署到生产环境前添加测试。语音智能体难以手动验证,测试可以防止无声的回归。"
从一个"无所不能"的智能体开始,然后随着时间的推移添加工具/指令。相反,即使初始实现很简单,也应预先设计工作流结构。
延迟问题会累积。一个在开发中感觉"有点慢"的智能体,在真实网络条件下的生产环境中会变得无法使用。持续测量和优化延迟。
文档中的示例展示了特定的模式。不理解其目的就复制代码会导致臃肿、结构不良的智能体。在包含每个组件之前,先理解它的作用。
智能体行为就是代码。提示更改对行为的影响与代码更改一样大。以与传统软件相同的严谨性测试智能体行为。切勿交付没有至少一个测试文件的智能体实现。
重申关键规则:切勿信任模型记忆中的 LiveKit API。SDK 的演变速度超过了模型训练周期。验证一切。
始终查阅文档以获取:
本技能提供以下方面的指导:
这种区别很重要:本技能告诉您如何思考构建语音智能体。文档告诉您如何实现特定功能。
通过 MCP 使用 LiveKit 文档时,请注意任何空白、过时信息或令人困惑的内容。报告文档问题有助于改善所有开发者的生态系统。
使用 LiveKit Cloud 构建有效的语音智能体需要:
无论 SDK 版本或 API 如何变化,这些原则仍然有效。对于所有具体的实现细节,请通过 MCP 查阅 LiveKit 文档。
每周安装数
843
代码仓库
GitHub 星标数
34
首次出现
2026年2月9日
安全审计
安装于
codex830
opencode826
github-copilot824
gemini-cli820
kimi-cli816
amp814
This skill provides opinionated guidance for building voice AI agents with LiveKit Cloud. It assumes you are using LiveKit Cloud (the recommended path) and encodes how to approach agent development, not API specifics. All factual information about APIs, methods, and configurations must come from live documentation.
This skill is for LiveKit Cloud developers. If you're self-hosting LiveKit, some recommendations (particularly around LiveKit Inference) won't apply directly.
Before writing ANY code, complete this checklist:
LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET from your Cloud projectThis checklist applies regardless of whether MCP is available. MCP provides documentation access but does NOT replace the guidance in this skill.
LiveKit Cloud is the fastest way to get a voice agent running. It provides:
Sign up at cloud.livekit.io if you haven't already
Create a project (or use an existing one)
Get your credentials from the project settings:
LIVEKIT_URL - Your project's WebSocket URL (e.g., wss://your-project.livekit.cloud)LIVEKIT_API_KEY - API key for authenticationLIVEKIT_API_SECRET - API secret for authenticationSet these as environment variables (typically in .env.local):
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret
The LiveKit CLI can automate credential setup. Consult the CLI documentation for current commands.
LiveKit Inference is the recommended way to use AI models with LiveKit Cloud. It provides access to leading AI model providers—all through your LiveKit credentials with no separate API keys needed.
Benefits of LiveKit Inference:
Consult the documentation for available models, supported providers, and current usage patterns. The documentation always has the most up-to-date information.
LiveKit Agents is a fast-evolving SDK. Model training data is outdated the moment it's created. When working with LiveKit:
This rule applies even when confident about an API. Verify anyway.
Before writing any LiveKit code, ensure access to the LiveKit documentation MCP server. This provides current, verified API information and prevents reliance on stale model knowledge.
Look for livekit-docs MCP tools. If available, use them for all documentation lookups:
If the LiveKit MCP server is not configured, inform the user and recommend installation. Installation instructions for all supported platforms are available at:
https://docs.livekit.io/intro/mcp-server/
Fetch the installation instructions appropriate for the user's coding agent from that page.
If MCP cannot be installed in the current session:
# UNVERIFIED: Please check docs.livekit.io for current APIVoice AI agents have fundamentally different requirements than text-based agents or traditional software. Internalize these principles:
Voice conversations are real-time. Users expect responses within hundreds of milliseconds, not seconds. Every architectural decision should consider latency impact:
Large system prompts and extensive tool lists directly increase latency. A voice agent with 50 tools and a 10,000-token system prompt will feel sluggish regardless of model speed.
Design agents with minimal viable context:
Voice interface constraints differ from text:
Complex voice agents should not be monolithic. LiveKit Agents supports structured workflows that maintain low latency while handling sophisticated use cases.
A single agent handling an entire conversation flow accumulates:
This creates latency and reduces reliability.
Handoffs allow one agent to transfer control to another. Use handoffs to:
Design handoffs around natural conversation boundaries where context can be summarized rather than transferred wholesale.
Tasks are tightly-scoped prompts designed to achieve a specific outcome. Use tasks for:
Consult the documentation for implementation details on handoffs and tasks.
Voice agent behavior is code. Every agent implementation MUST include tests. Shipping an agent without tests is shipping untested code.
When building or modifying a LiveKit agent:
tests/ directory if one doesn't existWhen modifying agent behavior—instructions, tool descriptions, workflows—begin by writing tests for the desired behavior:
This approach prevents shipping agents that "seem to work" but fail in production.
At minimum, write tests for:
Focus tests on:
Use LiveKit's testing framework. Consult the testing documentation via MCP for current patterns:
search: "livekit agents testing"
The framework supports:
Agents that "seem to work" in manual testing frequently fail in production:
Tests catch these issues before users do.
If a user explicitly requests no tests, proceed without them but inform them:
"I've built the agent without tests as requested. I strongly recommend adding tests before deploying to production. Voice agents are difficult to verify manually and tests prevent silent regressions."
Starting with one agent that "does everything" and adding tools/instructions over time. Instead, design workflow structure upfront, even if initial implementation is simple.
Latency issues compound. An agent that feels "a bit slow" in development becomes unusable in production with real network conditions. Measure and optimize latency continuously.
Examples in documentation demonstrate specific patterns. Copying code without understanding its purpose leads to bloated, poorly-structured agents. Understand what each component does before including it.
Agent behavior is code. Prompt changes affect behavior as much as code changes. Test agent behavior with the same rigor as traditional software. Never deliver an agent implementation without at least one test file.
Reiterating the critical rule: never trust model memory for LiveKit APIs. The SDK evolves faster than model training cycles. Verify everything.
Always consult documentation for:
This skill provides guidance on:
The distinction matters: this skill tells you how to think about building voice agents. The documentation tells you how to implement specific features.
When using LiveKit documentation via MCP, note any gaps, outdated information, or confusing content. Reporting documentation issues helps improve the ecosystem for all developers.
Building effective voice agents with LiveKit Cloud requires:
These principles remain valid regardless of SDK version or API changes. For all implementation specifics, consult the LiveKit documentation via MCP.
Weekly Installs
843
Repository
GitHub Stars
34
First Seen
Feb 9, 2026
Security Audits
Gen Agent Trust HubPassSocketWarnSnykPass
Installed on
codex830
opencode826
github-copilot824
gemini-cli820
kimi-cli816
amp814
Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU
59,200 周安装