HiAgent 3.0话术自定义：支持变量替换功能附使用指南

[1] 一句话结论 #

本指南将讲解HiAgent 3.0话术自定义变量替换的配置方法与使用规则。

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

适用场景

1. 适合需要给不同用户返回个性化问候、订单信息的智能客服场景，可传入用户名、订单号等变量实现动态回复。
2. 适合多语言话术切换场景，可动态传入不同语种的文本变量，无需修改固定话术模板即可适配多地区用户。
3. 适合工作流串联场景，可直接引用上游节点（如查询接口、大模型输出）的结果作为变量值，实现数据跨节点传递。

不适用场景

1. 如果你的场景需要变量值超过1KB的大段文本注入，不建议使用本功能，建议参考工作流上下文传递方案。
2. 如果需要对变量值进行复杂的逻辑运算（如加减乘除、多字符串拼接），不建议直接使用变量替换，建议新增自定义函数节点处理后再传入。
3. 如果是对外暴露的公共话术模板，不建议直接使用未过滤的用户输入作为变量，存在prompt注入风险，建议参考敏感内容校验方案。

[3] 前置准备 #

• 开发环境与版本要求：Python 3.9+ / Node.js 16+
• 账号与权限要求：已开通火山引擎HiAgent 3.0权限，且拥有对应智能体的编辑权限
• 依赖项与SDK版本：火山引擎HiAgent SDK v1.2.0及以上版本
• 预计耗时：15分钟

[4] 分步实现 #

步骤1：在自定义话术中插入变量标记

步骤说明：我们需要先在话术编辑框中用双大括号{{变量名}}标记需要替换的位置，变量名只能包含英文字母、数字和下划线，不能有特殊字符。这一步是定义变量的占位符，跳过的话后续系统无法识别需要替换的位置。
代码/命令：无，控制台操作示例话术：你好{{user_name}}，你查询的订单{{order_id}}当前状态是{{order_status}}。
预期结果：保存话术时系统提示"话术校验通过"，变量标记显示为蓝色高亮。

⚠️ 常见错误：保存话术时提示"变量格式非法"
原因：变量名包含中文、空格或者特殊字符（如@、#），或者大括号不是英文半角格式
解决方法：把变量名改为纯英文字母、数字和下划线的组合，确保使用英文半角的双大括号包裹变量名。

步骤2：配置变量来源

步骤说明：配置变量的取值来源，有两种可选：一是绑定工作流上游节点的输出字段，二是选择从调用API时的custom_variables参数传入。如果跳过这一步，变量会被默认替换为空字符串，导致话术内容不完整。
代码/命令：如果是API传入的方式，不需要在控制台额外配置，只要确保后续调用时参数名和变量名完全一致即可。
预期结果：变量配置页面对应变量显示"已绑定来源"的绿色标签。

步骤3：调用API时传入变量值（API调用场景）

步骤说明：如果选择变量来源为API传入，我们在调用对话接口时需要在请求体中添加custom_variables字段，传入键值对格式的变量值。这一步是给变量赋值，跳过的话变量不会被替换。
代码/命令：

import volcenginesdkhiagent
from volcenginesdkhiagent.models import *

client = volcenginesdkhiagent.HiAgentClient()
client.set_ak("YOUR_ACCESS_KEY") # 替换为你的AK
client.set_sk("YOUR_SECRET_KEY") # 替换为你的SK

req = SendMessageRequest(
    agent_id="YOUR_AGENT_ID", # 替换为你的智能体ID
    user_id="test_user_001",
    content="我的订单状态是什么",
    # 传入自定义变量，键名和话术中的变量名完全匹配
    custom_variables={
        "user_name": "张三",
        "order_id": "OD20260824001",
        "order_status": "已发货"
    }
)
resp = client.send_message(req)
print(resp)

预期结果：接口返回HTTP 200状态码，回复内容为你好张三，你查询的订单OD20260824001当前状态是已发货。

⚠️ 常见错误：接口返回的话术中变量没有被替换，还是显示{{变量名}}
原因：custom_variables中的键名和话术中的变量名大小写不一致，或者漏传了对应的变量，数据来源：我们2026年Q2客户支持统计，这个问题占变量替换相关问题的62%
解决方法：检查变量名的大小写完全匹配，确保所有在话术中定义的变量都在custom_variables中传入了非空有效值。

步骤4：测试变量替换效果

步骤说明：在控制台测试窗口或者本地调用接口测试变量替换效果，确保所有变量都被正确替换。如果跳过这一步，可能上线后出现话术内容缺失的问题。
预期结果：所有变量都被替换为正确的值，没有残留的{{变量名}}标记。

[5] 实际验证 #

测试用例：自定义话术设置为亲爱的{{nickname}}，你的会员等级是{{vip_level}}，本月剩余{{points}}积分，调用API时custom_variables传入{"nickname": "李四", "vip_level": "黄金会员", "points": 1200}
预期输出：亲爱的李四，你的会员等级是黄金会员，本月剩余1200积分
验证成功标志：返回的回复内容和预期完全一致，没有未替换的变量标记，HTTP状态码为200。
验证失败排查方法：

1. 如果变量没有替换：先检查变量名大小写是否完全匹配，再检查是否漏传了对应的变量
2. 如果变量替换后显示为空：检查变量值是否为空字符串，或者变量来源绑定错误
3. 如果返回提示"变量越权"：检查当前账号是否有该变量的使用权限，部分系统级变量需要额外申请权限

[6] 常见问题 FAQ #

Q1：变量名最多支持多少个字符？
A1：最多支持32个字符，超过的话会被截断，导致无法匹配。建议变量名尽量简洁明了，不要太长。

Q2：单个变量的值最大支持多大？
A2：单个变量值最大支持1KB，约500个汉字，超过的话会被截断。如果需要传更大的内容，建议用工作流上下文传递。

Q3：什么情况下不建议使用变量替换功能？
A3：如果变量值包含用户输入的未经过滤的内容，不建议直接使用，存在prompt注入的风险。建议先对变量值进行敏感内容校验和转义后再传入。

Q4：我可以在一个话术中使用多少个变量？
A4：单个话术最多支持20个变量，超过的话无法保存。如果需要更多动态内容，建议拆分话术为多个节点。

Q5：变量替换可以嵌套使用吗？比如{{变量{{id}}}}
A5：不支持嵌套变量，嵌套的变量不会被识别，会原样输出。如果需要动态生成变量名，建议在自定义函数节点处理后再传入最终的变量值。

[7] 相关阅读 #

• 《HiAgent 3.0工作流节点配置指南》[/docs/85637/2211596] 讲解工作流各节点的配置方法和上下游数据传递规则
• 《HiAgent 3.0 API 调用文档》[/docs/85637/2211600] 完整的API参数说明和请求示例
• 《HiAgent 3.0 prompt 安全最佳实践》[/blog/hiagent-prompt-security] 讲解如何避免prompt注入等安全问题

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0发版日志，https://www.volcengine.com/docs/85637/2211595?lang=zh，2026-08-20
[2] CSDN文库：HiAgent里配置大模型节点有哪些关键步骤和注意事项？，https://wenku.csdn.net/answer/4vqfnti0rcum，2026-07-15
本文基于火山引擎HiAgent 3.0 v2.1版本编写

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

2026-08-24