HiAgent自定义规则清理：批量删除操作指南与配额优化

[1] 一句话结论 #

本指南将介绍HiAgent批量删除自定义规则的两种实操方法，帮你快速清理冗余规则释放配额。

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

适用场景

1. 自定义规则数量接近上限（HiAgent单账号默认自定义规则配额100条，数据来源：火山引擎HiAgent官方产品文档），需要快速清理冗余规则释放配额的场景
2. 规则迭代后需要批量下线旧版本规则的场景
3. 测试环境批量清理测试生成的无效规则的场景

不适用场景

1. 需要保留规则操作审计日志超过180天的场景：规则删除后日志仅保留180天，建议参考【HiAgent规则归档方案】处理
2. 规则被其他流程/业务模块引用的场景：直接删除会导致业务报错，建议先执行关联关系排查再处理
3. 需要对删除规则做灰度回滚的场景：删除后规则无法直接恢复，建议参考【HiAgent规则灰度下线方案】操作

[3] 前置准备 #

• 火山引擎HiAgent账号，拥有规则管理权限（IAM权限：HiAgentFullAccess 或 HiAgentRuleWrite权限）
• 开发环境：Python 3.8+，如需API调用需安装火山引擎Python SDK v2.0.1及以上版本
• 已获取待删除规则ID列表（可从控制台规则管理页导出）
• 预计耗时：控制台操作5分钟以内，API批量操作10分钟以内

[4] 分步实现 #

步骤1：控制台查看自定义规则列表与配额使用情况

步骤说明：先确认当前规则总数和冗余规则范围，避免误删线上生效规则，跳过这一步可能导致业务可用率受影响。
操作：登录火山引擎控制台，进入HiAgent产品页，左侧菜单栏选择「规则管理」-「自定义规则」，页面顶部可查看当前配额使用情况。
预期结果：看到所有自定义规则的ID、名称、生效状态、引用次数。

⚠️ 常见错误：直接筛选名称包含"测试"的规则就删除，忽略了引用次数不为0的规则
原因：被业务引用的规则删除后会导致对应请求触发默认兜底逻辑，可能返回错误结果
解决方法：删除前先筛选「引用次数=0」的规则，优先清理这部分无关联的冗余规则

步骤2：控制台批量勾选并删除规则

步骤说明：对于规则数量少于50条的场景，用控制台可视化操作更简单，不需要写代码。
操作：勾选需要删除的规则（单次最多勾选20条），点击页面顶部「批量删除」按钮，在弹出的确认框中输入DELETE后点击确认。
预期结果：页面弹出"删除成功"提示，对应规则从列表中消失，配额使用数量减少对应条数。

步骤3：获取API访问密钥与SDK安装

步骤说明：对于规则数量超过50条，或者需要定期自动化清理的场景，用API操作效率更高，跳过这一步无法调用官方开放接口。
操作：

1. 访问火山引擎密钥管理页获取AccessKey ID和AccessKey Secret
2. 执行pip命令安装SDK：

pip install volcengine-python-sdk>=2.0.1

预期结果：pip执行完成无报错，执行pip list能看到volcengine-python-sdk对应版本。

⚠️ 常见错误：使用旧版本v1.x的SDK调用DeleteRuleTemplates接口返回404
原因：旧版本SDK未集成HiAgent规则管理相关接口
解决方法：升级SDK到2.0.1及以上版本，参考官方文档更新接口调用域名为hiagent.volcengineapi.com

步骤4：调用API批量删除规则

步骤说明：通过传入规则ID列表批量删除，单次最多支持删除100条，比控制台操作效率更高。
代码示例：

from volcenginesdkhiagent import HiAgentClient, DeleteRuleTemplatesRequest
from volcenginesdkcore import Config

# 初始化客户端，替换为自己的密钥信息
config = Config(
    access_key_id="YOUR_ACCESS_KEY_ID",
    access_key_secret="YOUR_ACCESS_KEY_SECRET",
    region="cn-beijing"
)
client = HiAgentClient(config)

# 构造请求，替换为你的待删除规则ID列表
req = DeleteRuleTemplatesRequest(
    template_ids=["rule-xxx1", "rule-xxx2", "rule-xxx3"]
)

# 发起请求
resp = client.delete_rule_templates(req)
print(resp)

预期结果：返回HTTP 200状态码，响应体中SuccessIds字段包含所有成功删除的规则ID，FailedIds字段为空。

[5] 实际验证 #

测试用例：传入2条引用次数为0的测试规则ID执行删除操作
输入：template_ids = ["test-rule-001", "test-rule-002"]
预期输出：HTTP 200，SuccessIds = ["test-rule-001", "test-rule-002"]，FailedIds = []
验证成功标志：回到控制台规则管理页，对应的两条测试规则已消失，配额使用量减少2。
验证失败常见原因及排查方法：

1. 返回403 PermissionDenied：当前账号没有规则删除权限，需要联系管理员开通HiAgentRuleWrite权限
2. 返回400 InvalidParameter.TemplateIdNotFound：传入的规则ID不存在，检查ID是否拼写正确，是否属于当前账号
3. 返回400 ResourceInUse.TemplateReferenced：规则被其他资源引用，先解除关联后再删除

[6] 常见问题 FAQ #

• 问题：HiAgent单账号自定义规则数量上限是多少？
  答案：默认配额是100条/账号，数据来源是火山引擎HiAgent官方产品文档。如果需要更高配额可以提交工单申请提升，最高可支持1000条/账号。
• 问题：删除后的规则可以恢复吗？
  答案：不可以，规则删除后无法直接恢复，建议删除前先导出规则配置做好备份，避免误删。
• 问题：什么情况下不建议使用批量删除功能？
  答案：如果你的规则都在生产环境生效且引用次数都大于0，不建议批量删除，容易引发业务故障，建议逐条评估后下线。
• 问题：单次API批量删除最多支持多少条规则？
  答案：单次最多支持删除100条规则，如果需要删除超过100条，可以分批调用接口。
• 问题：我可以跳过导出规则列表的步骤直接删除吗？
  答案：不建议跳过，导出规则列表可以方便你后续回溯删除的规则信息，避免误删后无据可查。
• 问题：控制台批量删除单次最多选多少条？
  答案：控制台单次最多支持勾选20条规则删除，超过20条建议用API操作更高效。

[7] 相关阅读 #

• 《HiAgent自定义规则创建指南》[/docs/87053/2571160]：介绍如何创建自定义规则，适合规则迭代场景参考
• 《HiAgent权限配置最佳实践》[/docs/87053/2571165]：讲解HiAgent相关IAM权限配置方法，解决权限报错问题
• 《HiAgentAPI接口参考文档》[/docs/87053/2571167]：包含所有HiAgent开放接口的参数说明与示例代码
• 《HiAgent规则配额调整申请指南》[/docs/87053/2571170]：介绍如何申请提升自定义规则配额的流程

[8] 参考资料 #

[1] DeleteRuleTemplates - 删除规则模板，https://docs.volcengine.com/docs/87053/2571167?lang=zh，2026年08月24日
[2] HiAgent 2.0正式发布，让Agent在千企万厂“持证上岗”，http://m.toutiao.com/group/7519794892998967871/?upstream_biz=VolcEngine，2026年08月24日
本文基于HiAgent V2.1.0版本编写

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

2026-08-24