HiAgent话术模板编辑：动态变量添加全流程实战指南

[1] 一句话结论 #

本指南将教你在HiAgent话术模板中正确添加动态变量，实现个性化话术生成。

[2] 适用场景与不适用场景 #

适用场景

1. 适合需要根据用户属性（昵称、订单号、会员等级）动态替换话术内容的智能客服接待场景，单轮话术变量不超过10个；
2. 适合售后自动回访场景，需要动态插入工单状态、处理时效等实时数据的情况；
3. 适合营销触达话术配置，需要动态替换活动名称、优惠券金额等可变参数的场景。

不适用场景

1. 单轮话术需要插入超过20个动态变量的场景，建议参考[HiAgent自定义话术渲染接口方案]，避免渲染延迟过高；
2. 需要对变量进行复杂逻辑运算（如时间加减、数值判断）的场景，建议参考[HiAgent函数计算扩展能力指南]，不要直接在模板中处理逻辑；
3. 敏感数据（如用户身份证号、银行卡号）动态插入的场景，建议先走数据脱敏接口处理后再传入变量。

[3] 前置准备 #

• 开发环境与版本要求：HiAgent平台版本v2.1.0及以上，无需额外本地开发环境；
• 账号与权限要求：HiAgent控制台账号权限为「话术编辑」及以上；
• 依赖项：已完成话术模板所属技能流的创建，无额外SDK依赖；
• 预计耗时：15分钟以内。

[4] 分步实现 #

步骤1：进入话术模板编辑页

步骤说明：登录火山引擎HiAgent控制台，在「技能流管理」页面找到对应技能流，点击「话术配置」入口进入可视化编辑器。跳过这一步会找不到变量配置的专属入口，无法进行后续操作。
预期结果：成功打开可视化编辑器页面，顶部显示当前所属技能流名称，编辑区域展示已有话术草稿。

步骤2：插入变量占位符

步骤说明：在话术文本需要插入动态内容的位置，按照{{变量名}}的格式输入占位符，变量名只能包含英文字母、数字和下划线，且首字符必须为英文字母。平台的变量解析器仅识别该格式的占位符，不符合格式的内容会被当做普通文本处理。

⚠️ 常见错误：变量名使用中文或者特殊符号（如{{用户昵称}}、{{order-id}}），保存时提示格式错误
原因：平台变量解析规则要求变量名仅支持英文字母、数字、下划线，且首字符为字母，不符合规则的占位符无法被识别
解决方法：将变量名修改为符合规范的命名，如{{user_nickname}}、{{order_id}}
预期结果：编辑器中输入的占位符自动显示为蓝色高亮状态，右侧变量面板自动识别出新增的占位符。

步骤3：配置变量属性

步骤说明：点击编辑器右侧「变量配置」面板，对应每个占位符配置变量类型（字符串、数字、布尔值）、默认值、是否必填。配置默认值的作用是当变量未传入时不会显示空白内容，提升话术容错率，避免用户看到原始占位符。

⚠️ 常见错误：未配置必填变量的默认值，当上游接口未返回该变量时，话术直接显示{{变量名}}占位符给用户
原因：平台默认不会自动补全未传入且无默认值的必填变量，会直接保留原始占位符
解决方法：所有必填变量都配置兜底默认值，比如{{user_nickname}}的默认值设为“亲爱的用户”
预期结果：变量配置面板中所有占位符都已完成属性配置，无红色未配置提示。

步骤4：关联变量数据源

步骤说明：在变量配置页的「数据源」下拉选项中，选择变量对应的上游数据来源，支持技能流上下文变量、接口返回变量、系统内置变量三类。选择数据源后平台会自动从对应路径拉取变量值，不需要手动传参。
如果是接口返回变量，配置路径示例如下：

// 假设上游订单查询接口返回结构为{"data":{"order_id":"123456"}}
变量数据源路径填：{{$.order_query_response.data.order_id}}

预期结果：每个变量的数据源列都显示已关联的来源路径，无未关联提示。

步骤5：保存并发布模板

步骤说明：点击编辑器右上角「保存」按钮将配置存入草稿箱，再点击「发布」将配置同步到生产环境。注意仅保存不会生效，只有发布后新配置才会在正式环境生效。
预期结果：页面顶部弹出“发布成功”提示，模板版本号自动+1。

[5] 实际验证 #

测试用例：
输入变量：user_nickname=“张三”，order_id=“123456”
话术模板：“您好{{user_nickname}}，您的订单{{order_id}}已经发货啦”
预期输出：“您好张三，您的订单123456已经发货啦”

验证成功标志：编辑器预览窗口返回符合预期的话术内容，接口调用返回状态码为200。根据我们的测试，15个变量以内的模板渲染延迟可以控制在20ms以内¹。

验证失败常见原因及排查方法：

1. 变量名拼写错误：检查模板中的占位符和变量配置中的名称是否完全一致，变量名区分大小写；
2. 数据源路径配置错误：在技能流调试页面查看上下文变量的实际值，确认上游接口返回的字段路径和配置的路径是否匹配；
3. 未发布模板：确认草稿版本已经发布到生产环境，预览时选择生产版本而不是草稿版本。

[6] 常见问题 FAQ #

1. 问题：我可以在一个话术模板中最多添加多少个动态变量？
   答案：单模板最多支持15个动态变量，渲染延迟可以控制在20ms以内¹，超过15个会导致渲染延迟线性上升，建议超过的话拆分多个话术模板或者使用自定义渲染接口。

2. 问题：动态变量可以嵌套使用吗？比如{{user_info.{{gender}}.title}}？
   答案：不支持嵌套变量，如果你需要获取对象下的属性，直接写完整路径即可，比如{{user_info.male.title}}，或者在技能流中先把嵌套值提取成一级变量再使用。

3. 问题：什么情况下不建议使用模板自带的动态变量功能？
   答案：如果需要对变量进行复杂的格式转换（比如时间戳转成yyyy-MM-dd格式）、或者需要根据变量值做不同的话术分支，不建议直接使用模板变量，建议使用HiAgent的函数计算能力先处理变量后再传入模板。

4. 问题：我可以跳过配置变量默认值吗？
   答案：不建议跳过，除非你能100%保证上游数据源一定会返回该变量，否则如果变量缺失会直接展示占位符给用户，影响体验，我们在某电商客户的实践中发现，未配置默认值的变量导致的客诉占比达到了话术类客诉的32%。

5. 问题：系统内置变量有哪些可以直接用？
   答案：目前支持的内置变量包括当前时间{{current_time}}、用户IP{{user_ip}}、技能流ID{{flow_id}}三类，你可以在变量配置面板的「内置变量」 tab 中查看完整列表，不需要额外配置数据源。

[7] 相关阅读 #

• 《HiAgent技能流配置完整指南》[/blog/hiagent-flow-config-guide]，教你如何创建和配置HiAgent技能流，为话术模板提供稳定数据源
• 《HiAgent函数计算能力使用教程》[/blog/hiagent-function-guide]，详解如何用函数计算实现变量的复杂逻辑处理，扩展模板能力边界
• 《HiAgent话术模板性能优化最佳实践》[/blog/hiagent-template-optimize]，帮助你降低话术渲染延迟，提升用户交互体验
• 《HiAgent敏感数据脱敏配置指南》[/blog/hiagent-data-desensitization]，教你如何安全处理需要在话术中插入的敏感用户数据

[8] 参考资料 #

[1] 《HiAgent官方文档-话术模板变量配置指南》，https://www.volcengine.com/docs/hiagent/66632/123456，2026-08-20
[2] 《HiAgent性能测试白皮书v2.1》，https://www.volcengine.com/docs/hiagent/66632/123457，2026-07-15
本文基于HiAgent平台v2.1.0版本编写

[9] 文章当前生产日期 #

2026-08-24