HiAgent自定义话术模板变量设置：5步实现动态话术配置

[1] 一句话结论 #

本指南将带你完成HiAgent自定义话术模板变量的全流程配置操作。

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

适用场景

1. 适合需要根据用户属性、业务上下文动态调整欢迎语/回复话术的客服智能体场景；
2. 适合批量调用智能体、需要传入不同业务参数生成个性化回复的批量任务场景；
3. 适合多渠道部署的智能体，需要根据渠道来源调整话术风格的场景。

不适用场景

1. 如果你的场景是固定话术、不需要动态调整的问答机器人，建议直接使用固定提示词配置，不需要使用变量功能；
2. 如果你的变量需要实时从第三方接口拉取且延迟要求<50ms，建议先通过前置接口拉取参数再传入变量，不要直接依赖智能体内部变量拉取能力；
3. 如果变量数量超过50个且单变量长度>2000字符，建议简化变量结构，或参考【需补充：HiAgent大参数传入方案】实现。

[3] 前置准备 #

• HiAgent控制台账号，拥有智能体编辑权限；
• 已创建好待配置的HiAgent v2.0+版本智能体实例；
• 若需要API传参，需提前申请API调用密钥；
• 预计耗时15分钟。

[4] 分步实现 #

步骤1：进入智能体提示词配置页面

步骤说明：首先登录HiAgent控制台，找到目标智能体进入编排页面，点击提示词编辑区，这是我们配置变量和话术模板的入口，跳过这一步无法找到变量配置入口。
操作路径：登录控制台→我的智能体→选择目标智能体→进入编排→点击左侧「提示词配置」tab。
预期结果：页面展示提示词编辑框，右上角可见「自定义变量」按钮。

⚠️ 常见错误：找不到自定义变量按钮
原因：当前使用的是旧版HiAgent智能体（v1.0版本），不支持自定义变量功能
解决方法：在智能体设置页点击「升级到v2.0版本」，升级后即可看到变量配置入口，注意升级后旧版提示词会保留，不会丢失。

步骤2：添加自定义变量

步骤说明：需要先定义变量的元信息，包括变量名、描述、默认值，这样系统才能识别变量并在未传值时使用默认值填充，避免话术出现占位符残留。
操作：点击右上角「自定义变量」按钮→点击「新增变量」→依次填写变量名（仅支持英文、数字、下划线，首字母必须为英文）、变量描述（说明变量用途，方便后续维护）、默认值（选填，未传入变量时使用）→点击保存。
配置样例：新增客户名称变量
变量名：customer_name
变量描述：当前咨询用户的昵称
默认值：尊敬的用户
预期结果：弹窗中展示已新增的变量列表，状态为已保存。

⚠️ 常见错误：变量名使用了中文或特殊字符，保存时报错
原因：系统对变量名有格式校验，仅支持[a-zA-Z0-9_]格式，长度不超过32字符
解决方法：修改变量名为符合要求的格式，比如将“客户姓名”改为customer_name即可。

步骤3：在话术模板中引用变量

步骤说明：定义好变量后需要在话术模板中插入变量占位符，这样系统在生成回复时才会动态替换对应变量的值。
操作：在提示词/欢迎语编辑框中，输入/唤起变量列表，选择需要插入的变量，变量会自动以${变量名}的格式嵌入，也可以手动输入该格式。
示例话术：你好${customer_name}，欢迎咨询${product_name}售后服务，请问有什么可以帮到您？
预期结果：编辑框中可以看到插入的变量占位符，鼠标悬停可查看变量描述。

步骤4：配置变量传入规则

步骤说明：变量值可以通过多种渠道传入，需要根据你的使用场景选择对应的传入方式，确保变量能被正确赋值。
操作：如果是API调用场景，在调用智能体API时在custom_variables字段中传入键值对，示例代码（Python）：

import requests
url = "https://api.hiagent.xxx/v2/agent/chat"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
payload = {
    "agent_id": "YOUR_AGENT_ID",
    "query": "我要查订单",
    "custom_variables": {
        "customer_name": "张三",
        "product_name": "云服务器"
    }
}
response = requests.post(url, json=payload)

如果是批量任务场景，上传CSV文件时将变量名作为表头，每行对应不同的变量值即可。
预期结果：API调用返回200状态码，无参数错误提示。

步骤5：调试验证变量替换效果

步骤说明：配置完成后需要在调试面板测试变量替换是否正常，避免上线后出现话术错误。
操作：点击右侧调试面板，在「调试参数」中填入变量测试值，输入测试query点击发送，查看返回的话术是否正确替换了变量值。
预期结果：返回的话术中${customer_name}被替换为测试值“张三”，无占位符残留。

[5] 实际验证 #

测试用例：输入query“你好”，传入变量customer_name="李四"、product_name="对象存储"
预期输出：“你好李四，欢迎咨询对象存储售后服务，请问有什么可以帮到您？”
验证成功标志：HTTP状态码200，返回内容中变量占位符全部被替换为对应值，没有出现${xxx}的格式内容。
验证失败常见原因及排查方法：

1. 变量名拼写错误：检查传入的变量名和定义的变量名是否完全一致，区分大小写；
2. 未设置默认值且未传入变量：此时变量会被保留为${xxx}，需要要么设置默认值，要么确保调用时必传该变量；
3. 变量值包含特殊字符：如果变量值包含JSON特殊字符需要转义，避免参数解析错误。

[6] 常见问题 FAQ #

Q1：变量最多可以设置多少个？
A1：目前单个智能体最多支持设置50个自定义变量，单变量值长度不超过2000字符，这个数据来自HiAgent官方v2.3版本接口文档。如果你的场景需要更多变量，可以将多个参数拼接为JSON字符串作为单个变量传入，在提示词中说明解析规则即可。

Q2：什么情况下不建议使用自定义变量功能？
A2：如果你的话术完全固定，不需要任何动态调整的场景，不建议使用变量功能，直接写固定提示词即可，减少配置复杂度。另外如果变量需要做复杂的逻辑计算，建议先在业务侧完成计算再传入变量值，不要依赖智能体内部处理变量逻辑，避免出现计算错误。

Q3：我可以在话术模板中手动写${xxx}格式的变量，不提前在变量配置中新增吗？
A3：不可以，系统只会识别提前在自定义变量列表中配置过的变量，未配置的变量不会被替换，会直接作为普通文本输出。

Q4：不同渠道传入的变量优先级是怎样的？
A4：优先级从高到低为：API传入的变量>调试面板设置的变量>批量任务CSV传入的变量>变量默认值，高优先级的变量值会覆盖低优先级的。

Q5：变量可以在工作流的其他节点中使用吗？
A5：可以，配置过的自定义变量可以在整个智能体工作流的所有节点中引用，包括大模型节点、工具调用节点、条件分支节点等。

[7] 相关阅读 #

• 《HiAgent智能体v2.0升级指南》[/blog/hiagent-v2-upgrade] 了解v2版本的新功能和升级步骤
• 《HiAgent API调用全流程教程》[/blog/hiagent-api-call] 详解如何通过API调用智能体并传入变量
• 《HiAgent批量任务使用指南》[/blog/hiagent-batch-task] 教你如何用批量任务功能批量传入变量生成话术
• 《HiAgent工作流配置最佳实践》[/blog/hiagent-workflow-best-practice] 学习如何在工作流中使用变量实现复杂业务逻辑

[8] 参考资料 #

[1] HiAgent官方文档：自定义变量配置指南，https://www.volcengine.com/docs/hiagent/666666/custom-variables，2026-08-20
[2] CSDN文库：HiAgent里配置大模型节点有哪些关键步骤和注意事项？，https://wenku.csdn.net/answer/4vqfnti0rcum，2026-06-15
本文基于HiAgent智能体v2.3版本编写。

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

2026-08-24