创建和管理自动化任务¶

创建自动化任务时，需要指定要运行的智能体、执行指令和触发方式。创建成功后会得到任务 ID；该 ID 用于修改任务、手动运行或查询任务的历史记录。

开始之前¶

请准备：

Product API Base URL 和个人访问令牌；
目标工作区 ID；
已发布且可以运行的智能体 ID；
本任务需要的触发方式和输入结构。

本文假设 PRODUCT_API_BASE_URL 已包含 /newmoi。认证与工作区作用域见 Product API 开始使用。

选择触发方式¶

`trigger.mode`	何时使用	触发入口
`api`	外部应用按服务名称提交输入	Dynamic Service 调用接口
`cron`	按计划周期运行	保存后的计划配置，或任务的手动运行接口
`callback`	第三方事件满足回调规则时运行	消息通道、回调地址和回调规则

手动运行不是任务定义中的触发模式，而是对已有任务发起的一次运行并生成一条历史记录。不要为了手动测试把任务的长期触发配置改成另一种模式。

创建 API 触发任务¶

下面的请求创建一个 API 触发任务。将占位值替换为当前工作区的值：

curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-automation-tasks" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-summary",
    "description": "Summarize the supplied records",
    "agent_id": "<AGENT_ID>",
    "instruction_text": "Summarize the input and return the main findings.",
    "trigger": {
      "mode": "api",
      "input_schema": {
        "type": "object",
        "properties": {
          "input": {"type": "string"}
        },
        "required": ["input"]
      }
    },
    "auth_policy": {
      "type": "workspace_api_key"
    },
    "status": "active"
  }'

请求会创建或配置自动化任务，不会立即运行该任务。成功后，从 data.id 保存任务 ID。只有响应包含 data.api_summary.service_name 时，才能使用 Dynamic Service 调用入口；不要根据任务名称自行拼接服务名称。

主要配置¶

字段	类型	必需	取值或格式	说明
`name`	string	是	工作区内可识别的名称	用于列表检索和运维识别，不代替任务 ID。
`agent_id`	string	是	已发布智能体 ID	每次运行调用的智能体。创建前应先验证该智能体可以正常调用。
`agent_workspace_id`	string	使用系统工作区智能体时	`system`	指定智能体所在的工作区范围。
`model`	string	否	工作区可用模型名称	为任务指定运行时模型。
`instruction_text`	string	是	文本	每次运行都会使用的固定任务指令。动态业务输入放在触发请求的 `payload` 中。
`trigger.mode`	string	是	`api`、`cron` 或 `callback`	决定任务如何自动启动。
`auth_policy.type`	string	`trigger.mode` 为 `api` 时	`workspace_api_key`	API 调用方认证策略。
`trigger.cron_expression`	string	条件必需	Cron 表达式	`mode=cron` 时设置。还需要按当前环境确认时区。
`trigger.input_schema`	object	否	JSON Schema	约束 API 或手动运行的输入结构。调用方应按该结构构造 `payload`。
`trigger.config`	object	否	Provider 或触发器配置	只填写当前触发方式明确支持的字段。
`output_contract`	object	否	输出约定	用于约束或校验结构化输出；校验结果会出现在历史记录结果中。
`status`	string	否	任务状态	第一次联调可以先停用，验证配置后再启用。

完整字段见自动化任务 API 参考。

查询和修改任务¶

使用列表接口按名称、状态、智能体或触发方式筛选任务。取得任务 ID 后，再读取详情或提交部分更新：

curl \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-automation-tasks/<TASK_ID>" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

更新触发方式、输入 Schema、智能体或指令可能影响后续运行。更新响应中的 version 表示任务配置版本；已有历史记录仍保留其创建时的任务版本和触发配置快照。

停用或归档任务¶

暂时停止自动触发时，将任务状态更新为停用。确认不再需要任务后，可以调用归档接口。归档前检查是否仍有回调规则、脚本或外部应用引用该任务或服务名称。

归档任务不会删除或改变已有历史记录，也不撤销此前运行产生的外部副作用。

常见问题¶

现象	先检查	下一步
创建后没有历史记录	创建请求是否只定义了任务、触发方式是否已经发生	使用正确入口触发一次低风险运行。
API 调用找不到服务	任务状态、触发模式和服务名称	重新读取任务，不根据任务名称自行构造服务名称。
定时任务未按预期运行	Cron 表达式、任务状态和下一次触发时间	修正计划并通过任务详情确认配置已更新。
回调事件没有触发任务	通道实例、回调规则和目标任务 ID	按接收事件并触发自动化任务逐段检查。

下一步¶

最后更新于 2026 年 8 月 14 日