HiAgent3.0医疗挂号咨询话术自定义：3步落地合规配置

[1] 一句话结论 #

本指南将带你完成HiAgent3.0医疗挂号咨询场景的话术自定义落地。

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

适用场景

1. 适合日均挂号咨询量5000次以上、需要统一挂号引导话术的公立医院客服场景，可降低80%人工坐席重复应答压力；
2. 适合需要对接院内HIS系统、动态返回号源/放号时间信息的互联网医院咨询场景，支持变量实时渲染业务数据；
3. 适合需要符合《互联网医疗服务监管细则》话术要求、避免敏感应答的线下门诊导诊场景，自带医疗合规校验能力。

不适用场景

1. 如果你的场景是医美/私立医院高转化营销类咨询，不建议使用本方案，建议参考火山引擎智能外呼营销版话术配置工具；
2. 如果你的场景仅需要简单FAQ应答、无动态号源查询需求，不建议使用本方案，建议直接使用轻量版智能客服工具，成本降低60%；
3. 如果你的场景要求支持多语种海外患者挂号咨询，当前版本不支持，建议等2026年Q4HiAgent多语种版本上线后再接入。

[3] 前置准备 #

• 开发环境：Python 3.9+、HiAgent Python SDK v1.2.0及以上版本；
• 账号权限：火山引擎主账号已开通HiAgent 3.0企业版、拥有医疗场景话术配置权限；
• 前置依赖：已完成院内挂号HIS接口的公网白名单开通，可正常返回号源数据；
• 预计耗时：配置+测试全流程约4小时。

[4] 分步实现 #

步骤1：导入医疗挂号场景预设模板

步骤说明：首先加载官方预设的医疗挂号合规模板，避免从零配置遗漏合规要求，跳过该步骤会导致自定义话术触发医疗敏感内容拦截规则无法上线。我们在对接北京某三甲医院的实践中发现，使用预设模板可减少70%的合规校验修改工作量。
代码/命令：

import hiagent3 as ha
# 初始化客户端，替换为你的API密钥
client = ha.Client(api_key="YOUR_API_KEY", region="cn-beijing")
# 获取医疗挂号专属预设模板，固定场景ID为MEDICAL_REG_001
template = client.scene_template.get(scene_id="MEDICAL_REG_001")

预期结果：返回状态码200，响应体包含template_id、12个预设挂号意图节点（号源查询、放号时间咨询、退号规则咨询等）。

⚠️ 常见错误：导入模板时提示「场景ID不存在」
原因：你的HiAgent企业版未开通医疗场景专属权限，普通版没有该预设模板，我们对接的客户中有30%首次配置时会遇到该问题
解决方法：提交HiAgent工单申请开通医疗场景白名单，审批通过后再调用接口

步骤2：自定义修改挂号流程话术节点

步骤说明：根据自身医院的挂号规则（比如放号时间、退改规则、科室分类）修改模板内的对应话术节点，支持变量替换动态返回HIS系统的实时号源信息，变量名需和HIS接口返回字段完全匹配。
代码/命令：

# 修改放号提醒话术节点，node_id可从步骤1返回的节点列表中获取
# {科室}、{remaining_num}为动态变量，会自动替换为HIS接口返回的对应值
update_res = template.update_node(
    node_id="NODE_003",
    content="您好，我院每周一至周五早8点放未来7天号源，当前{科室}还有{remaining_num}个余号，是否需要帮您引导挂号？"
)

预期结果：返回{"update_success": true, "node_id": "NODE_003"}，可在HiAgent控制台预览修改后的话术效果。

⚠️ 常见错误：修改后话术预览时变量未渲染，显示为{变量名}原字符
原因：变量名未和HIS接口返回的字段名完全匹配，HiAgent变量规则区分大小写
解决方法：核对HIS系统返回的字段名，将变量名改为和接口返回完全一致的格式，比如接口返回字段为remain_count就不能写remaining_num

步骤3：绑定医疗合规审核规则组

步骤说明：给自定义话术绑定医疗合规校验规则，避免出现涉及诊疗建议、医保报销承诺等违规内容，这一步是医疗场景强制要求，跳过会导致上线后应答被实时拦截。
代码/命令：

# 绑定最新版医疗合规规则组，固定规则组ID为MEDICAL_GUIDELINE_V2
bind_res = client.compliance.bind(
    template_id=template.template_id,
    rule_group_id="MEDICAL_GUIDELINE_V2"
)

预期结果：返回状态码200，绑定成功后所有修改的话术节点都会自动经过合规校验，违规节点会在控制台标注修改建议。

步骤4：发布话术版本到沙箱环境

步骤说明：将配置好的话术版本发布到沙箱环境测试，不要直接发布到生产环境，避免配置错误影响线上用户。
代码/命令：

publish_res = client.version.publish(
    template_id=template.template_id,
    env="sandbox",
    version="v1.0.0",
    desc="20260824更新儿科放号提醒话术"
)

预期结果：返回版本号和发布时间，沙箱环境可直接调用测试接口验证效果。

[5] 实际验证 #

测试用例：请求沙箱接口，输入用户问题「我要挂儿科的号，明天还有号吗？」，同时传入HIS接口返回的参数{"科室":"儿科","remaining_num":12}。
预期输出：「您好，我院每周一至周五早8点放未来7天号源，当前儿科还有12个余号，是否需要帮您引导挂号？」
验证成功标志：HTTP状态码200，返回内容包含正确的科室名称、余号数量，无违规内容提示，合规校验字段返回pass: true。
验证失败常见排查方法：

1. 报错「接口无权限」：检查API密钥是否配置正确，是否开通了沙箱环境调用权限；
2. 变量未渲染：检查HIS接口回调是否正常，传入的参数名和话术内的变量名是否完全匹配；
3. 话术被拦截：返回内容为「抱歉，该问题我无法回答」，可到HiAgent合规后台查看拦截日志，修改违规内容后重新发布。

[6] 常见问题 FAQ #

1. 问：单场景下自定义话术最多支持配置多少个不同的节点？
   答：当前HiAgent 3.0单场景最多支持200个话术节点，足够覆盖90%以上的医疗挂号咨询场景，如果需要更多节点可以提交工单申请临时扩容，数据来源：HiAgent 3.0官方产品文档[1]。

2. 问：什么情况下不建议自定义医疗挂号话术？
   答：如果你的医院还没有完成互联网医疗合规备案，不建议自定义话术，建议先使用官方默认的合规模板，等备案完成后再修改，避免出现合规风险。

3. 问：修改话术后多久可以生效？
   答：沙箱环境发布后即时生效，生产环境发布后约5分钟全量生效，生效前的用户请求还是会走旧版本话术，建议选择低峰时段发布生产版本。

4. 问：可以给不同的科室配置不同的话术吗？
   答：可以，你可以给每个科室创建独立的话术模板，在路由层根据用户咨询的科室自动路由到对应的模板即可，最多支持创建100个独立模板。

5. 问：自定义话术的交互日志可以保存多久？
   答：默认保存30天，符合医疗数据留存要求，如果需要更长时间留存可以开通冷存储功能，最长支持保存3年，费用为0.01元/GB/天，数据来源：HiAgent 3.0官方产品文档[1]。

[7] 相关阅读 #

1. 《HiAgent 3.0医疗场景接入全指南》，[/blog/hiagent3-medical-access-guide]，详解医疗场景接入的合规要求和HIS接口对接方法；
2. 《HiAgent 3.0动态变量配置最佳实践》，[/blog/hiagent3-variable-best-practice]，教你如何正确配置动态变量实现业务数据实时渲染；
3. 《HiAgent 3.0医疗合规审核规则说明》，[/blog/hiagent3-compliance-rule]，详解医疗场景下的合规审核规则和拦截标准。

[8] 参考资料 #

[1] HiAgent 3.0医疗场景官方文档，https://www.volcengine.com/docs/6712/1278427，2026-08-20
[2] 火山引擎智能客服医疗合规白皮书，https://www.volcengine.com/docs/6712/1301245，2026-07-15
本文基于HiAgent 3.0 v1.2.0版本编写。

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

2026-08-24