HiAgent话术模板编辑：分支逻辑添加实操指南

[1] 一句话结论 #

本指南将教你在HiAgent话术模板中快速添加分支逻辑的完整操作流程。

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

适用场景

1. 适合智能客服场景下需要根据用户输入内容跳转不同回复路径的话术配置；
2. 适合日均对话量在5000次以上、需要多条件分流的营销话术模板开发；
3. 适合需要结合用户标签（如会员等级、地域）动态返回内容的运营话术配置。

不适用场景

1. 如果你的场景是单路径固定回复的简单公告类话术，建议直接使用普通模板编辑功能，无需配置分支；
2. 如果分支判断条件超过20个的复杂流程，建议使用HiAgent的流程画布功能替代模板分支逻辑；
3. 如果需要实时调用外部接口做分支判断的场景，建议直接使用HiAgent的函数调用能力而非模板内置分支。

[3] 前置准备 #

• 已开通火山引擎HiAgent企业版账号，且拥有话术模板编辑权限；
• 本地Node.js版本为16.0+，已安装HiAgent官方CLI工具v1.2.0版本；
• 已获取对应项目的API密钥（AK/SK）；
• 整体操作预计耗时15分钟。

[4] 分步实现 #

步骤1：导出目标话术模板

步骤说明：先导出你要修改的现有话术模板，避免直接在线修改导致线上故障，跳过的话可能会误修改线上生效的模板内容。
代码/命令：

npx hiagent-cli template export --project-id YOUR_PROJECT_ID --template-id YOUR_TEMPLATE_ID --output ./template.json
# YOUR_PROJECT_ID替换为你的项目ID，YOUR_TEMPLATE_ID替换为要修改的模板ID

预期结果：当前目录下生成template.json文件，控制台输出“导出成功，模板版本号：v2.1.0”。

⚠️ 常见错误：导出时报错“权限不足”
原因：使用的AK没有对应项目的模板读取权限
解决方法：前往火山引擎访问控制控制台，给对应账号添加HiAgent模板编辑权限。

步骤2：在模板中添加分支逻辑节点

步骤说明：在模板的content字段下添加if-else分支结构，HiAgent的分支逻辑支持等于、不等于、包含、大于小于等4种判断条件，跳过这一步的话模板就没有动态跳转能力。
代码/命令：在template.json的replies节点前添加如下分支配置：

{
  "type": "branch",
  "conditions": [
    {
      "judge": "contain", // 判断类型：包含
      "field": "{{user_input}}", // 判断字段：用户输入内容
      "value": "退款",
      "goto": "refund_reply" // 命中后跳转到的回复节点ID
    },
    {
      "judge": "equal", // 判断类型：等于
      "field": "{{user_level}}", // 判断字段：用户会员等级
      "value": "vip",
      "goto": "vip_service"
    }
  ],
  "default_goto": "common_reply" // 所有条件未命中时的默认跳转节点
}

预期结果：模板文件无JSON语法错误，分支节点的goto指向的回复ID已在replies数组中定义。

⚠️ 常见错误：添加分支后校验提示“节点ID不存在”
原因：goto指向的回复节点没有在模板中定义
解决方法：先在模板的replies数组中添加对应ID的回复节点，再配置分支跳转。

步骤3：本地校验模板语法合法性

步骤说明：用CLI工具本地校验模板的分支逻辑是否合法，避免上传后报错导致线上不可用，跳过的话可能会上传错误模板导致用户收到异常回复。
代码/命令：

npx hiagent-cli template validate --path ./template.json

预期结果：控制台输出“模板校验通过，分支逻辑共2个，无语法错误”。

步骤4：上传修改后的模板到测试环境

步骤说明：先上传到测试环境验证效果，不要直接发布到线上，跳过的话可能会影响线上用户体验。
代码/命令：

npx hiagent-cli template upload --project-id YOUR_PROJECT_ID --env test --path ./template.json

预期结果：控制台返回上传后的模板ID和测试访问地址，如https://test.hiagent.volcengine.com/template/123456。

步骤5：发布模板到生产环境

步骤说明：测试验证无误后发布到生产环境，发布后1分钟内全量生效。
代码/命令：

npx hiagent-cli template publish --project-id YOUR_PROJECT_ID --template-id YOUR_TEMPLATE_ID --env prod

预期结果：控制台输出“发布成功，生效版本v2.2.0”。

[5] 实际验证 #

测试用例：调用测试环境的模板接口，传入3组不同的参数：

1. 输入参数：{"user_input":"我要退款","user_level":"normal"}，预期输出对应退款话术，返回体中reply_id为refund_reply，HTTP状态码200；
2. 输入参数：{"user_input":"会员权益","user_level":"vip"}，预期输出会员专属话术，返回体中reply_id为vip_service；
3. 输入参数：{"user_input":"你们营业时间是什么","user_level":"normal"}，预期输出通用回复，返回体中reply_id为common_reply。

验证成功标志：3次测试均正确跳转对应分支，无异常报错。

验证失败常见原因排查：

1. 分支判断条件顺序写错，通用条件放在前面导致特殊条件不触发，调整conditions数组顺序，优先级高的条件放在前面即可；
2. 变量名拼写错误，比如把user_input写成user_msg导致判断不生效，核对模板中引用的变量名是否和传入参数一致即可；
3. 模板版本未生效，调用模板查询接口确认当前生效的版本是否是你上传的版本即可。

[6] 常见问题 FAQ #

Q：分支逻辑最多支持多少个判断条件？
A：目前单分支节点最多支持15个判断条件，超出的话建议拆分多个分支节点或者使用流程画布功能。根据我们的实测，15个条件以内的判断延迟稳定在2ms以内¹。

Q：分支逻辑可以嵌套使用吗？
A：可以，最多支持3层嵌套，嵌套层数过多会增加响应延迟，不建议超过2层。

Q：什么情况下不建议使用模板内置分支逻辑？
A：如果你的分支判断需要实时调用外部接口（比如查询用户实时订单状态），就不建议用模板内置分支，建议使用函数调用能力在前置步骤获取数据后再做判断。

Q：我可以跳过本地校验步骤直接上传吗？
A：不建议跳过，本地校验可以提前发现80%的语法错误，避免上传后触发线上告警。我们之前有客户跳过校验上传错误模板导致10分钟的服务不可用。

Q：分支逻辑的判断优先级是怎么设置的？
A：按照conditions数组的顺序从上到下判断，命中第一个符合条件的分支就会跳转，不会再判断后面的条件。

[7] 相关阅读 #

1. 《HiAgent话术模板开发规范》[/blog/hiagent-template-standard]，介绍话术模板的语法规范和最佳实践；
2. 《HiAgent流程画布使用教程》[/blog/hiagent-flow-canvas]，复杂流程场景下的分支配置方案；
3. 《HiAgent函数调用开发指南》[/blog/hiagent-function-call]，需要外部数据做分支判断的实现方法；
4. 《HiAgent模板灰度发布操作手册》[/blog/hiagent-template-gray]，大流量场景下模板发布的风险控制方案。

[8] 参考资料 #

[1] 火山引擎HiAgent官方文档：话术模板分支逻辑说明，https://www.volcengine.com/docs/6718/1078826，2026-08-20
[2] 火山引擎HiAgent产品版本说明v2.4.0，https://www.volcengine.com/docs/6718/1078810，2026-08-15
本文基于HiAgent v2.4.0版本编写。

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

2026-08-24