企业官网建设流程全解析

LiveKit Agents 集成 Anam 虚拟头像：livekit-plugins-anam 插件配置与实战指南

【免费下载链接】agentsA framework for building realtime voice AI agents 🤖🎙️📹项目地址: https://gitcode.com/GitHub_Trending/agen/agents

导读

livekit-plugins-anam是 LiveKit Agents 框架下的官方插件，用于将 Anam 的云端虚拟数字人（avatar）能力接入实时语音 Agent 会话：Agent 的语音输出由 LiveKit 侧推理生成，而对应的口型动画、面部表情与视频画面由 Anam 引擎渲染并以参与者身份加入同一房间。读完本文，你将掌握该插件的安装前置条件、AvatarSession的完整初始化参数、PersonaConfig/DirectorNotes/SessionOptions三类配置对象的字段语义与边界行为，以及插件底层如何调用 Anam API 完成会话创建与 LiveKit 房间接入。

插件定位与核心能力

从仓库结构看，本插件是一个标准的 LiveKit Agents 插件包，源码位于 livekit-plugins/livekit-plugins-anam/livekit/plugins/anam/，包含以下模块：

• avatar.py：核心的AvatarSession类，负责会话启动、LiveKit 房间接入与音频输出接管；
• api.py：AnamAPI异步客户端，封装鉴权、请求重试与/v1/engine/session会话创建接口；
• types.py：PersonaConfig、DirectorNotes、SessionOptions三个配置数据类；
• errors.py：插件自定义异常AnamException；
• version.py：插件版本号。

该插件集成的是 LiveKit Agents 的 avatar 抽象层。基类AvatarSession定义在 livekit-agents/livekit/agents/voice/avatar/_types.py，其职责包括：等待 avatar 参与者加入房间并发布视频轨（wait_for_join）、在会话结束时移除 avatar 参与者（aclose）、上报 avatar 加入延迟与播放延迟指标等。Anam 插件通过继承该基类并实现start()，把"云端渲染虚拟人"的能力挂接到 LiveKit 房间中。

安装与前置条件

安装插件

使用 pip 安装：

pip install livekit-plugins-anam

根据 pyproject.toml 的声明，插件要求 Python >= 3.10，依赖livekit-agents>=1.8.0，包许可证为 Apache-2.0。

必需的环境变量

使用前需要准备两个来源的凭证：

1. Anam API Key：从 Anam 平台申请，通过环境变量ANAM_API_KEY提供。源码 avatar.py 中，若构造AvatarSession时未显式传入api_key，则会读取ANAM_API_KEY，两者都缺失时直接抛出AnamException("ANAM_API_KEY must be set by arguments or environment variables")。
2. LiveKit 凭证：LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET三者必须齐全。start()内部会为 avatar 参与者签发一个带room_join权限的 access token（见 avatar.py），任一缺失都会抛出AnamException。

此外，api.py 定义了默认 API 地址常量DEFAULT_API_URL = "https://api.anam.ai"，可用环境变量ANAM_API_URL覆盖。

核心类：AvatarSession

AvatarSession是插件对外的主要入口，位于 avatar.py。

初始化参数

from livekit.plugins.anam import AvatarSession, PersonaConfig session = AvatarSession( persona_config=PersonaConfig(name="客服小安", avatarId="your-avatar-id"), session_options=None, # 可选：SessionOptions api_url=None, # 可选：覆盖默认 https://api.anam.ai api_key=None, # 可选：未传则读 ANAM_API_KEY avatar_participant_identity="anam-avatar-agent", # 可选：avatar 在房间中的身份 avatar_participant_name="anam-avatar-agent", # 可选：avatar 在房间中的显示名 conn_options=DEFAULT_API_CONNECT_OPTIONS, # 可选：连接重试配置 )

各参数语义如下：

注意conn_options直接复用 LiveKit Agents 框架的APIConnectOptions（来自livekit.agents），api.py 中用它控制max_retry重试次数、retry_interval重试间隔与timeout建连超时；遇到aiohttp.ClientError或asyncio.TimeoutError会按策略重试，重试耗尽后抛出APIConnectionError。

start()：启动会话的完整流程

await session.start( agent_session=agent_session, # 你的 AgentSession 实例 room=ctx.room, # 当前 JobContext 的房间 livekit_url=None, # 未传则读 LIVEKIT_URL livekit_api_key=None, # 未传则读 LIVEKIT_API_KEY livekit_api_secret=None, # 未传则读 LIVEKIT_API_SECRET ) await session.wait_for_join() # 等待 avatar 加入房间并发布视频轨

从源码看，start()内部依次完成五件事：

1. 凭证校验：补齐并校验 LiveKit 三项凭证，任一缺失即抛AnamException；
2. 签发 avatar token：用 LiveKit 的api.AccessToken为 avatar 生成 JWT，授予room_join权限并加入当前房间；同时通过with_attributes({ATTRIBUTE_PUBLISH_ON_BEHALF: local_participant_identity})声明"以本地 Agent 身份代发布媒体轨"（常量ATTRIBUTE_PUBLISH_ON_BEHALF定义于livekit.agents.voice.room_io），这是 avatar 能代表你的 Agent 发布音视频的关键机制；
3. 调用 Anam 创建会话：以async with AnamAPI(...)上下文调用start_session()，向 Anam 提交 persona 配置与 LiveKit 环境信息，返回的sessionId保存在session.session_id属性上；
4. 接管音频输出：调用agent_session.output.replace_audio_tail(DataStreamAudioOutput(...))，将 Agent 的 TTS 音频流重定向到 avatar 参与者（destination_identity为 avatar 身份），采样率固定为24000（SAMPLE_RATE常量），并等待 avatar 端发布视频轨后再开始推送；
5. 继承基类生命周期管理：基类start()会注册aclose为 Job 关闭回调，并监听conversation_item_added事件以采集播放延迟指标（见 _types.py）。

启动后可用session.wait_for_join(timeout=30.0)阻塞等待 avatar 参与者加入房间并发布视频轨，超时抛asyncio.TimeoutError，传timeout=None则无限等待；session.aclose()用于清理：移除房间中的 avatar 参与者、解绑事件监听并取消等待任务。

配置对象详解

PersonaConfig：avatar 的人设与外观

定义于 types.py：

from livekit.plugins.anam import PersonaConfig, DirectorNotes persona = PersonaConfig( name="客服小安", # 必填：avatar 名称 avatarId="your-avatar-id", # 必填：Anam 侧的 avatar 模型 ID avatarModel=None, # 可选：avatar 模型标识 directorNotes=None, # 可选：风格导演指令 )

从 api.py 的 payload 组装逻辑可以看出，name与avatarId是必填项，会被写入personaConfig的name与avatarId字段，同时插件固定使用llmId: "CUSTOMER_CLIENT_V1"与type: "ephemeral"；avatarModel仅在显式设置时写入；directorNotes会过滤掉值为None的字段后再提交，从而让 Anam 对未设置项回退到模型默认值。

DirectorNotes：表现力与风格控制

定义于 types.py，映射 Anam persona 配置中的directorNotes字段，全部字段可选：

需要说明的是，expressivity的归一化区间、presetStyle的完整内置风格清单属于 Anam 平台侧定义（源码 docstring 指向 anam.ai 的 director-notes 文档），本插件仅负责透传与互斥校验前的字段过滤。

SessionOptions：会话级输出选项

定义于 types.py，映射 Anam session-token 请求中的sessionOptions字段：

支持的像素对组合是模型相关的，由 Anam 侧校验，不支持的组合会被 HTTP 400 拒绝而非静默降级——这是插件在源码注释中明确的设计意图。

底层 API 交互：AnamAPI

AnamAPI位于 api.py，是一个异步客户端，负责与 Anam 服务端通信：

• 鉴权：请求头携带Authorization: Bearer <api_key>与Content-Type: application/json；
• 会话创建：start_session()向POST {api_url}/v1/engine/session提交{personaConfig, environment, sessionOptions?}JSON，environment中携带livekitUrl与livekitToken（即前面签发的 JWT），Anam 据此让渲染引擎加入你的 LiveKit 房间；
• 错误处理：非 2xx 响应抛出APIStatusError（含状态码与响应体）；网络层异常按APIConnectOptions配置重试，重试耗尽抛APIConnectionError；
• 资源管理：支持async with AnamAPI(...)上下文，未传入外部aiohttp.ClientSession时自行创建并在退出时关闭。

与框架的集成模式

将本插件接入一个标准的 LiveKit Agents 应用，推荐骨架如下（可参考仓库 examples/avatar/agent.py 中 avatar 会话的启动与切换模式，该示例使用的是 lemonslice 插件，但AvatarSession.start()/wait_for_join()/aclose()的编排方式一致）：

from livekit import rtc from livekit.agents import AgentSession, JobContext, cli, inference from livekit.plugins import anam @server.rtc_session() async def entrypoint(ctx: JobContext) -> None: session = AgentSession( stt=inference.STT("deepgram/nova-3"), llm=inference.LLM("google/gemini-3.5-flash"), tts=inference.TTS("cartesia/sonic-3.5"), # 语音由本地推理 ) avatar = anam.AvatarSession( persona_config=anam.PersonaConfig( name="客服小安", avatarId="your-avatar-id", directorNotes=anam.DirectorNotes(presetStyle="warm"), ), session_options=anam.SessionOptions( video_width=1280, video_height=720, show_ai_avatar_disclosure=True, ), ) await avatar.start(session, room=ctx.room) # 创建 Anam 会话并接管音频输出 await avatar.wait_for_join() # 等待 avatar 入房并发布视频轨 await session.start(agent=my_agent, room=ctx.room)

运行前提：启动 Worker 前导出ANAM_API_KEY、LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET，并用livekit-agents的 CLI 启动 Worker。插件注册本身是自动的——init.py 在导入时通过Plugin.register_plugin(AnamPlugin())完成注册，因此业务代码只需from livekit.plugins import anam即可。

常见错误与排查

结语

livekit-plugins-anam以极小的接入成本（一个AvatarSession类 + 三组配置数据类）将 Anam 云端虚拟数字人接入 LiveKit 实时语音 Agent：TTS 语音由 Agent 本地推理产出，画面渲染与口型表情由 Anam 云端完成，双方通过 LiveKit 房间内的"代发布媒体轨"机制协同。理解PersonaConfig/DirectorNotes/SessionOptions的字段语义与校验边界、start()的凭证与 token 流程，以及AnamAPI的重试与错误模型，即可在项目中快速落地具备可视化虚拟人形象的语音助手。更完整的字段参考可继续阅读源码 types.py、avatar.py 与 api.py。

【免费下载链接】agentsA framework for building realtime voice AI agents 🤖🎙️📹项目地址: https://gitcode.com/GitHub_Trending/agen/agents