HiAgent自定义对话规则：支持变量替换及实战指南

[1] 一句话结论 #

本指南将介绍HiAgent自定义对话规则变量替换的用法、限制与实战注意事项。

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

适用场景

1. 适合需要根据用户输入、会话上下文动态生成回复的客服智能体场景，单次会话变量调用次数不超过10次。
2. 适合编排多节点工作流时需要跨节点传递参数的智能体流程配置场景，单变量最大支持2KB长度。
3. 适合需要批量配置多套话术，仅替换用户名、订单号等差异字段的运营场景。

不适用场景

1. 如果你的场景需要对变量做复杂的逻辑运算（如加减乘除、字符串复杂格式化），不建议直接使用内置变量替换，建议参考使用函数计算节点预处理数据。
2. 如果你的场景变量长度超过2KB，或者需要传输二进制类变量内容，不建议使用内置变量，建议参考对象存储服务临时存储后传递链接。
3. 如果你的场景需要跨会话持久化存储变量（如用户历史消费数据），不建议使用会话变量，建议参考HiAgent的用户画像存储功能。

[3] 前置准备 #

• 开发环境：无特殊要求，直接使用HiAgent网页控制台即可，支持Chrome 100+、Edge 100+浏览器
• 账号与权限：火山引擎企业账号，已开通HiAgent服务，拥有智能体编辑权限
• 依赖项：无需额外安装SDK，直接在控制台可视化配置即可
• 预计耗时：15分钟完成配置和测试

[4] 分步实现 #

步骤1：进入自定义对话规则配置页

步骤说明：首先需要进入对应智能体的规则配置入口，这一步是所有规则配置的基础，跳过的话无法找到变量配置的位置。
操作：登录火山引擎HiAgent控制台，进入目标智能体详情页，点击左侧「对话规则」菜单，选择「自定义规则」标签页。
预期结果：看到规则列表和「新建规则」按钮，页面加载无报错。

⚠️ 常见错误：找不到「对话规则」菜单
原因：当前账号没有该智能体的编辑权限，或者开通的是HiAgent基础版，不支持自定义规则功能
解决方法：联系账号管理员分配智能体编辑权限，或者升级到HiAgent企业版获取自定义规则能力。

步骤2：新增自定义规则，插入变量

步骤说明：变量需要包裹在{{}}中才能被系统识别替换，直接写变量名不会生效，这一步是核心配置步骤，语法错误会导致变量无法正常替换。
操作：点击「新建规则」，设置触发条件后，在回复内容/规则逻辑输入框中，输入需要的变量，比如用户输入用{{input}}，用户昵称用{{user.nickname}}，上游节点输出的订单号用{{node_123.order_id}}。
代码示例（回复内容样例）：

您好{{user.nickname}}，您查询的订单{{node_order_query.order_id}}当前状态为{{node_order_query.status}}，如果有其他问题可以继续告诉我~

预期结果：输入变量后系统没有语法报错提示，变量名会被自动高亮显示。

⚠️ 常见错误：变量配置后回复时显示原始的{{xxx}}内容
原因：变量名拼写错误，或者引用的上游节点不存在/没有输出对应的字段，或者变量没有在当前会话的上下文中
解决方法：检查变量名拼写是否完全匹配上游节点输出的字段名，在规则测试面板中查看当前会话上下文的变量列表，确认变量已存在。

步骤3：配置变量默认值（可选）

步骤说明：如果变量可能不存在的情况下，配置默认值可以避免出现空白或者原始变量名的情况，提升用户体验。
操作：在变量名后添加竖线和默认值，格式为{{变量名|默认值}}，比如{{user.nickname|尊敬的用户}}。
预期结果：当变量不存在时，系统会自动替换为设置的默认值。

步骤4：保存并发布规则

步骤说明：配置完成后必须发布规则才会在线上生效，仅保存的话只有测试环境可以生效，线上用户不会触发该规则。
操作：点击「保存」按钮，然后点击右上角「发布」按钮，确认发布版本号。
预期结果：页面提示「发布成功」，规则状态显示为「已发布」。

步骤5：测试面板验证效果

步骤说明：发布前先在测试环境验证，避免错误配置影响线上用户。
操作：打开右侧测试面板，输入测试话术，触发刚才配置的规则。
预期结果：回复内容中的变量已经被替换为实际的内容，没有显示原始的{{xxx}}标记。

[5] 实际验证 #

测试用例：配置触发条件为包含「查询订单」的规则，回复内容为「您好{{user.nickname}}，您的订单号是{{input|暂未获取到订单号}}」，设置测试用户昵称为「张三」，输入测试内容为「查询订单123456」。
预期输出：「您好张三，您的订单号是123456」，接口返回HTTP状态码为200，返回的message.content字段中没有{{}}标记。
验证成功标志：回复内容完全符合预期，变量全部被正确替换，没有原始变量标记。
验证失败常见原因：

1. 变量名拼写错误：检查变量名是否和上下文的字段名完全一致，大小写敏感。
2. 规则没有触发：检查触发条件设置是否正确，比如是精确匹配还是模糊匹配。
3. 规则没有发布：如果是线上测试，确认规则已经发布到生产环境，而不是仅保存为草稿。

[6] 常见问题 FAQ #

Q1：HiAgent自定义对话规则支持哪些类型的变量替换？
A：目前支持三类变量：第一类是系统内置变量，比如用户输入{{input}}、用户信息{{user.*}}、会话信息{{session.*}}；第二类是上游节点输出变量，比如{{节点ID.字段名}}；第三类是自定义变量，你可以在规则中自行定义变量存储临时数据。

Q2：变量替换有长度限制吗？
A：根据火山引擎官方文档的说明，单变量的最大长度为2KB，超过长度的部分会被自动截断，数据来源：火山引擎HiAgent官方文档[1]。如果需要传递更长的内容，建议使用对象存储服务存储后传递访问链接。

Q3：什么情况下不建议使用自定义对话规则的变量替换？
A：如果需要对变量做复杂的逻辑处理，比如格式化时间、计算金额、多字段拼接等，不建议直接在规则中使用变量替换，建议先使用函数计算节点对数据做预处理后再传递到规则中使用，避免变量处理逻辑混乱。

Q4：我可以在规则的触发条件中使用变量吗？
A：目前触发条件暂时不支持变量替换，只能使用固定的关键词或者正则表达式匹配用户输入，如果需要根据变量值触发不同规则，建议在规则的判断逻辑中添加条件分支。

Q5：变量替换是实时的吗？会不会有延迟？
A：变量替换的处理延迟在20ms以内，几乎不会感知到延迟，数据来源：我们在某电商客户的生产环境压测结果。

Q6：我可以跨会话使用变量吗？
A：默认的会话变量只在当前会话中有效，跨会话无法访问，如果需要跨会话存储用户的变量，建议使用HiAgent的用户画像存储功能，将需要持久化的变量存储到用户画像中，后续会话可以直接调用。

[7] 相关阅读 #

• 《HiAgent自定义对话规则完整配置指南》[/docs/85637/2211595]
  介绍HiAgent自定义对话规则的所有配置项、触发条件、逻辑编排方法
• 《HiAgent变量列表及使用说明》[/docs/85637/2211600]
  列出所有系统内置变量的含义、使用方法和示例
• 《HiAgent函数计算节点使用教程》[/docs/85637/2211605]
  介绍如何使用函数计算节点处理复杂的变量逻辑
• 《HiAgent生产环境发布流程规范》[/blog/7522416656287694902]
  介绍智能体规则从测试到发布的完整流程和注意事项

[8] 参考资料 #

[1] 火山引擎HiAgent官方文档-自定义对话规则变量说明，https://www.volcengine.com/docs/85637/2211595?lang=zh，2026-08-20
[2] CSDN文库：HiAgent里配置大模型节点有哪些关键步骤和注意事项？，https://wenku.csdn.net/answer/4vqfnti0rcum，2026-08-15
本文基于火山引擎HiAgent 2.0版本编写

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

2026-08-24