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.pyAnamAPI异步客户端封装鉴权、请求重试与/v1/engine/session会话创建接口types.pyPersonaConfig、DirectorNotes、SessionOptions三个配置数据类errors.py插件自定义异常AnamExceptionversion.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-agents1.8.0包许可证为 Apache-2.0。必需的环境变量使用前需要准备两个来源的凭证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)。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覆盖。核心类AvatarSessionAvatarSession是插件对外的主要入口位于 avatar.py。初始化参数from livekit.plugins.anam import AvatarSession, PersonaConfig session AvatarSession( persona_configPersonaConfig(name客服小安, avatarIdyour-avatar-id), session_optionsNone, # 可选SessionOptions api_urlNone, # 可选覆盖默认 https://api.anam.ai api_keyNone, # 可选未传则读 ANAM_API_KEY avatar_participant_identityanam-avatar-agent, # 可选avatar 在房间中的身份 avatar_participant_nameanam-avatar-agent, # 可选avatar 在房间中的显示名 conn_optionsDEFAULT_API_CONNECT_OPTIONS, # 可选连接重试配置 )各参数语义如下参数类型默认行为persona_configPersonaConfig必填定义 avatar 的名称、外观与表现风格无默认值session_optionsSessionOptions或未给出会话级输出选项例如视频输出分辨率、AI 头像披露水印api_urlstr未传则读环境变量ANAM_API_URL再缺省用https://api.anam.aiapi_keystr未传则读环境变量ANAM_API_KEYavatar_participant_identitystr缺省anam-avatar-agent即 avatar 在 LiveKit 房间中的 participant identityavatar_participant_namestr缺省anam-avatar-agentconn_optionsAPIConnectOptions缺省DEFAULT_API_CONNECT_OPTIONS控制请求超时与重试注意conn_options直接复用 LiveKit Agents 框架的APIConnectOptions来自livekit.agentsapi.py 中用它控制max_retry重试次数、retry_interval重试间隔与timeout建连超时遇到aiohttp.ClientError或asyncio.TimeoutError会按策略重试重试耗尽后抛出APIConnectionError。start()启动会话的完整流程await session.start( agent_sessionagent_session, # 你的 AgentSession 实例 roomctx.room, # 当前 JobContext 的房间 livekit_urlNone, # 未传则读 LIVEKIT_URL livekit_api_keyNone, # 未传则读 LIVEKIT_API_KEY livekit_api_secretNone, # 未传则读 LIVEKIT_API_SECRET ) await session.wait_for_join() # 等待 avatar 加入房间并发布视频轨从源码看start()内部依次完成五件事凭证校验补齐并校验 LiveKit 三项凭证任一缺失即抛AnamException签发 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 发布音视频的关键机制调用 Anam 创建会话以async with AnamAPI(...)上下文调用start_session()向 Anam 提交 persona 配置与 LiveKit 环境信息返回的sessionId保存在session.session_id属性上接管音频输出调用agent_session.output.replace_audio_tail(DataStreamAudioOutput(...))将 Agent 的 TTS 音频流重定向到 avatar 参与者destination_identity为 avatar 身份采样率固定为24000SAMPLE_RATE常量并等待 avatar 端发布视频轨后再开始推送继承基类生命周期管理基类start()会注册aclose为 Job 关闭回调并监听conversation_item_added事件以采集播放延迟指标见 _types.py。启动后可用session.wait_for_join(timeout30.0)阻塞等待 avatar 参与者加入房间并发布视频轨超时抛asyncio.TimeoutError传timeoutNone则无限等待session.aclose()用于清理移除房间中的 avatar 参与者、解绑事件监听并取消等待任务。配置对象详解PersonaConfigavatar 的人设与外观定义于 types.pyfrom livekit.plugins.anam import PersonaConfig, DirectorNotes persona PersonaConfig( name客服小安, # 必填avatar 名称 avatarIdyour-avatar-id, # 必填Anam 侧的 avatar 模型 ID avatarModelNone, # 可选avatar 模型标识 directorNotesNone, # 可选风格导演指令 )从 api.py 的 payload 组装逻辑可以看出name与avatarId是必填项会被写入personaConfig的name与avatarId字段同时插件固定使用llmId: CUSTOMER_CLIENT_V1与type: ephemeralavatarModel仅在显式设置时写入directorNotes会过滤掉值为None的字段后再提交从而让 Anam 对未设置项回退到模型默认值。DirectorNotes表现力与风格控制定义于 types.py映射 Anam persona 配置中的directorNotes字段全部字段可选字段类型说明expressivityfloat \| None归一化表现力强度取值[0, 1]1 表示对风格指令响应更强烈0 表示更弱缺省时 Anam 使用默认值 0.5越界值会被 Anam 以 HTTP 400 拒绝presetStylestr \| None内置表现风格例如happy、warm、playful与customStylePrompt互斥同时设置会被 Anam 以 HTTP 400 拒绝customStylePromptstr \| None自由文本风格提示与presetStyle互斥需要说明的是expressivity的归一化区间、presetStyle的完整内置风格清单属于 Anam 平台侧定义源码 docstring 指向 anam.ai 的 director-notes 文档本插件仅负责透传与互斥校验前的字段过滤。SessionOptions会话级输出选项定义于 types.py映射 Anam session-token 请求中的sessionOptions字段字段类型说明video_widthint \| None输出视频帧宽像素。必须与video_height成对设置否则 api.py 会直接抛出ValueErrorfail fast避免向 Anam 提交半对参数后收到 HTTP 400不设置则使用 avatar 模型的默认输出尺寸video_heightint \| None输出视频帧高像素规则同video_widthshow_ai_avatar_disclosurebool \| None是否渲染AI 头像披露水印。Anam 默认不渲染设为True时以水印形式披露视频由 AI 头像生成支持的像素对组合是模型相关的由 Anam 侧校验不支持的组合会被 HTTP 400 拒绝而非静默降级——这是插件在源码注释中明确的设计意图。底层 API 交互AnamAPIAnamAPI位于 api.py是一个异步客户端负责与 Anam 服务端通信鉴权请求头携带Authorization: Bearer api_key与Content-Type: application/json会话创建start_session()向POST {api_url}/v1/engine/session提交{personaConfig, environment, sessionOptions?}JSONenvironment中携带livekitUrl与livekitToken即前面签发的 JWTAnam 据此让渲染引擎加入你的 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( sttinference.STT(deepgram/nova-3), llminference.LLM(google/gemini-3.5-flash), ttsinference.TTS(cartesia/sonic-3.5), # 语音由本地推理 ) avatar anam.AvatarSession( persona_configanam.PersonaConfig( name客服小安, avatarIdyour-avatar-id, directorNotesanam.DirectorNotes(presetStylewarm), ), session_optionsanam.SessionOptions( video_width1280, video_height720, show_ai_avatar_disclosureTrue, ), ) await avatar.start(session, roomctx.room) # 创建 Anam 会话并接管音频输出 await avatar.wait_for_join() # 等待 avatar 入房并发布视频轨 await session.start(agentmy_agent, roomctx.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即可。常见错误与排查症状根因与处理启动即抛AnamException(ANAM_API_KEY must be set...)未提供 Anam API Key。检查构造参数api_key与环境变量ANAM_API_KEY启动即抛AnamException(livekit_url, livekit_api_key, and livekit_api_secret must be set...)LiveKit 三项凭证缺失检查LIVEKIT_URL/LIVEKIT_API_KEY/LIVEKIT_API_SECRET或对应构造参数ValueError: video_width and video_height must be set togetherSessionOptions只设置了一个视频尺寸字段必须成对设置APIStatusErrorHTTP 400多为配置越界如expressivity超出[0,1]、presetStyle与customStylePrompt同时设置、或不支持的视频像素组合按 types.py 中各字段约束修正APIConnectionError网络层重试耗尽检查api_url是否可达、conn_options的超时与重试配置wait_for_join()超时avatar 未按时入房。确认 Anam 引擎可用、房间与 token 权限正确room_join授权、ATTRIBUTE_PUBLISH_ON_BEHALF属性可适当调大timeout结语livekit-plugins-anam以极小的接入成本一个AvatarSession类 三组配置数据类将 Anam 云端虚拟数字人接入 LiveKit 实时语音 AgentTTS 语音由 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考