# LiveKit Agents

[LiveKit Agents](https://docs.livekit.io/agents/) 是用于构建实时语音和媒体 Agent 的框架。它把 Agent 的会话逻辑与音频或视频传输、语音识别、语言模型、语音合成、轮次检测和工具连接起来。这些组件共同使应用能够在实时交互中作出响应。

该框架让这些组件保持模块化。LiveKit 应用可以继续使用现有的房间或传输机制以及语音服务，只把文本语言模型环节通过 AISIX 发送。这样，应用无需把媒体会话移入网关，就能获得 AISIX 模型别名、访问控制、路由和遥测能力。

此集成使用 LiveKit 的 `openai.LLM` 客户端，并配置 AISIX 代理 URL、调用方 API Key 和模型别名。它不使用 OpenAI Realtime 模型插件；LiveKit 继续协调文本 LLM 周围的音频流水线。

## 前置条件[​](#prerequisites "前置条件的直接链接")

开始前，请准备以下内容：

* 使用 LiveKit Agents 的 Python 项目。
* LiveKit Worker 能够访问的运行中 AISIX 网关。
* AISIX 调用方 API Key。
* 调用方 Key 可以通过[兼容 OpenAI 的 API](https://docs.apiseven.com/ai-gateway/endpoints/openai-compatible-chat.md)访问的模型别名。

Worker 还需要现有的 LiveKit、语音转文本和文本转语音配置。这些凭证与 AISIX 调用方 Key 相互独立。

## 配置 LLM 插件[​](#configure-the-llm-plugin "配置 LLM 插件的直接链接")

如果项目尚未包含 LiveKit OpenAI 插件，请安装它：

```
pip install "livekit-agents[openai]~=1.5"
```

在 Worker 环境中设置网关值：

```
# AISIX_BASE_URL 包含 /v1，且末尾不带斜杠。

export AISIX_BASE_URL="https://gateway.example.com/v1"

export AISIX_API_KEY="YOUR_CALLER_API_KEY"

export AISIX_MODEL="voice-agent-prod"
```

使用这些值创建 LLM 插件：

```
import os



from livekit.plugins import openai



llm = openai.LLM(

  api_key=os.environ["AISIX_API_KEY"],

  base_url=os.environ["AISIX_BASE_URL"],

  model=os.environ["AISIX_MODEL"],

)
```

把 `llm` 传给应用的 `AgentSession`。保持现有的传输、STT、TTS 和轮次检测组件不变。

## 测试 LLM 连接[​](#test-the-llm-connection "测试 LLM 连接的直接链接")

加入 LiveKit 房间前，先把同一插件作为独立流式客户端进行测试：

```
import asyncio

import os



from livekit.agents import ChatContext

from livekit.plugins import openai





async def main():

  context = ChatContext()

  context.add_message(

    role="user",

    content="Reply with one short sentence about voice gateways.",

  )



  llm = openai.LLM(

    api_key=os.environ["AISIX_API_KEY"],

    base_url=os.environ["AISIX_BASE_URL"],

    model=os.environ["AISIX_MODEL"],

  )



  stream = llm.chat(chat_ctx=context)

  async for text in stream.to_str_iterable():

    print(text, end="", flush=True)



  await llm.aclose()





asyncio.run(main())
```

脚本应打印流式模型响应。AISIX 应为所选调用方 Key 和别名记录 `POST /v1/chat/completions`。

此测试通过后，运行常规 LiveKit Worker 并验证一轮简短语音对话。如果文本生成成功，但参与者没有收到音频，请排查 LiveKit TTS 和房间流水线，而不是更改 AISIX 模型端点。

## 了解 API 选择[​](#understand-the-api-choice "了解 API 选择的直接链接")

LiveKit 建议直接使用 OpenAI 时优先采用 Responses API 插件。本指南使用 `openai.LLM`，因为 LiveKit 将该客户端用于兼容 OpenAI 的 Chat Completions 端点，而这是适用范围更广的 AISIX 集成路径。

除非应用明确使用网关的 [Realtime API](https://docs.apiseven.com/ai-gateway/endpoints/realtime.md)，并且已经验证完整的音频事件协议，否则不要把 LiveKit OpenAI Realtime 插件指向 AISIX。

## 后续步骤[​](#next-steps "后续步骤的直接链接")

* [流式传输](https://docs.apiseven.com/ai-gateway/endpoints/streaming.md)：了解流完成和故障转移行为。
* [工具调用](https://docs.apiseven.com/ai-gateway/endpoints/tool-calling.md)：验证 LiveKit Agent 使用的工具。
* [路由与故障转移](https://docs.apiseven.com/ai-gateway/routing/routing-and-failover.md)：为语音流量配置具有弹性的模型目标。
