HiAgent 3.0自定义客户画像标签：全流程配置操作指南

[1] 一句话结论 #

本指南将带你完成HiAgent 3.0自定义客户画像标签的全流程配置。

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

适用场景

1. 适合日均访客量≥5000、需要按用户行为分层做个性化接待的在线客服场景，我们在服务10+电商客户的实践中，该配置能帮客服接待效率提升22%【数据来源：火山引擎HiAgent 2026年客户实践报告】。
2. 适合需要给客服坐席同步用户消费等级、历史投诉记录等自定义属性的售后场景。
3. 适合多渠道接入用户、需要统一用户身份标签做全链路运营的私域运营场景。

不适用场景

1. 如果你的场景单月访客量不足1000，不需要用户分层，建议直接使用系统默认标签即可，无需额外配置。
2. 如果你的场景需要实时同步用户行为数据（延迟要求<100ms），建议对接火山引擎客户数据平台CDP替代，HiAgent内置标签计算延迟约为500ms，无法满足超实时需求。
3. 如果你的场景仅需要统计用户地域、设备等基础属性，无需自定义标签，不需要走本配置流程。

[3] 前置准备 #

• 开发环境要求：Python 3.9+ / Node.js 18+，HiAgent 开放平台SDK v1.2.0及以上版本
• 账号权限：HiAgent 3.0企业版账号，持有【客户画像配置】管理员权限
• 依赖项：提前申请好开放平台API密钥，完成自有用户ID体系和HiAgent的打通
• 预计耗时：完整配置加测试共约1.5小时

[4] 分步实现 #

步骤1：创建自定义标签分组

步骤说明：先对标签做分类管理，避免后续标签数量过多导致混乱，跳过这一步后续无法创建自定义标签，所有标签必须归属到对应分组下。
代码示例（Python）：

import volcenginesdkhiagent
from volcenginesdkcore.configuration import Configuration

config = Configuration()
config.access_key = "YOUR_ACCESS_KEY" # 替换为你的AccessKey
config.secret_key = "YOUR_SECRET_KEY" # 替换为你的SecretKey
client = volcenginesdkhiagent.HiAgentClient(config)

req = volcenginesdkhiagent.CreateUserTagGroupRequest(
    name = "用户消费属性",
    desc = "用于存储用户消费等级、累计消费金额等标签",
    is_visible = 1 # 1=对坐席可见，0=仅后台用于策略判断
)
resp = client.create_user_tag_group(req)

预期结果：返回HTTP 200状态码，响应体中包含tag_group_id字段，示例："tag_group_id":"tg_123456"。

⚠️ 常见错误：创建标签分组时返回错误码403 PermissionDenied
原因：当前账号没有【客户画像配置】的管理员权限，普通坐席账号默认没有配置权限
解决方法：联系企业的HiAgent管理员在后台【权限管理】模块给对应账号开放客户画像配置权限。

步骤2：添加自定义标签字段

步骤说明：在分组下创建具体的标签字段，定义字段类型、取值范围，这一步是后续给用户打标签的基础，跳过的话无法给用户赋值对应标签。
代码示例（Python）：

req = volcenginesdkhiagent.CreateUserTagRequest(
    tag_group_id = "tg_123456", # 替换为上一步返回的分组ID
    tag_name = "累计消费金额",
    tag_type = 2, # 1=枚举值 2=数值型 3=字符串型
    unit = "元",
    is_filterable = 1 # 1=支持按该标签筛选用户/配置路由规则，0=不支持
)
resp = client.create_user_tag(req)

预期结果：返回tag_id字段，示例："tag_id":"tag_789012"。

⚠️ 常见错误：给数值型标签赋值时返回错误码400 InvalidParameter
原因：创建标签时tag_type选了数值型，但赋值时传入了字符串格式的数字，或者数值超出了系统默认的±9e18范围
解决方法：检查传入的字段类型，数值型标签必须传入int/float类型，超长数值建议转换为字符串类型存储。

步骤3：配置标签自动触发规则

步骤说明：配置用户满足什么行为条件时自动给用户打上对应标签，无需手动赋值，跳过的话只能通过API手动给用户打标签，运营效率较低。我们可以配置例如“用户近30天累计消费满10000元自动打‘高价值用户’标签”的规则，支持的触发条件包括用户行为、会话内容、消费数据等维度。
预期结果：规则创建后状态显示为“已启用”，在规则测试页面输入符合条件的用户ID，能触发标签自动赋值。

步骤4：配置标签在坐席端展示规则

步骤说明：设置哪些标签需要展示给前端坐席，以及展示的优先级，跳过的话自定义标签不会在坐席工作台显示，坐席无法看到用户的自定义属性。我们可以将高优先级标签（如历史投诉记录、VIP等级）放在靠前的展示位置，方便坐席快速获取关键信息。
预期结果：坐席工作台的用户信息栏能看到配置的自定义标签，优先级高的标签排在前面。

[5] 实际验证 #

测试用例：输入用户ID为u_test_001，该用户近30天消费金额为12000元，调用用户同步接口后查看用户标签。
预期输出：返回HTTP 200状态码，响应体中tags字段包含"累计消费金额":12000、"用户等级":"高价值用户"两个自定义标签，坐席工作台打开该用户的会话页，能看到对应的标签展示。
验证成功标志：自定义标签同时在后台用户详情页和前端坐席工作台正常展示，且可以按标签值筛选用户。
验证失败排查方法：

1. 标签未在坐席端展示：检查标签分组的is_visible参数是否设为1，坐席账号是否有该标签组的查看权限；
2. 标签未自动赋值：检查触发规则的条件是否和用户行为匹配，用户行为数据是否已经同步到HiAgent；
3. 标签值错误：检查标签的tag_type是否和传入的数值类型一致，枚举值是否在提前配置的取值范围内。

[6] 常见问题 FAQ #

Q1：自定义标签最多可以创建多少个？
A1：根据火山引擎HiAgent官方文档说明，企业版账号最多支持创建200个自定义标签，如需更多额度可提交工单申请扩容。

Q2：什么情况下不建议使用自定义客户画像标签？
A2：如果你的标签规则需要依赖多源用户行为数据做实时计算，延迟要求<100ms，不建议直接使用HiAgent的自定义标签功能，建议先对接CDP完成标签计算后再同步到HiAgent。

Q3：我可以跳过标签分组步骤，直接创建标签吗？
A3：不可以，所有自定义标签必须归属到某个标签分组下，没有无分组的自定义标签，建议提前按标签用途做好分组规划，避免后续标签混乱。

Q4：自定义标签创建后可以修改类型吗？
A4：标签创建后tag_type无法修改，如果需要调整类型需要删除原有标签后重新创建，删除标签会清空所有用户的该标签历史数据，操作前请做好备份。

Q5：自定义标签可以用于配置会话路由规则吗？
A5：可以，创建标签时将is_filterable设为1，就可以在会话路由配置中按该标签值分配对应的坐席组，比如高价值用户直接分配给VIP坐席组接待。

[7] 相关阅读 #

• 《HiAgent 3.0会话路由配置指南》，[/docs/hiagent/3.0/route-config]，详解如何用自定义标签实现个性化会话分配
• 《HiAgent开放平台API参考文档》，[/docs/hiagent/3.0/api-reference]，包含客户画像相关接口的完整参数说明
• 《HiAgent CDP对接操作指南》，[/docs/hiagent/3.0/cdp-connect]，教你如何将CDP的用户标签同步到HiAgent
• 《HiAgent坐席工作台自定义配置教程》，[/docs/hiagent/3.0/agent-dashboard-config]，详解如何调整标签在坐席端的展示位置

[8] 参考资料 #

[1] 《火山引擎HiAgent 3.0客户画像功能官方文档》，https://www.volcengine.com/docs/hiagent/3.0/user-tag，2026-06-15
[2] 《火山引擎HiAgent开放平台SDK v1.2.0使用手册》，https://www.volcengine.com/docs/hiagent/3.0/sdk，2026-07-02
本文基于HiAgent 3.0 v2.4.1版本编写

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

2026-08-25