LiveKit Agents AWS 插件实战基于 Amazon Nova Sonic 构建实时语音 Agent【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents本篇指南以livekit-plugins-aws插件为核心系统讲解如何在 LiveKit Agents 框架中接入 Amazon Bedrock、Nova Sonic 实时语音模型、Transcribe 语音识别与 Polly 语音合成覆盖安装配置、模型与音色选择、generate_reply()文本提示、轮转灵敏度调优以及 STT LLM TTS 管线模式的完整实践。读完本文你将掌握从零搭建一个基于 Nova 2 Sonic 的端到端实时语音 Agent并理解其底层双向流与会话回收等稳定性机制。插件总览一个包覆盖 AWS 全链路 AI 能力livekit-plugins-aws是 LiveKit Agents 的 AWS AI 全家桶插件将四大能力统一收敛到livekit.plugins.aws命名空间下能力底层 AWS 服务默认模型RealtimeModelAmazon Bedrock 双向流speech-to-speechAmazon Nova 2 Sonicamazon.nova-2-sonic-v1:0LLMAmazon Bedrock Converse APIAmazon Nova 2 Liteamazon.nova-2-lite-v1:0STTAmazon Transcribe—TTSAmazon PollyRuthgenerative 引擎在 插件入口文件 中插件对外导出STT、SpeechStream、TTS、ChunkedStream、LLM、realtime与__version__并注册为 LiveKit 官方Plugin。值得注意的是realtime模块采用惰性加载只有当你显式访问aws.realtime时才尝试导入若未安装可选依赖会抛出ImportError提示pip install livekit-plugins-aws[realtime]。因此即使只使用传统的管线模式STT/LLM/TTS也不需要安装实时模型依赖。安装与依赖安装基础插件pip install livekit-plugins-aws如需使用 Nova Sonic 实时语音模型安装带realtime额外依赖的版本pip install livekit-plugins-aws[realtime]从 pyproject.toml 可以看到运行时约束基础依赖livekit-agents1.8.0、aiobotocore3.0.0且要求python_version 3.12时额外引入aws_sdk_transcribe_streaming0.11.0与smithy-http[awscrt]realtime额外依赖aws-sdk-bedrock-runtime0.2.0、aws-sdk-signers0.0.3、boto31.35.10项目要求 Python3.10.0。配置注释中明确说明了 CRT 传输层的原因StartStreamTranscriptionTranscribe 双向流与 Nova Sonic 的双向流都需要CRTawscrt传输而较新版本的transcribe-streaming/bedrock-runtime将 CRT 从其基础依赖中移除因此插件显式声明smithy-http[awscrt]来保证双向流可用。前置条件AWS 凭据配置环境变量插件通过标准的 boto3 凭据链获取认证因此最简单的做法是设置环境变量export AWS_ACCESS_KEY_IDyour-access-key export AWS_SECRET_ACCESS_KEYyour-secret-key export AWS_DEFAULT_REGIONus-east-1 # or your preferred region从源码看RealtimeModel与LLM的region参数默认值均为us-east-1RealtimeSession在初始化客户端时会据此拼出端点https://bedrock-runtime.{region}.amazonaws.com见 realtime_model.py。从 SSO 获取临时凭据本地测试如果使用 AWS SSO 认证可以按如下流程导出临时凭据# 登录 SSO 配置文件 aws sso login --profile your-profile-name # 从 SSO 会话导出凭据到环境变量 eval $(aws configure export-credentials --profile your-profile-name --format env) # 验证凭据是否生效 aws sts get-caller-identity为避免每次都要手动导出可将其封装为 shell 函数并写入~/.bashrc或~/.zshrcfunction aws-creds() { eval $(aws configure export-credentials --profile $1 --format env) } # 用法aws-creds your-profile-name临时凭据对实时会话尤为重要源码中的Boto3CredentialsResolver会缓存凭据并在过期前 3 分钟主动触发会话回收详见下文会话回收机制因此本地调试时使用临时凭据也能保持会话不断流。快速上手默认行为与 Breaking Change重要变更默认模型已切换为 Nova 2 Sonic。RealtimeModel()现在默认使用amazon.nova-2-sonic-v1:0modalitiesmixed支持语音 文本输入此前默认的amazon.nova-sonic-v1:0modalitiesaudio仅语音不再作为默认值。如果你需要保留旧行为可显式指定 Nova Sonic 1.0model aws.realtime.RealtimeModel.with_nova_sonic_1() # 或 model aws.realtime.RealtimeModel( modelamazon.nova-sonic-v1:0, modalitiesaudio )对应地源码中with_nova_sonic_2()封装了modelamazon.nova-2-sonic-v1:0modalitiesmixed而with_nova_sonic_1()封装了modelamazon.nova-sonic-v1:0modalitiesaudio两个工厂方法在 realtime_model.py 中定义。模型选择Nova 2 Sonic 与 Nova Sonic 1.0from livekit.plugins import aws # Nova 2 Sonic语音 文本输入最新 model aws.realtime.RealtimeModel.with_nova_sonic_2() # Nova Sonic 1.0仅语音初代模型 model aws.realtime.RealtimeModel.with_nova_sonic_1()Nova 2 Sonic 核心能力Amazon Nova 2 Sonic 是统一的 speech-to-speech 基础模型支持实时双向流式对话低延迟、自然的语音交互多语言英语、法语、意大利语、德语、西班牙语、葡萄牙语、印地语自动语言镜像自动以用户所说的语言作答多语言polyglot音色Matthew 与 Tiffany 可在单次对话中无缝切换语言非常适合多语言应用18 个 expressive 音色每种语言多个音色具备自然韵律函数调用内置工具调用与 Agentic 工作流打断处理优雅处理打断且不丢失上下文噪声鲁棒性可应用于真实嘈杂环境文本输入支持支持程序化文本提示。构造参数详解源码确认RealtimeModel的构造参数在 realtime_model.py 中定义如下参数默认值说明modelamazon.nova-2-sonic-v1:0Bedrock 实时推理模型 IDmodalitiesmixedaudio仅语音Sonic 1.0或mixed语音 文本Sonic 2.0voicetiffanyTTS 输出音色 IDtemperature0.7采样温度注意 Sonic 的定义与行业惯例相反0.0最随机1.0最确定top_p0.9核采样概率质量同样0.0最随机、1.0最确定max_tokens1024单次响应最大输出 token 数上限 10,000tool_choiceNOT_GIVEN工具调用策略auto/required/ 指定函数regionus-east-1Bedrock 运行时端点所在区域turn_detectionMEDIUM轮转灵敏度HIGH/MEDIUM/LOWgenerate_reply_timeout10.0generate_reply()调用超时秒RealtimeModel同时声明了能力集RealtimeCapabilities支持服务端轮转检测、用户转写、音频输出与自动工具回复生成但不支持手动函数调用与每响应级 tool_choice。音色选择音色以小写字符串指定可导入SONIC1_VOICES或SONIC2_VOICES类型提示获得 IDE 自动补全from livekit.plugins.aws.experimental.realtime import SONIC2_VOICES model aws.realtime.RealtimeModel.with_nova_sonic_2( voicecarolina # 葡萄牙语女性 )Nova 2 Sonic 音色 ID以下列表来自 README最新列表与 ID 以 AWS 官方文档为准语言音色 ID英语美国tiffanypolyglot、matthewpolyglot英语英国amy英语澳大利亚olivia英语印度kiara、arjun法语ambre、florian意大利语beatrice、lorenzo德语tina、lennart西班牙语美国lupe、carlos葡萄牙语巴西carolina、leo印地语kiara、arjun注意Nova 2 Sonic 中tiffany与matthew支持 polyglot 模式可在单次对话中无缝切换语言。从源码看types.py 中SONIC2_VOICES定义了 16 个唯一音色 ID其中kiara/arjun在英语印度与印地语之间共用README 宣称为 18 个 expressive 音色。Nova Sonic 1.0 音色 ID11 个语言音色 ID英语美国tiffany、matthew英语英国amy法语ambre、florian意大利语beatrice、lorenzo德语greta、lennart西班牙语lupe、carlos文本提示使用generate_reply()Nova 2 Sonic 支持程序化文本输入可用于主动触发 Agent 回复或在同一对话中混合语音与文本输入例如在 UI 中混合输入class Assistant(Agent): async def on_enter(self): # 让 Agent 先开口打招呼 await self.session.generate_reply( instructionsGreet the user and introduce your capabilities )instructionsvsuser_inputgenerate_reply()接受两个行为不同的参数instructions—— 系统级指令推荐await session.generate_reply( instructionsGreet the user warmly and ask how you can help )作为系统提示/命令发送给模型立即触发生成不会作为用户消息出现在对话历史中适用场景Agent 主动发起的语音、提示特定行为。user_input—— 模拟用户消息await session.generate_reply( user_inputHello, I need help with my account )以交互式 USER 角色内容发送会被加入 Nova 的对话上下文像用户说话一样触发生成适用场景测试、模拟用户输入、程序化对话。选择建议场景参数Agent 开场问候用instructionsAgent 无需用户输入即可说话引导 Agent 下一步行为用instructions模拟多轮对话测试用user_input程序化注入用户输入用user_input如同用户说话一样注入文本从源码实现看generate_reply()的文本发送受_stream_ready事件与_text_block_lock双重约束必须等 Bedrock 双向流返回 HTTP 200音频通道已就绪后才能发送交互式文本且文本块发送期间会暂停音频帧传输以避免触发 Nova Sonic 的 Chat history should be sent completely before streaming audio 校验错误。轮转灵敏度Turn-Taking Sensitivity控制 Agent 对停顿的响应速度model aws.realtime.RealtimeModel.with_nova_sonic_2( turn_detectionMEDIUM # HIGH, MEDIUM (默认), LOW )HIGH响应最快为低延迟优化但可能打断语速较慢的说话者MEDIUM平衡响应速度与误打断推荐默认值LOW响应最慢、最有耐心适合犹豫型说话者。TURN_DETECTION在 types.py 中被定义为Literal[HIGH, MEDIUM, LOW]并在初始化时写入 Nova Sonic 的endpointingSensitivity字段Nova Sonic 2 要求该字段嵌套在turnDetectionConfiguration下见 events.py 中的SessionStart模型。完整示例Nova 2 Sonic 实时语音 Agentfrom livekit import agents from livekit.agents import Agent, AgentSession from livekit.plugins import aws from dotenv import load_dotenv load_dotenv() class Assistant(Agent): def __init__(self): super().__init__( instructionsYou are a helpful voice assistant powered by Amazon Nova 2 Sonic. ) async def on_enter(self): await self.session.generate_reply( instructionsGreet the user and offer assistance ) server agents.AgentServer() server.rtc_session() async def entrypoint(ctx: agents.JobContext): await ctx.connect() session AgentSession( llmaws.realtime.RealtimeModel.with_nova_sonic_2( voicematthew, turn_detectionMEDIUM, tool_choiceauto ) ) await session.start(roomctx.room, agentAssistant()) if __name__ __main__: agents.cli.run_app(server)注意RealtimeModel的voice、turn_detection、tool_choice等参数也可在构造RealtimeModel时直接指定二选一即可。会话建立后RealtimeSession会以两个后台任务驱动整个对话_process_audio_input将用户麦克风音频与工具结果推送给 Bedrock_process_responses接收服务端事件并将其转换为 LiveKit 的MessageGeneration等高层抽象见 realtime_model.py。Pipeline 模式STT LLM TTS 分离如果需要对各组件进行更精细的控制可以使用传统的管线模式让 STT、LLM、TTS 各司其职from livekit.agents import inference from livekit.plugins import aws session AgentSession( sttaws.STT(), # Amazon Transcribe llmaws.LLM(), # Nova 2 Lite默认 ttsaws.TTS(), # Amazon Polly vadinference.VAD(), )Nova 2 LiteAmazon Nova 2 Lite 是面向日常 AI 负载的快速、高性价比推理模型极快处理实时对话场景下延迟极低高性价比行业领先的性价比表现多模态输入支持文本、图像、视频100 万 token 上下文窗口可处理长对话与复杂上下文Agentic 工作流RAG 系统、函数调用、工具使用微调支持可按需定制。它非常适合需要在语音应用中获取快速、准确 LLM 响应的管线模式。LLM 构造参数源码确认llm.py 中LLM的默认模型为amazon.nova-2-lite-v1:0支持以下参数model也可通过环境变量BEDROCK_INFERENCE_PROFILE_ARN指定推理配置 ARN、api_key/api_secret、region默认us-east-1、temperature默认0.8、max_output_tokens、top_p、tool_choice、additional_request_fields、cache_system/cache_tools缓存系统消息与工具定义以降低 token 用量、supports_sampling_params显式覆盖采样参数支持判断等。插件还会自动识别拒绝temperature/topP参数的模型如 Claude Opus 4.7/4.8、Opus 5、Sonnet 5 等避免触发ValidationException。STT 构造参数源码确认stt.py 中STT的默认sample_rate24000、languageen-US、encodingpcm并支持vocabulary_name、vocab_filter_method/vocab_filter_name、show_speaker_label、enable_channel_identification/number_of_channels、enable_partial_results_stabilization/partial_results_stability、language_model_name、identify_language/identify_multiple_languages/language_options/preferred_language、vocabulary_names/vocabulary_filter_names等完整参数可覆盖多语言识别与说话人标注等高级场景。TTS 构造参数源码确认tts.py 中TTS的默认音色为Ruthgenerative 引擎默认sample_rate16000、text_typetext可切换为ssml以使用 SSML 增强文本并支持language、speech_engine、region、api_key/api_secret等参数。其TTSCapabilities(streamingFalse)表明 Polly 合成按块返回而非真正的流式输出。底层实现与稳定性设计源码级双向流与事件驱动架构RealtimeSession通过 Bedrock Runtime 的invoke_model_with_bidirectional_stream建立双向流音频输入以 16kHz/16bit/单声道、base64 编码的 LPCM 帧发送音频输出以 24kHz 采样率解码为rtc.AudioFrame。服务端事件completionStart、audioOutputContent、textOutputContent、toolUse、usageEvent等由_event_handlers分发到对应的_handle_*方法并同步维护_ResponseGeneration生命周期状态。会话回收机制AWS 对实时会话存在约 8 分钟的限制临时凭据也可能过期。源码通过_start_session_recycle_timer主动回收会话默认MAX_SESSION_DURATION_SECONDS 6 * 60可通过环境变量LK_SESSION_MAX_DURATION覆盖便于测试并在凭据过期前 3 分钟提前重启。回收流程会先等待 Assistant 说完END_TURN、确认音频停流、发送关闭事件、排空待处理工具结果然后保留对话状态重建会话且会在历史以 assistant 消息开头时补一条占位 USER 消息以满足 Nova Sonic 的约束。错误恢复与上下文保护_is_recoverable_validation_error()可识别 System instability detected 等可恢复校验错误并自动重启会话相关逻辑有对应单元测试见 tests/test_realtime_validation_errors.py遇到ThrottlingException、ModelNotReadyException、ModelTimeoutException等也会尝试重启聊天上下文被限制为最多 40 条消息、单条消息 1KB超出自动截断防止触发 Nova Sonic 的服务端校验检测到用户打断时通过BARGE_IN_SIGNAL标记被中断消息并关闭当前生成。工具调用与指标注册工具后_serialize_tool_config()会把 LiveKit 的FunctionTool转换为 Nova Sonic 的ToolSpec/ToolConfiguration并自动将未显式指定的temperature/top_p调整为贪心值1.0官方推荐的工具调用配置。每次完成周期还会基于usageEvent计算并上报RealtimeModelMetrics包含TTFT首 token 延迟、响应时长、tokens/秒以及输入/输出 token 明细文本 token 与语音 token 分开统计。结语livekit-plugins-aws用一个插件包同时覆盖了实时 speech-to-speechNova 2 Sonic / Nova Sonic 1.0与经典 STT LLM TTS 管线两条路线追求极低延迟与多语言自然对话可直接使用RealtimeModel需要精细控制各组件时则可回退到 Transcribe Bedrock Nova 2 Lite Polly 的组合。插件底层还内置了会话回收、错误恢复、上下文裁剪与指标上报等生产级机制配合LK_BEDROCK_DEBUG、LK_SESSION_MAX_DURATION等环境变量便于调试与压测。更多细节可继续阅读仓库内的 插件 README、实时模型实现 与 测试用例。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考