LiveKit Agents for Node.js

Agent 框架旨在构建运行在服务器上的实时可编程参与者。使用它来创建能够看见、听见并理解的对话式多模态语音助手。

这是 LiveKit Agents 框架 的 Node.js 版本，最初是用 Python 编写的。

✨ 1.0 发布 ✨

本 README 反映的是 1.0 版本。如果您正尝试从 0.x 升级，请参阅迁移指南。

特性

• 灵活的集成：一个全面的生态系统，可以根据您的用例自由组合合适的 STT、LLM、TTS 和实时 API。
• 丰富的 WebRTC 客户端：使用 LiveKit 的开源 SDK 生态系统构建客户端应用，支持所有主流平台。
• 与客户端交换数据：使用 RPC 和其他 数据 API 与客户端无缝交换数据。
• 语义轮次检测：采用 Transformer 模型检测用户何时结束发言，有助于减少打断。
• 开源：完全开源，允许您在自己的服务器上运行整个堆栈，包括 LiveKit 服务器，这是最常用的 WebRTC 媒体服务器之一。

安装

该框架包含多种插件，便于处理流式输入或生成输出。例如，有用于文本转语音或与流行 LLM 进行推理的插件。

• 如果尚未安装 pnpm，请先安装：

npm install -g pnpm

要安装核心 Agents 库以及插件，请运行：

pnpm install @livekit/agents

目前仅支持以下插件：

插件	功能
@livekit/agents-plugin-openai	LLM、TTS、STT
@livekit/agents-plugin-google	LLM、TTS
@livekit/agents-plugin-deepgram	STT、TTS
@livekit/agents-plugin-elevenlabs	TTS
@livekit/agents-plugin-cartesia	TTS
@livekit/agents-plugin-neuphonic	TTS
@livekit/agents-plugin-resemble	TTS
@livekit/agents-plugin-rime	TTS
@livekit/agents-plugin-inworld	TTS
@livekit/agents-plugin-silero	VAD
@livekit/agents-plugin-livekit	EOU
@livekit/agents-plugin-anam	阿凡达
@livekit/agents-plugin-bey	阿凡达
@livekit/agents-plugin-lemonslice	阿凡达
@livekit/agents-plugin-xai	LLM、TTS
@livekit/agents-plugin-phonic	实时

文档和指南

关于框架及其使用方法的文档可以在这里找到：https://docs.livekit.io/agents/

推荐的入门应用

使用 LiveKit Agents Node.js 入门项目快速启动完整的语音 AI 流程（LLM、STT、TTS）：

• livekit-examples/agent-starter-node

它包含一个现成的助手、多语言轮次检测、背景噪声消除、指标/日志记录，以及一个生产就绪的 Dockerfile。您可以快速开始，然后根据自己的偏好选择模型和插件进行定制。

核心概念

• Agent：基于 LLM 的应用程序，具有明确的指令。
• AgentSession：用于管理与最终用户交互的代理容器。
• entrypoint：交互会话的起点，类似于 Web 服务器中的请求处理器。
• Worker：负责协调作业调度并为用户会话启动代理的主要进程。

使用方法

请查看快速入门指南

简单的语音代理

---

import {
  type JobContext,
  type JobProcess,
  WorkerOptions,
  cli,
  defineAgent,
  llm,
  voice,
  inference,
} from '@livekit/agents';
import * as silero from '@livekit/agents-plugin-silero';
import { fileURLToPath } from 'node:url';
import { z } from 'zod';

const lookupWeather = llm.tool({
  description: '用于查询天气信息。',
  parameters: z.object({
    location: z.string().describe('要查询天气信息的位置'),
  }),
  execute: async ({ location }, { ctx }) => {
    return { weather: 'sunny', temperature: 70 };
  },
});

export default defineAgent({
  prewarm: async (proc: JobProcess) => {
    proc.userData.vad = await silero.VAD.load();
  },
  entry: async (ctx: JobContext) => {
    const agent = new voice.Agent({
      instructions: '你是由 LiveKit 构建的友好语音助手。',
      tools: { lookupWeather },
    });

    const session = new voice.AgentSession({
      // 语音转文本（STT）是代理的“耳朵”，将用户的语音转换为 LLM 可以理解的文本
      // 可用模型请参见 https://docs.livekit.io/agents/models/stt/
      stt: new inference.STT({ model: 'deepgram/nova-3', language: 'en' }),
      // 大型语言模型（LLM）是代理的“大脑”，处理用户输入并生成响应
      // 可用模型请参见 https://docs.livekit.io/agents/models/llm/
      llm: new inference.LLM({ model: 'openai/gpt-4.1-mini' }),
      // 文本转语音（TTS）是代理的“声音”，将 LLM 的文本转换为用户可以听到的语音
      // 可用模型及语音选项请参见 https://docs.livekit.io/agents/models/tts/
      tts: new inference.TTS({ model: 'cartesia/sonic-3', voice: '9626c31c-bec5-4cca-baa8-f8ba9e84c8bc' }),
      // VAD 和发言轮次检测用于判断用户何时在说话以及代理何时应该回应
      // 更多信息请参见 https://docs.livekit.io/agents/build/turns
      vad: ctx.proc.userData.vad! as silero.VAD,
      turnDetection: new livekit.turnDetector.MultilingualModel(),
      // 若要使用实时模型，可将 STT、LLM、TTS 和 VAD 替换为以下内容：
      // llm: new openai.realtime.RealtimeModel(),
    });

    await session.start({
      agent,
      room: ctx.room,
    });

    await session.generateReply({
      instructions: '问候用户并询问他们今天过得如何',
    });
  },
});

cli.runApp(new WorkerOptions({ agent: fileURLToPath(import.meta.url) }));

此示例无需任何第三方 API 密钥。它通过 LiveKit 推理网关 即可开箱即用。

多代理交接

---

此代码片段已简化。完整示例请参阅 multi_agent.ts

type StoryData = {
  name?: string;
  location?: string;
};

class IntroAgent extends voice.Agent<StoryData> {
  constructor() {
    super({
      instructions: `你是一名说书人。你的目标是从用户那里收集一些信息，使故事更加个性化和引人入胜。请向用户询问他们的姓名和来自哪里。`,
      tools: {
        informationGathered: llm.tool({
          description:
            '当用户提供了使故事个性化和引人入胜所需的信息时调用。',
          parameters: z.object({
            name: z.string().describe('用户的姓名'),
            location: z.string().describe('用户的所在地'),
          }),
          execute: async ({ name, location }, { ctx }) => {
            ctx.userData.name = name;
            ctx.userData.location = location;

            return llm.handoff({
              agent: new StoryAgent(name, location),
              returns: "让我们开始讲故事吧！",
            });
          },
        }),
      },
    });
  }

  // 使用继承创建带有自定义钩子的代理
  async onEnter() {
    this.session.generateReply({
      instructions: '"问候用户并收集信息"',
    });
  }
}

class StoryAgent extends voice.Agent<StoryData> {
  constructor(name: string, location: string) {
    super({
      instructions: `你是一名说书人。请利用用户的提供的信息使故事更具个性化。
        用户的名字是 ${name}, 来自 ${location}`,
    });
  }

  async onEnter() {
    this.session.generateReply();
  }
}

export default defineAgent({
  prewarm: async (proc: JobProcess) => {
    proc.userData.vad = await silero.VAD.load();
  },
  entry: async (ctx: JobContext) => {
    await ctx.connect();
    const participant = await ctx.waitForParticipant();
    console.log('参与者加入：', participant.identity);

    const userdata: StoryData = {};

    const session = new voice.AgentSession({
      vad: ctx.proc.userData.vad! as silero.VAD,
      stt: new inference.STT({ model: 'deepgram/nova-3', language: 'en' }),
      llm: new inference.LLM({ model: 'openai/gpt-4.1-mini' }),
      tts: new inference.TTS({ model: 'cartesia/sonic-3', voice: '9626c31c-bec5-4cca-baa8-f8ba9e84c8bc' }),
      userData: userdata,
    });

    await session.start({
      agent: new IntroAgent(),
      room: ctx.room,
    });
  },
});

运行您的代理

该框架提供了一个 CLI 界面来运行您的代理。要开始使用，您需要设置以下环境变量：

• LIVEKIT_URL
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET
• 任何其他提供商的 API 密钥（例如 OPENAI_API_KEY）

以下命令将启动工作进程，并等待用户连接到您的 LiveKit 服务器：

pnpm run build && node ./examples/src/restaurant_agent.ts dev

使用 Playground 构建代理 UI

为了简化代理的构建和测试过程，我们开发了一个多功能的 Web 前端工具“Playground”。您可以根据自己的需求使用或修改此应用，它也可以作为完全自定义代理应用程序的起点。

• 托管的 Playground
• 源代码
• Playground 文档

生产环境运行

pnpm run build && node ./examples/src/restaurant_agent.ts start

此命令将以生产就绪的优化方式运行代理。

常见问题解答

运行我的代理时会发生什么？

按照上述步骤运行代理后，会启动一个工作进程，该进程会与 LiveKit 服务器实例建立经过身份验证的 WebSocket 连接（由你的 LIVEKIT_URL 定义，并使用访问令牌进行身份验证）。

此时并没有实际运行的代理。相反，工作进程正在等待 LiveKit 服务器为其分配任务。

当创建房间时，服务器会通知已注册的工作进程之一有新任务。被通知的工作进程可以决定是否接受该任务。如果工作进程接受任务，则会将你的代理实例化为参与者，并让其加入房间，从而开始订阅音视频轨道。一个工作进程可以同时管理多个代理实例。

如果被通知的工作进程拒绝了任务，或者在预设的超时时间内未接受任务，服务器会将任务请求路由到另一个可用的工作进程。

当我向工作进程发送 SIGTERM 信号时会发生什么？

编排系统专为生产环境设计。与典型的 Web 服务器不同，代理是一个有状态的程序，因此在活动会话进行中终止工作进程是非常重要的。

当向工作进程发送 SIGTERM 信号时，工作进程会向 LiveKit 服务器表明它不再需要新的任务。同时，它还会自动拒绝任何在服务器收到信号之前到达的新任务请求。工作进程将继续保持运行状态，直到处理完所有连接到房间的代理。

贡献

要为该项目做出贡献：

1. 分叉 agents-js 仓库
2. 基于 main 分支创建一个新的分支
3. 进行更改
4. 提交拉取请求
5. 在标记评审人员之前，请确保完成预审核对清单。

测试更改和插件

要测试任何更改或插件：

1. 构建项目：

   pnpm build
   

2. 根据插件更改的需要，编辑 ./examples/src/basic_agent.ts

3. 使用调试日志运行基础代理：

   node ./examples/src/basic_agent.ts dev --log-level=debug
   

测试代理连接性

要连接并与你的代理对话：

1. 前往 LiveKit 控制台沙盒部分
2. 启动名为“Web Voice Agent”的沙盒应用
3. 运行你的代理，并确保所有 LiveKit API 密钥都已正确配置
4. 点击沙盒界面中的蓝色“START CALL”按钮，以测试连接并与你的代理对话。

许可证

本项目采用 Apache-2.0 许可证，并符合 REUSE-3.2 标准。有关详细信息，请参阅 许可证。

LiveKit 生态系统
代理 SDKs	Python · Node.js
LiveKit SDKs	浏览器 · Swift · Android · Flutter · React Native · Rust · Node.js · Python · Unity · Unity (WebGL) · ESP32 · C++
入门应用	Python 代理 · TypeScript 代理 · React 应用 · SwiftUI 应用 · Android 应用 · Flutter 应用 · React Native 应用 · 网页嵌入
UI 组件	React · Android Compose · SwiftUI · Flutter
服务器 API	Node.js · Golang · Ruby · Java/Kotlin · Python · Rust · PHP（社区版） · .NET（社区版）
资源	文档 · MCP 服务器文档 · CLI · LiveKit 云
LiveKit 服务器开源软件	LiveKit 服务器 · Egress · Ingress · SIP
社区	开发者社区 · Slack · X · YouTube

LiveKit Agents (Node.js) 快速上手指南

LiveKit Agents for Node.js 是一个用于构建实时、可编程语音代理的框架。它允许开发者创建能够“看”、“听”和“理解”的多模态对话代理，运行在服务器端并通过 WebRTC 与客户端交互。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (推荐 WSL2)
• Node.js: 建议安装最新 LTS 版本 (v18+)
• 包管理器: 本项目推荐使用 pnpm
• LiveKit 服务: 需要一个可用的 LiveKit 服务器实例（可使用 LiveKit Cloud 或自托管）

前置依赖安装

如果尚未安装 pnpm，请先全局安装：

npm install -g pnpm

安装步骤

1. 初始化项目

创建一个新的项目目录并初始化：

mkdir my-voice-agent
cd my-voice-agent
pnpm init

2. 安装核心库与插件

安装 LiveKit Agents 核心库。该框架采用插件化架构，你需要根据需求安装对应的模型插件（如 STT 语音转文字、LLM 大模型、TTS 文字转语音等）。

安装核心库：

pnpm install @livekit/agents

安装常用插件示例（以 OpenAI 和 Deepgram 为例）：

pnpm install @livekit/agents-plugin-openai @livekit/agents-plugin-deepgram @livekit/agents-plugin-silero

注意：如果你希望快速体验且不想配置第三方 API Key，可以使用 LiveKit 提供的推理网关（Inference Gateway），上述代码示例中默认使用了此方案，无需额外安装特定厂商的 SDK 即可运行基础示例。

3. 配置环境变量

在运行代理之前，需要设置以下环境变量。你可以创建一个 .env 文件或在终端中导出：

export LIVEKIT_URL=ws://your-livekit-server:7880
export LIVEKIT_API_KEY=your_api_key
export LIVEKIT_API_SECRET=your_api_secret
# 如果使用第三方模型（如 OpenAI），还需配置对应的 Key
# export OPENAI_API_KEY=sk-...

基本使用

以下是一个最简单的语音代理示例。该代理具备语音识别（STT）、大语言模型处理（LLM）和语音合成（TTS）能力，并包含一个查询天气的工具函数。

新建文件 agent.ts，填入以下代码：

import {
  type JobContext,
  type JobProcess,
  WorkerOptions,
  cli,
  defineAgent,
  llm,
  voice,
  inference,
} from '@livekit/agents';
import * as silero from '@livekit/agents-plugin-silero';
import { fileURLToPath } from 'node:url';
import { z } from 'zod';

// 定义一个工具：查询天气
const lookupWeather = llm.tool({
  description: 'Used to look up weather information.',
  parameters: z.object({
    location: z.string().describe('The location to look up weather information for'),
  }),
  execute: async ({ location }, { ctx }) => {
    // 此处仅为模拟返回，实际应用中可调用真实 API
    return { weather: 'sunny', temperature: 70 };
  },
});

export default defineAgent({
  // 预加载资源（如 VAD 模型），提高启动速度
  prewarm: async (proc: JobProcess) => {
    proc.userData.vad = await silero.VAD.load();
  },
  entry: async (ctx: JobContext) => {
    // 定义代理角色和工具
    const agent = new voice.Agent({
      instructions: 'You are a friendly voice assistant built by LiveKit.',
      tools: { lookupWeather },
    });

    // 配置会话组件
    const session = new voice.AgentSession({
      // STT: 将用户语音转为文本 (耳朵)
      stt: new inference.STT({ model: 'deepgram/nova-3', language: 'en' }),
      // LLM: 处理逻辑并生成回复 (大脑)
      llm: new inference.LLM({ model: 'openai/gpt-4.1-mini' }),
      // TTS: 将文本转为语音输出 (嘴巴)
      tts: new inference.TTS({ model: 'cartesia/sonic-3', voice: '9626c31c-bec5-4cca-baa8-f8ba9e84c8bc' }),
      // VAD: 语音活动检测，判断用户何时说完
      vad: ctx.proc.userData.vad! as silero.VAD,
      // 多语言轮次检测
      turnDetection: new livekit.turnDetector.MultilingualModel(),
    });

    // 启动会话
    await session.start({
      agent,
      room: ctx.room,
    });

    // 主动生成第一条回复
    await session.generateReply({
      instructions: 'greet the user and ask about their day',
    });
  },
});

// 启动 Worker
cli.runApp(new WorkerOptions({ agent: fileURLToPath(import.meta.url) }));

运行代理

在开发模式下运行代理，它将连接到指定的 LiveKit 服务器并等待用户加入房间：

pnpm run build && node ./agent.ts dev

运行成功后，你可以使用 LiveKit 提供的 Playground 网页工具连接测试，或者使用任何集成 LiveKit SDK 的客户端应用加入房间与该代理对话。

生产环境部署

当准备就绪进行生产部署时，使用 start 命令以启用优化：

pnpm run build && node ./agent.ts start