任务接入¶

任务接入用于把工作空间中的事件，或外部业务系统发送的消息，交给指定 Agent 自动处理。Agent 会根据接入配置收集输入、创建任务会话，并利用当前可用的上下文和工具完成分析；结果可保留在会话中，也可投递到已配置的消息渠道会话。

Agent 可使用的能力由已启用的配置和访问权限决定。除指标、日志、链路等可观测数据外，Agent 还可根据任务需要使用已启用的 Skill、MCP 服务，以及运行环境中可访问的相关信息。未配置或无权限访问的资源不会被使用。

它适合把原本分散在告警、监控系统、工单系统和业务平台中的事件，沉淀为可持续执行的智能工作流。例如，告警触发后由 Agent 给出初步研判和排查步骤；外部系统出现发布异常时，自动创建分析任务并把结果发到值班群。

任务接入能做什么¶

任务接入将事件触发、分析和结果分发串联起来，帮助团队：

• 更快处理异常：让 Agent 在事件发生后自动整理告警摘要、可能原因、影响范围和建议动作；
• 综合分析关联信息：结合告警内容与指标、日志、链路等可观测数据，并按任务需要使用 Agent 的 Skill、MCP 服务和可访问的环境信息，减少人工收集上下文的时间；
• 减少重复沟通：将分析结果主动投递到值班群、故障群或负责人会话；
• 扩展自动化边界：通过 Webhook 接入第三方监控、工单、发布和业务系统事件；
• 保留处理依据：每一次触发都会生成运行记录和关联任务会话，便于追踪、复盘和优化配置。

自动化任务适合按固定时间执行；任务接入适合由事件或外部消息触发执行。

接入类型¶

任务接入提供两种入口，最终都会由对应的 Agent 处理：

flowchart LR
  A[工作空间告警策略] --> B[工作空间接入]
  C[外部系统] --> D[自定义 Webhook 接入]
  B --> E[Agent 创建任务并分析]
  D --> E
  E --> F[任务会话与运行记录]
  E --> G[已配置的消息渠道会话]

开始前准备¶

使用任务接入前，请确认：

• 已在当前工作空间创建并配置好目标 Agent；
• 目标 Agent 已启用完成任务所需的 Skill 和 MCP 服务，并具备访问所需工作空间数据或环境信息的权限；
• 如需将结果通知到群聊或私聊，已为目标对话建立消息渠道会话；
• 对于自定义接入，外部系统能够通过 HTTP POST 发送 JSON 请求。

建议先让 Agent 输出分析与建议，确认结果稳定后，再逐步增加需要执行操作的任务要求。

准备结果投递目标¶

任务接入中的Channel 投递以具体会话为目标。选择列表只会展示当前 Agent 已经建立的消息渠道会话；仅完成消息渠道配置时，目标群聊或私聊可能尚未出现在列表中。

如果列表为空或找不到目标会话，请先按照准备用于结果投递的消息渠道会话在目标对话中与机器人完成一次消息交互，再刷新当前页面或重新打开配置后选择。您可以选择一个或多个会话，分析结果只会发送到所选会话，不会自动发送到同一消息渠道下的其他会话。

使用工作空间接入¶

工作空间接入用于处理空间内部产生的监控器事件。您可以在告警策略中选择目标 Agent；事件产生后，系统会将事件上下文交给该 Agent，Agent 可结合自身可用的数据、工具和环境信息开展分析。

进入 Agent 工作台的任务接入页面，找到类型为工作空间的接入配置，打开详情后可查看或调整以下内容：

使用自定义接入¶

自定义接入会为当前 Agent 生成一个可供外部系统调用的 Webhook 地址。外部系统向该地址发送 JSON 消息后，系统根据任务指令整理输入并触发 Agent。

创建接入¶

1. 进入目标 Agent 的任务接入页面。
2. 点击新建自定义接入。
3. 填写接入配置并保存。
4. 复制生成的 Webhook 地址，配置到外部系统。
5. 发送一条测试事件，在接入详情的运行记录中确认 Agent 是否已创建任务并输出结果。

配置项说明¶

保存后，系统会生成包含访问 token 的 Webhook 地址。请将该地址视为敏感信息，不要公开到不受控的位置。需要停止旧地址时，可在接入详情中重置 Webhook 地址；重置后旧地址立即失效，需同步更新外部系统配置。

请求格式与字段引用¶

调用自定义接入的 Webhook 地址时，请使用 POST 方法发送 JSON。请求格式需符合以下规范：

任务指令直接以 data 内的字段作为变量上下文，无需在占位符中添加 data 前缀：

• {{title}} 对应 data.title。
• {{detail.message}} 对应 data.detail.message，可使用英文句点引用嵌套对象中的字段。
• 占位符中的字段路径支持英文字母、数字、下划线、连字符和英文句点。
• 数组会转换为以逗号分隔的文本，对象会转换为 JSON 文本。

如果请求体不是有效的 JSON，或者缺少符合要求的 data 对象，接口会返回 400。任务指令中找不到对应字段时，占位符会保留在指令中。建议使用稳定、语义明确的字段名，并在上线前发送测试消息，确认字段可以被正确引用。

最佳实践：接入外部监控告警¶

以下示例演示如何将第三方监控系统的网关告警接入 Agent，并把综合分析结果发送给值班人员。

1. 创建自定义接入¶

可按以下方式配置：

在任务指令中填写：

以下是一条来自第三方外部监控系统的告警。请根据告警字段内容，并结合当前工作空间的可观测数据、已启用的 Skill 和 MCP 服务，以及运行环境中可访问的相关信息，完成初步分析。

告警标题：{{title}}
发生时间：{{date}}
环境/标签：{{tags}}
详细信息：{{message}}

请输出：
1. 告警摘要
2. 可能原因
3. 影响范围
4. 建议处理步骤

这段任务指令既告诉 Agent 如何读取事件字段，也明确了分析范围和输出结构。若希望 Agent 进一步执行操作，应单独写明操作目标、边界和必须人工确认的事项。

2. 由外部系统发送告警¶

将页面生成的 Webhook 地址替换为实际地址，并以 POST 方式发送以下 JSON。示例中的业务告警内容保持在 data 中，供任务指令引用：

{
  "data": {
    "title": "接口异常 / unknown upstream issue",
    "date": "2026-07-14T16:08:32+08:00",
    "tags": ["prod", "order", "gateway", "auto-alert", "sev:?"],
    "message": "[FIRING] rule=gw_5xx_rate maybe order-create; current=8.7? prev=0.3? unit=%; path=/v1/orders/create,/v1/orders/*; region=cn-east-1; host=gw-prod-17|gw-prod-22; upstream=?; err_code=502/503/000; raw_log=\"upstream_reset_before_headers EOF timeout context_canceled\"; payload_hash=***; detail_truncated=true; dashboard_ref=apigw-err-03; note=\"auto merged from 3 signals, confidence=0.62\""
  }
}

3. 查看发送给值班人员的分析结果¶

Agent 会先将任务指令和告警字段写入任务会话，再结合当前可用的数据、工具和环境信息完成分析。下面是一份示例结果，用于说明值班人员可能在已配置的消息渠道会话中收到的内容；其中的指标和结论为模拟内容，实际结果以 Agent 在当前任务中可访问的信息为准。

【订单网关异常初步分析】

1. 告警摘要
- 2026-07-14 16:08:32，生产环境订单网关的 5xx 比例升至 8.7%，高于此前约 0.3% 的水平。
- 异常集中在 /v1/orders/create 及 /v1/orders/* 路径，涉及 cn-east-1 的 gw-prod-17、gw-prod-22。
- 告警由 3 个相关信号合并产生，需结合后续链路和日志进一步确认。

2. 可能原因
- 网关日志出现 upstream_reset_before_headers、EOF、timeout、context_canceled，表明网关与上游之间可能存在连接中断或响应超时。
- 工作空间中的同时间段指标显示网关 502/503 增加，且订单创建调用的上游耗时出现抬升；优先排查订单创建服务及其依赖的可用性、连接池和超时配置。
- upstream 字段未明确指向具体实例，不能仅凭本次告警判定故障根因；还需通过请求链路确认实际失败的下游服务。

3. 影响范围
- 生产环境订单创建及相关订单接口可能出现失败或重试，用户可能无法完成下单或看到请求超时。
- 当前证据指向 cn-east-1 的两个网关实例和订单相关请求路径；是否影响其他区域、其他入口或异步订单流程仍需核实。

4. 建议处理步骤
1. 打开 dashboard_ref=apigw-err-03，确认 5xx、延迟和请求量的开始时间、持续时长及异常实例分布。
2. 查询 gw-prod-17、gw-prod-22 在告警时间前后的网关日志，并按 trace ID 关联 /v1/orders/create 的下游调用链。
3. 检查订单创建服务及其直接依赖的健康状态、错误率、连接数和超时；对比最近的发布、配置或流量变化。
4. 若错误率持续升高，按团队故障流程进行限流、摘流、扩容或回滚；执行变更前请先完成必要确认。

4. 在运行记录中复查¶

打开该自定义接入的详情页，可按状态查看每次处理记录：

• 聚合中：消息正在等待当前执行窗口结束；
• 运行中：Agent 已创建任务并正在分析；
• 已完成：可打开关联任务会话，查看输入内容、分析过程和最终结果；
• 失败：检查错误信息、任务指令、字段映射、Agent 能力和外部请求格式后重新测试。

运行记录还会显示触发时间和接收消息数量。使用窗口处理时，同一窗口内的多条消息会汇总到一次任务中，便于 Agent 分析它们之间的关联。

使用建议¶

• 按事件来源和处理目标拆分接入配置，不要把无关事件混入同一条接入；
• 对告警风暴、抖动或强关联事件使用执行窗口；对高优先级单点异常使用立即处理；
• 任务指令要可验证：写明字段、分析对象、输出结构和升级条件，避免只写“帮我看一下”；
• 外部请求中只传递完成分析所需的信息，避免把密钥、个人数据或不必要的原始内容发送到 Webhook；
• 对外部触发的任务优先使用默认权限，并在结果稳定、边界清晰后再考虑完全访问权限；
• 定期查看失败记录和低质量结果，根据实际输入调整任务指令、执行周期、Agent 能力或消息渠道投递目标；
• 怀疑 Webhook 地址泄露时，立即重置地址并更新外部系统配置。