任务（Task）

简介

任务（Task） 是 Agent 的主动消息能力：由 Agent 主动向用户发起对话，而不是等待用户先开口。

与常规对话不同，常规对话是"用户提问 → Agent 回答"，而任务是"平台按照你设定的条件，替用户向 Agent 发出一条消息 → Agent 生成回复 → 回复推送给用户"。你在任务中填写的"触发消息"，本质上是代替用户发给 Agent 的一句话，Agent 会像收到真实用户消息一样生成回复，最终用户看到的是 Agent 的回复，而不是触发消息本身。

典型使用场景：

前置条件

• 任务只会发送给已经与 Agent 产生过对话的用户。平台会为每个用户找到其在目标通道上"最后一次活跃"的会话，并在该会话中注入消息。没有会话记录的用户不会收到任务消息（执行明细中记为 NO_CONVERSATION）。
• 若目标通道为第三方集成（如 WhatsApp、Telegram、LINE 等），请确保对应的集成已在「Integrations」中正确配置并处于启用状态；集成被关闭或凭证失效会导致发送失败（CHANNEL_CONFIG_INVALID / CHANNEL_AUTH_FAILED）。
• 任务执行会调用 Agent 的 LLM 生成回复，会正常消耗积分（Credits）。

入口

进入 开发空间 → 智能体 → 选择某个 Agent → 左侧菜单「Tasks」。

任务列表支持：按任务名称搜索、按状态（Status）、触发类型（Trigger）、目标用户（Target）筛选。列表字段说明：

创建任务

点击右上角 New task，在右侧抽屉中完成配置。

1. 基础信息

注意：选择 All users 时会弹出二次确认，因为这意味着向该 Agent 所有通道上的全部用户广播。请务必确认目标会话范围设置合理，避免误发。

支持的目标通道

提示：部分通道因平台协议限制暂不支持服务端主动推送（如 Discord、DingTalk、SoBot），在通道下拉中会置灰并提示原因。自有渠道（Web / Widget 等）的回复会直接写入会话，用户下次打开对话窗口即可看到；IM 通道与客服平台则会通过对应平台的 API 主动推送给用户。

2. 触发方式（Trigger）

触发方式决定"什么时候发"，共三种：

主动 - 定时触发（Active - Scheduled）

由平台按设定的时间表主动发起，适合定期播报、单次通知。

时间按任务所选时区计算。定时任务创建后状态为 WAITING，到达首次执行时间后进入 RUNNING；Once 任务执行完成后自动转为 COMPLETED。

主动 - 事件触发（Active - Event）

由你的业务系统通过 Webhook 调用平台来触发，适合与订单、支付、工单等业务事件联动。

创建任务时选择鉴权方式并填写凭证，平台会自动生成一个唯一的 Webhook URL（创建后可在任务详情中查看）：

Webhook 调用示例

Webhook URL 形如 {平台域名}/bot/proactive-task/webhook/{webhookPath}，请以任务详情中显示的完整地址为准。

                      
                      POST {Webhook URL}
Content-Type: application/json
Authorization: Basic base64(username:password)

{
  "idempotency_key": "order-20260903-0001",
  "target": {
    "channel": "TELEGRAM",
    "user_id": "customer_123"
  },
  "variables": {
    "order_no": "SO-20260903-0001",
    "eta": "9月5日"
  }
}

                    

注意：Webhook 请求成功仅代表"已接收并进入发送队列"，实际发送结果请在执行历史中查看。鉴权失败、任务已停止、目标通道不在任务的目标通道范围内等情况都会返回权限错误。单个 Webhook 地址限流 120 次 / 分钟。

被动 - 用户触发（Passive - User Triggered）

由平台每分钟扫描一次所有目标用户，符合规则的用户即触发发送，适合沉默用户唤醒、高价值用户关怀等场景。

规则配置

点击 Add rule 添加规则，多条规则之间可选择 AND（全部满足）或 OR（任一满足）。

说明：用户属性取自「变量管理 → 用户属性」，按用户逐个取值（用户未设置时取属性默认值），适合按用户画像筛选；自定义属性取自「变量管理 → 自定义变量」，是 Agent 级的统一值，对所有用户相同，适合作为"总开关"类条件。所有规则字段都基于该用户在目标通道上最后活跃的那条会话取值。

消息频控（Message Frequency）

被动触发任务必须设置频控：在设定的窗口内（N 小时 / N 天），同一个用户最多只会被该任务触发一次，避免持续符合规则的用户被反复打扰。

提示：用户最后对话时间（User's last chat time）是"过去"的时间，请使用"已过去 N 单位"类算子；"距今 N 单位之后"类算子只适用于未来时间字段（如订阅到期时间），用在最后对话时间上永远不会命中。

3. 触发消息（Message）

填写要"代替用户"发送给 Agent 的消息内容。Agent 会根据这条消息以及自身的提示词、知识库等生成回复，再推送给用户。

支持使用 {{变量}} 引用以下变量：

示例

• 定时播报：请用简短友好的语气，为我总结今天的行业要闻。
• 沉默唤醒：我已经几天没有来了，请主动问候我，并告诉我最近有什么新功能。
• 事件通知：我的订单 {{event.variables.order_no}} 已发货，预计 {{event.variables.eta}} 送达，请告诉我物流信息并提醒我注意查收。

提示：触发消息是写给 Agent 看的"用户视角"提问，而不是直接展示给用户的文案。如果希望 Agent 尽量原样转述，可以在消息中明确要求，例如"请原样告诉用户：……"。

确认无误后点击 Create。

注意：每个 Agent 同时处于 WAITING / RUNNING 状态的任务最多 10 个，超出后需先停止或等待已有任务完成。

任务状态

查看任务与执行历史

点击列表中的 View 进入任务详情，包含两个 Tab：

• Configuration：任务配置的只读视图。事件触发任务可在此查看 Webhook URL 与鉴权信息。
• Execution History：每次执行的记录，含执行时间、目标数、成功 / 失败数与成功率。

点击某次执行可查看执行明细：各通道的成功 / 失败统计，以及逐条发送记录。失败原因说明：

停止与删除

• Stop：处于 WAITING / RUNNING / ERROR 状态的任务可随时停止，停止后转为 TERMINATED，不可恢复。
• Delete：仅 COMPLETED / TERMINATED 状态的任务可删除，删除时会同步清理执行历史与明细。

常见问题

Q：为什么任务执行成功，但用户看到的内容不是我填写的触发消息？
触发消息是"代替用户发给 Agent 的提问"，用户看到的是 Agent 针对这句话生成的回复。如需精确控制文案，请在触发消息中明确要求 Agent 原样输出。

Q：新用户会收到任务消息吗？
不会。任务只会向已有会话记录的用户发送，且会话创建时间需落在"目标会话范围"内。

Q：定时任务为什么没有在整点准时发送？
调度器每分钟扫描一次，且大批量发送会按项目级速率限制分批推送，因此实际到达时间可能略有延后。

Q：Webhook 返回权限错误（Permission deny）？
请依次检查：Webhook URL 是否正确、鉴权凭证是否匹配、任务是否已被停止、请求中的 target.channel 是否属于任务配置的目标通道。