尧图网站建设 
LiveKit 语音 Agent 开场问候的设计与实现从 greeting 提示词看 homepage 示例的提示词工程【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents导读本文以 examples/homepage/prompts/greeting.md 这份开场问候提示词为线索完整讲解 LiveKit Agents 语音 Agent 中开场白的设计与落地它如何被当作 Markdown 模板加载、在何时由谁触发、如何与系统指令instructions协作以及如何用单元测试和 LLM 评估保证问候行为稳定可靠。读完本文你将掌握在 LiveKit Agents 框架中管理提示词模板、编排on_enter开场流程、并为语音场景约束模型输出的完整实战方案。greeting.md 到底在说什么greeting.md全文是一句面向 LLM 的行为指令它定义了语音 Agent 接通用户后的第一反应Greet the user warmly. Introduce yourself as an assistant who can help with LiveKit Agents and other LiveKit products. Ask them how familiar they are with LiveKit so you can tailor your answers.拆解这句话它同时完成了三件事情绪基调warmly开场要热情对应语音客服场景对亲和力的要求身份介绍who you are自我介绍为能够帮助 LiveKit Agents 及其他 LiveKit 产品的助手信息收集tailor your answers主动询问用户对 LiveKit 的熟悉程度从而动态调整后续回答的深度——这一点与 agents_sdks.md 中 start simple, ask the user what they want to know, and only dive deep when they ask for it 的分层讲解策略一脉相承。值得注意的是greeting.md不是系统指令system prompt的一部分而是被单独加载、单独注入的一次性开场指令。理解这一点是理解整个 homepage 示例提示词架构的关键。提示词即模板prompts 目录与加载机制在 homepage 示例中所有作者编写的Agent 语言都存放在 examples/homepage/prompts/ 目录下以 Markdown 模板形式管理greeting.md——开场问候指令agents_sdks.md——系统指令system prompt内含角色设定、知识库与 FAQuser_away.md——用户长时间沉默后的回访指令。加载机制实现在 examples/homepage/prompts/init.py它用importlib.resources.files按模板名读取同包下的.md文件并通过functools.cache缓存结果cache def prompt(name: str) - str: resource files(__package__).joinpath(f{name}.md) if not resource.is_file(): raise FileNotFoundError(fno prompt named {name!r}) return resource.read_text(encodingutf-8)这段实现有几个值得借鉴的设计点模板与代码分离提示词是可朗读、可评审、可单独修改的 Markdown 文件不需要改动 Python 代码缓存加载cache保证同名模板进程内只读一次文件避免每个会话重复 I/O显式失败模板名不存在时抛出FileNotFoundError让拼写错误在启动期即暴露而不是静默传入空指令。在 examples/homepage/agent.py 中greeting与agents_sdks两个模板在模块加载时即被读取INSTRUCTIONS prompt(agents_sdks) GREETING prompt(greeting)这种启动时加载、运行时复用的模式让提示词内容对 Agent 逻辑完全透明。开场白在哪里触发on_enter 与 generate_replygreeting.md 的实际消费点在Assistant.on_enter。在 examples/homepage/agent.py 中async def on_enter(self): await self.session.generate_reply( instructionsGREETING, allow_interruptionsTrue, )on_enter是 LiveKit Agents 中 Agent 每次进入会话时的生命周期钩子在这里主动调用session.generate_reply生成第一轮回复。两个参数值得展开instructionsGREETING本次生成临时注入的指令。它只作用于这次开场回复不会污染系统指令INSTRUCTIONS。这意味着你可以为每一轮生成单独定制上下文而系统指令保持稳定的角色底座allow_interruptionsTrue允许用户在开场白尚未说完时打断。对语音场景这是关键体验设计——若用户一接通就直接提问Agent 不应机械地把整段问候念完而应立刻响应。由此形成的完整调用链是prompt(greeting)加载模板 →GREETING常量 →on_enter中作为临时指令注入 →generate_reply产出首轮语音回复。greeting.md 的温暖开场 自我介绍 询问熟悉度正是在这一链路中被执行的。语音场景的提示词约束为什么问候必须简短口语化问候提示词的设计不能脱离语音输出媒介。在 homepage 示例中TTS 使用了 Fish Audio S2.1 Pro 的 expressive 模式见 agent.py 的tts_model/tts_voice配置并通过tts_text_transforms挂载了 Markdown/emoji 过滤与 LiveKit 发音过滤器agent.py。这些技术手段能修正怎么说但说什么仍需提示词层面约束。系统指令 agents_sdks.md 为此立下了两条硬性规矩长度克制除非用户追问细节否则每次回复不超过两句话DONT WANT TO HOG THE CONVERSATION不要霸占对话零符号输出不使用复杂排版、标点、emoji、星号等符号全部使用缩略形式youre、its、dont以贴近自然口语。greeting.md 与之一致问候只包含热情招呼 身份 一个问题三个要素没有冗余铺垫。这印证了语音提示词工程的核心原则——在提示词层面就把可朗读性写进去而不是依赖后处理补救。开场问候在会话编排中的位置与其他提示词的协作homepage 示例展示了一份模板各司其职的编排思想三种提示词覆盖了会话的三个阶段提示词模板注入时机作用greetingon_enter首轮温暖开场、自我介绍、询问熟悉度以分层作答agents_sdks系统指令全程常驻角色设定、LiveKit 知识库、语音输出约束user_away用户静默超时事件回访确认用户是否还在其中user_away的注入路径与 greeting 完全相同在 examples/homepage/behaviors/user_away.py 中监听user_state_changed事件当用户状态变为away默认静默 15 秒AgentSession选项user_away_timeout时同样以generate_reply(instructionsCHECK_IN_INSTRUCTIONS, allow_interruptionsTrue)的方式注入 user_away.md 的指令。这说明generate_reply(instructions...)是 homepage 示例中临时指令注入的统一入口开场用、回访也用。greeting.md 不是孤立的一句话而是这套常驻系统指令 按需临时指令提示词架构的一个实例。如何验证问候行为单元测试与 LLM 评估提示词是行为契约必须有测试兜底。homepage 示例提供了两层保障单元测试层tests/unit/test_prompts.py验证模板加载机制本身对agents_sdks、greeting、user_away三个模板逐一断言prompt(name)能返回非空内容对不存在的模板名断言抛出FileNotFoundError。这保证了任何一次提示词改动都不会引入空指令或加载失败。评估测试层tests/evals/test_agent_behavior.py用真实的 LLM如openai/gpt-4.1-mini作为 judge验证行为效果。其中test_offers_assistance与 greeting.md 直接对应向 Agent 输入 Hello然后用 judge LLM 按意图清单友好问候、介绍自己是可协助 LiveKit 的助手、允许适度寒暄但不过度打扰评估首轮回复并要求事件流中除助手消息外没有多余事件。result await session.run(user_inputHello) await ( result.expect.next_event() .is_message(roleassistant) .judge( judge_llm, intenttextwrap.dedent(\ Greets the user in a friendly manner. ... ), ) )该文件还覆盖了与问候协作相关的行为Agent SDK 问题直接内联回答无需工具、其他产品问题触发lookup_product工具调用、未知个人信息拒绝回答、有害请求礼貌拒绝。这些评估与 greeting.md 共同定义了一个合格开场 Agent的完整行为边界。本地运行与自定义实践在仓库根目录安装工作区依赖后可以按 examples/homepage/README.md 的方式本地体验uv sync --all-extras --dev # 从仓库根目录执行 uv run agent.py console # 本地控制台会话连接 LiveKit Cloud 以便接入前端或电话会话则使用uv run agent.py dev。开发依赖安装完成后可用python -m pytest跑快速单元测试用python -m pytest -m evals跑依赖LIVEKIT_API_KEY与LIVEKIT_API_SECRET的在线评估套件。如果想自定义开场白只需修改 examples/homepage/prompts/greeting.md 的内容——比如调整自我介绍口径、增加品牌话术或改变询问方式——无需改动任何 Python 代码。修改后跑一遍test_prompts.py确认模板可加载再用 evals 套件验证新的问候仍符合友好、克制的行为契约。如果需要新增一个开场即介绍特定产品的场景也可以仿照该文件新建模板并在on_enter中通过prompt(新模板名)注入这正是提示词即模板设计带来的扩展性。小结从一句看似简单的 greeting.md 出发可以看清 homepage 示例完整的提示词工程链路Markdown 模板管理加载prompts/init.py→ 启动期读取agent.py→on_enter生命周期钩子注入agent.py→ 语音输出约束agents_sdks.md→ 单元测试与 LLM 评估闭环test_prompts.py、test_agent_behavior.py。这一模式不仅适用于开场白也被 user_away.py 复用于用户回访场景是构建可维护、可评估的语音 Agent 提示词体系的可直接复用的范本。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LiveKit 语音 Agent 开场问候的设计与实现：从 greeting 提示词看 homepage 示例的提示词工程
LiveKit 语音 Agent 开场问候的设计与实现从 greeting 提示词看 homepage 示例的提示词工程【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents导读本文以 examples/homepage/prompts/greeting.md 这份开场问候提示词为线索完整讲解 LiveKit Agents 语音 Agent 中开场白的设计与落地它如何被当作 Markdown 模板加载、在何时由谁触发、如何与系统指令instructions协作以及如何用单元测试和 LLM 评估保证问候行为稳定可靠。读完本文你将掌握在 LiveKit Agents 框架中管理提示词模板、编排on_enter开场流程、并为语音场景约束模型输出的完整实战方案。greeting.md 到底在说什么greeting.md全文是一句面向 LLM 的行为指令它定义了语音 Agent 接通用户后的第一反应Greet the user warmly. Introduce yourself as an assistant who can help with LiveKit Agents and other LiveKit products. Ask them how familiar they are with LiveKit so you can tailor your answers.拆解这句话它同时完成了三件事情绪基调warmly开场要热情对应语音客服场景对亲和力的要求身份介绍who you are自我介绍为能够帮助 LiveKit Agents 及其他 LiveKit 产品的助手信息收集tailor your answers主动询问用户对 LiveKit 的熟悉程度从而动态调整后续回答的深度——这一点与 agents_sdks.md 中 start simple, ask the user what they want to know, and only dive deep when they ask for it 的分层讲解策略一脉相承。值得注意的是greeting.md不是系统指令system prompt的一部分而是被单独加载、单独注入的一次性开场指令。理解这一点是理解整个 homepage 示例提示词架构的关键。提示词即模板prompts 目录与加载机制在 homepage 示例中所有作者编写的Agent 语言都存放在 examples/homepage/prompts/ 目录下以 Markdown 模板形式管理greeting.md——开场问候指令agents_sdks.md——系统指令system prompt内含角色设定、知识库与 FAQuser_away.md——用户长时间沉默后的回访指令。加载机制实现在 examples/homepage/prompts/init.py它用importlib.resources.files按模板名读取同包下的.md文件并通过functools.cache缓存结果cache def prompt(name: str) - str: resource files(__package__).joinpath(f{name}.md) if not resource.is_file(): raise FileNotFoundError(fno prompt named {name!r}) return resource.read_text(encodingutf-8)这段实现有几个值得借鉴的设计点模板与代码分离提示词是可朗读、可评审、可单独修改的 Markdown 文件不需要改动 Python 代码缓存加载cache保证同名模板进程内只读一次文件避免每个会话重复 I/O显式失败模板名不存在时抛出FileNotFoundError让拼写错误在启动期即暴露而不是静默传入空指令。在 examples/homepage/agent.py 中greeting与agents_sdks两个模板在模块加载时即被读取INSTRUCTIONS prompt(agents_sdks) GREETING prompt(greeting)这种启动时加载、运行时复用的模式让提示词内容对 Agent 逻辑完全透明。开场白在哪里触发on_enter 与 generate_replygreeting.md 的实际消费点在Assistant.on_enter。在 examples/homepage/agent.py 中async def on_enter(self): await self.session.generate_reply( instructionsGREETING, allow_interruptionsTrue, )on_enter是 LiveKit Agents 中 Agent 每次进入会话时的生命周期钩子在这里主动调用session.generate_reply生成第一轮回复。两个参数值得展开instructionsGREETING本次生成临时注入的指令。它只作用于这次开场回复不会污染系统指令INSTRUCTIONS。这意味着你可以为每一轮生成单独定制上下文而系统指令保持稳定的角色底座allow_interruptionsTrue允许用户在开场白尚未说完时打断。对语音场景这是关键体验设计——若用户一接通就直接提问Agent 不应机械地把整段问候念完而应立刻响应。由此形成的完整调用链是prompt(greeting)加载模板 →GREETING常量 →on_enter中作为临时指令注入 →generate_reply产出首轮语音回复。greeting.md 的温暖开场 自我介绍 询问熟悉度正是在这一链路中被执行的。语音场景的提示词约束为什么问候必须简短口语化问候提示词的设计不能脱离语音输出媒介。在 homepage 示例中TTS 使用了 Fish Audio S2.1 Pro 的 expressive 模式见 agent.py 的tts_model/tts_voice配置并通过tts_text_transforms挂载了 Markdown/emoji 过滤与 LiveKit 发音过滤器agent.py。这些技术手段能修正怎么说但说什么仍需提示词层面约束。系统指令 agents_sdks.md 为此立下了两条硬性规矩长度克制除非用户追问细节否则每次回复不超过两句话DONT WANT TO HOG THE CONVERSATION不要霸占对话零符号输出不使用复杂排版、标点、emoji、星号等符号全部使用缩略形式youre、its、dont以贴近自然口语。greeting.md 与之一致问候只包含热情招呼 身份 一个问题三个要素没有冗余铺垫。这印证了语音提示词工程的核心原则——在提示词层面就把可朗读性写进去而不是依赖后处理补救。开场问候在会话编排中的位置与其他提示词的协作homepage 示例展示了一份模板各司其职的编排思想三种提示词覆盖了会话的三个阶段提示词模板注入时机作用greetingon_enter首轮温暖开场、自我介绍、询问熟悉度以分层作答agents_sdks系统指令全程常驻角色设定、LiveKit 知识库、语音输出约束user_away用户静默超时事件回访确认用户是否还在其中user_away的注入路径与 greeting 完全相同在 examples/homepage/behaviors/user_away.py 中监听user_state_changed事件当用户状态变为away默认静默 15 秒AgentSession选项user_away_timeout时同样以generate_reply(instructionsCHECK_IN_INSTRUCTIONS, allow_interruptionsTrue)的方式注入 user_away.md 的指令。这说明generate_reply(instructions...)是 homepage 示例中临时指令注入的统一入口开场用、回访也用。greeting.md 不是孤立的一句话而是这套常驻系统指令 按需临时指令提示词架构的一个实例。如何验证问候行为单元测试与 LLM 评估提示词是行为契约必须有测试兜底。homepage 示例提供了两层保障单元测试层tests/unit/test_prompts.py验证模板加载机制本身对agents_sdks、greeting、user_away三个模板逐一断言prompt(name)能返回非空内容对不存在的模板名断言抛出FileNotFoundError。这保证了任何一次提示词改动都不会引入空指令或加载失败。评估测试层tests/evals/test_agent_behavior.py用真实的 LLM如openai/gpt-4.1-mini作为 judge验证行为效果。其中test_offers_assistance与 greeting.md 直接对应向 Agent 输入 Hello然后用 judge LLM 按意图清单友好问候、介绍自己是可协助 LiveKit 的助手、允许适度寒暄但不过度打扰评估首轮回复并要求事件流中除助手消息外没有多余事件。result await session.run(user_inputHello) await ( result.expect.next_event() .is_message(roleassistant) .judge( judge_llm, intenttextwrap.dedent(\ Greets the user in a friendly manner. ... ), ) )该文件还覆盖了与问候协作相关的行为Agent SDK 问题直接内联回答无需工具、其他产品问题触发lookup_product工具调用、未知个人信息拒绝回答、有害请求礼貌拒绝。这些评估与 greeting.md 共同定义了一个合格开场 Agent的完整行为边界。本地运行与自定义实践在仓库根目录安装工作区依赖后可以按 examples/homepage/README.md 的方式本地体验uv sync --all-extras --dev # 从仓库根目录执行 uv run agent.py console # 本地控制台会话连接 LiveKit Cloud 以便接入前端或电话会话则使用uv run agent.py dev。开发依赖安装完成后可用python -m pytest跑快速单元测试用python -m pytest -m evals跑依赖LIVEKIT_API_KEY与LIVEKIT_API_SECRET的在线评估套件。如果想自定义开场白只需修改 examples/homepage/prompts/greeting.md 的内容——比如调整自我介绍口径、增加品牌话术或改变询问方式——无需改动任何 Python 代码。修改后跑一遍test_prompts.py确认模板可加载再用 evals 套件验证新的问候仍符合友好、克制的行为契约。如果需要新增一个开场即介绍特定产品的场景也可以仿照该文件新建模板并在on_enter中通过prompt(新模板名)注入这正是提示词即模板设计带来的扩展性。小结从一句看似简单的 greeting.md 出发可以看清 homepage 示例完整的提示词工程链路Markdown 模板管理加载prompts/init.py→ 启动期读取agent.py→on_enter生命周期钩子注入agent.py→ 语音输出约束agents_sdks.md→ 单元测试与 LLM 评估闭环test_prompts.py、test_agent_behavior.py。这一模式不仅适用于开场白也被 user_away.py 复用于用户回访场景是构建可维护、可评估的语音 Agent 提示词体系的可直接复用的范本。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考