HiAgent 3.0话术自定义：变量替换完整操作避坑指南

[1] 一句话结论 #

本指南将手把手教你完成HiAgent 3.0自定义话术的变量替换配置与落地。

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

适用场景

1. 适合需要根据用户身份、订单信息等动态生成回复的智能客服场景，单会话变量数≤20个；
2. 适合可视化工作流中需要将上游节点输出注入大模型回复的业务场景；
3. 适合日均API调用量在10万次以下、替换后提示词长度≤8000字符的对话类场景。

不适用场景

1. 不适用变量超过50个、多分支逻辑嵌套复杂的话术场景，建议使用工作流分支节点单独配置不同分支话术；
2. 不适用需要实时拉取非结构化外部数据直接做替换的场景，建议先通过工具调用节点预处理数据再传参；
3. 不适用替换后总提示词长度超过8000字符的长上下文场景，建议参考【HiAgent长上下文优化方案】调整。

[3] 前置准备 #

• 开发环境：调用API可使用Python 3.8+/Java 11+/Node.js 16+，可视化配置无语言要求；
• 账号权限：火山引擎HiAgent 3.0企业版账号，拥有智能体编辑与API调用权限；
• 依赖项：火山引擎HiAgent官方SDK v1.2.0及以上版本（仅API调用场景需要）；
• 预计耗时：30分钟以内。

[4] 分步实现 #

步骤1：配置自定义变量占位符

步骤说明：首先在HiAgent控制台的话术编辑页定义需要动态替换的变量占位，只有符合命名规范的占位符才能被系统识别，跳过这一步后续传参不会生效。
话术示例：

您好{{user_name}}，您的订单{{order_id}}已发货，预计{{delivery_time}}送达。

预期结果：话术保存后无报错，变量占位符会在编辑页显示高亮标记。

⚠️ 常见错误：变量保存时提示“命名非法”
原因：变量名使用了中文、特殊符号或者纯数字，不符合命名规范
解决方法：调整变量名仅使用字母、数字、下划线组合，且不能以数字开头。

步骤2：选择变量赋值模式

步骤说明：根据你的使用场景选择对应的变量传参模式，选错模式会导致变量无法匹配替换。如果是直接调用智能体API的场景，选择接口传参模式；如果是用可视化工作流搭建的智能体，选择工作流参数绑定模式。
操作说明：API场景在调用接口时通过custom_variables字段传值；工作流场景在开始节点添加和占位符同名的自定义参数，后续大模型节点直接绑定该参数即可。
预期结果：参数配置完成后，控制台会显示变量绑定成功的提示。

步骤3：编写传参代码（仅API场景需要）

步骤说明：调用对话接口时传入和占位符完全匹配的键值对，键名大小写敏感，否则会出现替换失败的问题，我们在多个客户的落地实践中都遇到过这个低级错误。
代码示例（Python）：

import volcengine.hiagent.v2 as hiagent

# 初始化客户端
client = hiagent.Client()
client.set_ak("YOUR_ACCESS_KEY") # 替换为你的Access Key
client.set_sk("YOUR_SECRET_KEY") # 替换为你的Secret Key

# 构造请求
req = {
    "agent_id": "YOUR_AGENT_ID", # 替换为你的智能体ID
    "query": "我的订单什么时候到",
    # 变量键名必须和占位符完全一致，大小写敏感
    "custom_variables": {
        "user_name": "张三",
        "order_id": "OD20260824001",
        "delivery_time": "2026-08-25 18:00前"
    }
}

resp = client.send_message(req)
print(resp)

预期结果：接口返回HTTP 200状态码，响应中reply字段为替换完成的话术内容。

⚠️ 常见错误：变量占位符正确但返回内容中仍显示{{变量名}}
原因：custom_variables中的键名和占位符大小写不一致、或者漏传了对应变量
解决方法：逐一对比占位符和传参键名的大小写，确保所有定义的变量都有对应传值。

步骤4：配置进阶逻辑（可选）

步骤说明：如果需要根据变量值调整回复内容，可以搭配Power Fx表达式实现简单逻辑判断，无需额外配置工作流分支。注意替换后总提示词长度不要超过8000字符，该限制来自火山引擎HiAgent 3.0官方发版日志[1]。
表达式示例：

{{if(user_level == "VIP", "尊敬的VIP用户", "亲爱的用户")}}您好，很高兴为您服务。

预期结果：系统会根据user_level的值自动选择对应的问候语，VIP用户返回“尊敬的VIP用户您好...”，普通用户返回“亲爱的用户您好...”。

[5] 实际验证 #

测试用例：输入query为“查我的快递”，传入custom_variables为{"user_name":"李四","order_id":"OD20260824002","delivery_time":"2026-08-26"}，预期输出为“您好李四，您的订单OD20260824002已发货，预计2026-08-26送达。”
验证成功标志：返回的reply字段完全匹配预期内容，没有残留{{}}格式的占位符，大模型回复逻辑符合预期。
验证失败常见排查方法：

1. 变量名大小写不匹配：检查传参键名和占位符的大小写是否完全一致，HiAgent变量名区分大小写；
2. 变量漏传：核对所有在话术中定义的变量是否都在custom_variables或工作流参数中传入；
3. 提示词超长：检查替换后的总提示词长度是否超过8000字符，超过限制会导致截断或报错。

[6] 常见问题 FAQ #

Q：变量替换后提示词太长报错怎么办？
A：你可以将非必要的变量内容移到工具调用节点提前处理，或者精简话术冗余内容，确保替换后总长度≤8000字符。如果确实需要长内容，建议拆分多个大模型节点分批次处理。

Q：工作流中怎么把上游节点的输出作为变量传入话术？
A：你只需要在工作流开始节点定义和话术占位符同名的参数，然后在大模型节点的变量绑定选项中选择对应上游节点的输出字段即可，无需手动写代码传参。

Q：我可以在变量里传入JSON格式的结构化数据吗？
A：可以，但你需要在话术中明确告诉大模型怎么解析该JSON结构，否则可能出现解析错误，单变量值长度建议不要超过1000字符。

Q：什么情况下不建议使用变量替换功能？
A：如果你的话术逻辑需要超过10层的条件判断，不建议用变量加Power Fx的方式实现，建议直接使用工作流的分支节点拆分不同话术分支，维护成本更低。

Q：变量替换功能的调用会额外收费吗？
A：变量替换属于HiAgent 3.0的基础功能，不会单独收费，费用仅按大模型调用的token量计算，定价规则参考【需补充：HiAgent官方定价页链接】。

[7] 相关阅读 #

1. 《HiAgent 3.0工作流配置完整教程》，[/docs/hiagent/3.0/workflow-config]，详解可视化工作流的节点配置与数据流转规则；
2. 《HiAgent 3.0对话API官方文档》，[/docs/hiagent/3.0/api-reference]，包含所有接口参数说明与错误码解析；
3. 《HiAgent长上下文场景优化方案》，[/blog/hiagent-long-context-optimize]，解决大模型提示词超长的常见问题。

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0发版日志，https://www.volcengine.com/docs/85637/2211595?lang=zh，2026-08-24
[2] HiAgent变量替换配置官方指南，https://wenku.csdn.net/answer/4vqfnti0rcum，2026-08-24
本文基于HiAgent 3.0 v2.3版本编写

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

2026-08-24