跳到主要内容

配置 Agent Hooks

Hooks 功能允许您在对话前进行拦截与控制，支持意图检测、条件触发、优先级控制等功能。

功能特点​

  • 实时意图检测：如付费意愿、投诉、咨询等
  • 条件触发动作：Webhook 调用、阻止回复、消息替换等
  • 优先级控制：多个 Hook 可按 priority 顺序依次执行，数值越小优先级越高
  • 可扩展性：支持多种条件类型和动作类型，便于扩展业务逻辑

配置结构​

基础配置​

参数类型必传说明
hooksArray<Object>否对话前拦截钩子配置列表。
hooks[].nameString是Hook 名称，用于标识和调试。
hooks[].phaseString是执行阶段，当前仅支持：beforeChat（对话前）。
hooks[].priorityInt否优先级，数值越小优先级越高，默认 1。
hooks[].conditionObject是触发条件配置。
hooks[].actionsArray<Object>是触发动作列表。

触发条件​

条件类型​

参数类型必传说明
condition.typeString是条件类型，可选：intentDetection（意图检测）、comparison（比较条件）。

意图检测条件​

当 condition.type 为 intentDetection 时：

参数类型必传说明
condition.intentsArray<Object>是意图检测配置列表。
condition.intents[].intentString是意图名称。
condition.intents[].confidenceThresholdDouble是置信度阈值，范围 0.0–1.0。

配置示例：

JSON
{
  "type": "intentDetection",
  "intents": [
    { "intent": "付费意愿", "confidenceThreshold": 0.1 },
    { "intent": "升级会员", "confidenceThreshold": 0.1 },
    { "intent": "充值", "confidenceThreshold": 0.5 }
  ]
}

比较条件​

当 condition.type 为 comparison 时：

参数类型必传说明
condition.conditionsArray<Object>是比较条件列表。
condition.conditions[].propertyString是属性名，可选：conversationTurns（对话轮数）、conversationDays（对话天数）。
condition.conditions[].operatorString是比较操作符，可选：>、>=、<、<=、==。
condition.conditions[].valueInt是比较值。

配置示例：

JSON
{
  "type": "comparison",
  "conditions": [
    { "property": "conversationTurns", "operator": ">=", "value": 20 }
  ]
}

触发动作​

动作类型​

参数类型必传说明
actions[].typeString是动作类型，可选：webhook（调用外部 API）、stopReply（阻止回复）。

Webhook 动作​

当 actions[].type 为 webhook 时：

参数类型必传说明
actions[].urlString是回调 URL 地址。

配置示例：

JSON
{
  "type": "webhook",
  "url": "https://api.customer.com/payment-intent"
}
回调详情

Webhook 触发时的回调数据结构和处理方式，请参见 Hooks Webhook 回调。

stopReply​

当 actions[].type 为 stopReply 时，无需额外参数。

配置示例：

JSON
{
  "type": "stopReply"
}

配置场景示例​

付费意图检测示例​

检测用户付费意图，触发 Webhook 并阻止回复：

JSON
{
  "hooks": [
    {
      "name": "detectPaymentIntent",
      "phase": "beforeChat",
      "priority": 1,
      "condition": {
        "type": "intentDetection",
        "intents": [
          { "intent": "付费意愿", "confidenceThreshold": 0.8 },
          { "intent": "升级会员", "confidenceThreshold": 0.8 },
          { "intent": "充值", "confidenceThreshold": 0.8 }
        ]
      },
      "actions": [
        {
          "type": "webhook",
          "url": "https://api.customer.com/payment-intent"
        },
        {
          "type": "stopReply"
        }
      ]
    }
  ]
}

对话轮数监控示例​

当对话轮数达到阈值时触发 Webhook：

JSON
{
  "hooks": [
    {
      "name": "conversationTurnsMonitor",
      "phase": "beforeChat",
      "priority": 2,
      "condition": {
        "type": "comparison",
        "conditions": [
          { "property": "conversationTurns", "operator": ">=", "value": 20 }
        ]
      },
      "actions": [
        {
          "type": "webhook",
          "url": "https://api.customer.com/conversation-alert"
        }
      ]
    }
  ]
}

对话轮数限制示例​

当对话轮数超过阈值时停止回复：

JSON
{
  "hooks": [
    {
      "name": "conversationTurnsLimit",
      "phase": "beforeChat",
      "priority": 1,
      "condition": {
        "type": "comparison",
        "conditions": [
          { "property": "conversationTurns", "operator": ">", "value": 50 }
        ]
      },
      "actions": [
        {
          "type": "stopReply"
        }
      ]
    }
  ]
}

工作流程​

对话前拦截（beforeChat）​

  1. 用户输入：用户发送消息
  2. 条件判断：系统根据配置的条件进行检测
  3. 动作执行：条件满足时执行相应动作
  4. 流程控制：
    • 如果执行了 stopReply → 阻止 Agent 回复，流程终止
    • 否则 → 继续正常对话流程

注意事项​

  1. 对话统计功能：若要使用 conversationTurns（对话轮数）和 conversationDays（对话天数）进行条件判断，需在创建 Agent 时将 conversationStatsEnabled 设置为 true
  2. 执行优先级：当配置多个 Hook 时，系统按 priority 数值从小到大的顺序依次执行，数值越小优先级越高