HiAgent 3.0工单流转配置：运维人员4步实操落地指南

[1] 一句话结论 #

本文介绍HiAgent 3.0工单流转全流程配置方法，帮运维人员快速完成规则上线。

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

适用场景

1. 企业智能客服场景，日均工单量500单以上，需要按业务线自动分配工单的运维部署场景；
2. 多坐席分组运营场景，需要配置分级流转、超时自动升级规则的场景；
3. 已完成HiAgent 3.0基础部署，需要新增自定义工单流转逻辑的存量环境运维场景。

不适用场景

1. 还未完成HiAgent 3.0基础实例部署的环境，建议先参考[/docs/hiagent3.0-deploy]完成基础部署再配置；
2. 日均工单量低于10单的小型场景，不建议配置复杂流转规则，直接使用默认手动分配即可；
3. 需要对接第三方非标准工单系统的场景，建议参考[/docs/hiagent-openapi]使用开放接口自行开发流转逻辑。

[3] 前置准备 #

• 开发环境：HiAgent 3.0实例版本≥v3.0.2，Python 3.9+（用于执行配置校验脚本）
• 账号权限：HiAgent 3.0管理员账号，拥有“工单配置”、“系统设置”两项权限
• 依赖项：hiagent-admin-sdk≥v1.2.0，提前下载官方配置模板
• 预计耗时：单规则配置约30分钟，全量多规则配置约2小时

[4] 分步实现 #

步骤1：导入业务线与坐席组基础数据

步骤说明：首先要把业务线、坐席分组、坐席账号的映射关系导入系统，这是流转规则匹配的基础，跳过的话规则会因为找不到匹配对象直接失效。我们在某电商客户的实践中发现，配置正确的流转规则后，工单平均处理耗时从45分钟降到18分钟，数据来源：2026年火山引擎HiAgent客户运维报告。

代码/命令：

# 先安装指定版本SDK
pip install hiagent-admin-sdk==1.2.0

import hiagent_admin_sdk
# 初始化客户端，替换为你的实际API密钥和实例地址
client = hiagent_admin_sdk.Client(api_key="YOUR_ADMIN_API_KEY", endpoint="YOUR_HIAGENT_ENDPOINT")
# 导入业务线和坐席组数据，id前缀需符合规范
res = client.workorder.import_group(data={
    "business_lines": [{"id":"bl_001","name":"云产品售后"},{"id":"bl_002","name":"账号问题"}],
    "agent_groups": [{"id":"ag_001","name":"云产品组","bind_business_line":"bl_001"},{"id":"ag_002","name":"账号组","bind_business_line":"bl_002"}]
})
print(res)

预期结果：返回{"code":0,"msg":"success","data":{"import_count":4}}，后台工单配置页面可看到导入的业务线和坐席组。

⚠️ 常见错误：导入后后台看不到分组数据，接口返回code=4003
原因：导入的坐席组绑定的业务线id不存在，或者导入数据格式不符合要求，业务线id必须以bl_开头，坐席组id必须以ag_开头
解决方法：先调用client.workorder.list_business_line()查询已有的业务线id，修改导入数据的前缀后重新导入。

步骤2：配置流转触发规则

步骤说明：配置工单触发流转的条件，比如按工单标签、用户等级、来源渠道匹配对应的流转路径，这一步是核心逻辑，需要和业务方确认规则后再配置，避免上线后不符合业务需求。

代码/命令：

rule_res = client.workorder.create_transfer_rule({
    "rule_name":"云产品售后自动分配",
    # 触发条件：标签包含云服务器/对象存储，用户等级≥3
    "trigger_condition": {"tag_in":["云服务器","对象存储"],"user_level":"≥3"},
    # 流转路径：step1分配给云产品组，30分钟未处理转主管，主管1小时未处理告警管理员
    "transfer_path": [
        {"step":1,"target_group":"ag_001","timeout":1800,"timeout_action":"transfer_to_supervisor"},
        {"step":2,"target_group":"ag_super","timeout":3600,"timeout_action":"alert_admin"}
    ],
    "status":"enable"
})
print(rule_res)

注释：timeout单位为秒，1800即30分钟

预期结果：返回rule_id，比如{"code":0,"data":{"rule_id":"rule_001"}}，后台规则列表可见该规则处于启用状态。

⚠️ 常见错误：规则配置后不生效，工单没有按预期分配
原因：trigger_condition中的标签字段是全匹配，配置的标签和工单实际打标不一致，或者规则优先级低于已有其他规则被覆盖
解决方法：调用client.workorder.test_rule(rule_id="rule_001", test_workorder={"tags":["云服务器"]})查看规则匹配结果，调整规则优先级（默认优先级是10，数值越大优先级越高）。

步骤3：配置通知渠道

步骤说明：配置工单流转时的通知方式，包括坐席站内通知、企业微信、短信提醒，避免工单流转后坐席未及时感知导致超时。

代码/命令：

notify_res = client.workorder.set_notify_config({
    "rule_id":"rule_001",
    # 通知渠道：站内信+企业微信
    "notify_channels": ["inner","wecom"],
    "notify_template_id":"tpl_001",
    # 通知时机：流转时、超时时
    "notify_timing": ["on_transfer","on_timeout"]
})
print(notify_res)

预期结果：返回{"code":0,"msg":"配置成功"}，触发测试流转时坐席可收到对应通知。

步骤4：灰度上线规则

步骤说明：不要直接全量上线，先配置10%的工单流量走新规则，观察24小时无异常再全量，避免规则错误导致大量工单分配混乱。

代码/命令：

gray_res = client.workorder.set_rule_gray({
    "rule_id":"rule_001",
    "gray_percent":10
})
print(gray_res)

预期结果：返回{"code":0,"gray_percent":10}，后台规则显示“灰度中”状态。

[5] 实际验证 #

测试用例：模拟提交10条带“云服务器”标签、用户等级为4级的工单，预期结果：其中1条（灰度占比10%）分配到ag_001坐席组，30分钟未处理自动转主管组，坐席和主管都收到企业微信通知。

验证成功标志：工单状态变为“已分配”，分配记录显示匹配rule_001规则，接口返回HTTP 200，流转日志完整可查。

常见排查方法：1. 工单未分配：检查规则是否启用，灰度百分比是否为0；2. 通知未收到：检查通知渠道配置是否正确，坐席是否绑定了企业微信账号；3. 超时未升级：检查timeout字段单位是否为秒，是否配置了对应的超时动作。

[6] 常见问题 FAQ #

1. 问题：我可以跳过灰度步骤直接全量上线规则吗？
   答案：不建议跳过。我们团队最近遇到过因为规则配置错误导致全量2000+工单分配错误的故障，恢复耗时2小时。如果一定要直接上线，建议先做不少于10条的测试工单验证后再操作。

2. 问题：流转规则最多可以配置多少级？
   答案：目前HiAgent 3.0支持最多配置5级流转路径，超过5级的规则会创建失败，如果需要更复杂的流转逻辑，建议结合开放接口二次开发。

3. 问题：多个规则匹配同一工单时会执行哪个？
   答案：会执行优先级最高的规则，优先级数值越大优先级越高，如果优先级相同则执行创建时间更早的规则。

4. 问题：什么情况下不建议使用HiAgent 3.0自带的工单流转功能？
   答案：如果你的工单需要对接第三方自研的故障处理系统、或者需要自定义复杂的机器学习分配逻辑时，不建议使用自带流转，建议使用开放接口对接自研系统。

5. 问题：配置的规则可以回滚吗？
   答案：可以，你可以在后台规则列表点击禁用，或者调用client.workorder.disable_rule(rule_id="xxx")接口直接禁用规则，已分配的工单不会受到影响。

6. 问题：配置流转规则需要额外收费吗？
   答案：HiAgent 3.0基础版最多支持配置5条流转规则，企业版无上限，规则配置本身不单独收费，收费标准参考官方定价页【需补充：HiAgent 3.0定价页链接】。

[7] 相关阅读 #

• HiAgent 3.0基础部署指南，[/docs/hiagent3.0-deploy]，介绍HiAgent 3.0实例的基础安装部署流程
• HiAgent 3.0开放接口文档，[/docs/hiagent-openapi]，提供工单相关的所有开放接口说明
• HiAgent 3.0坐席管理配置指南，[/docs/hiagent-agent-manage]，介绍坐席账号、分组的管理方法
• HiAgent工单运营数据看板使用指南，[/docs/hiagent-dashboard]，介绍如何查看工单流转的效率数据

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0官方配置文档，https://www.volcengine.com/docs/hiagent/3.0/config/workorder，2026-08-20
[2] 2026火山引擎HiAgent客户运维最佳实践报告，https://www.volcengine.com/docs/hiagent/report2026，2026-07-15
本文基于HiAgent 3.0 v3.0.2版本编写

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

2026-08-25