# 创建和管理自动化任务

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

## 开始之前

请准备：

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

本文假设 `PRODUCT_API_BASE_URL` 已包含 `/newmoi`。认证与工作区作用域见 [Product API 开始使用](../../product-api/getting-started.md)。

## 选择触发方式

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

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

## 创建 API 触发任务

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

```bash
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 参考](api-reference.md)。

## 查询和修改任务

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

```bash
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 | 按[接收事件并触发自动化任务](../channels-callbacks/receive-route-events.md)逐段检查。 |

## 下一步

- [运行自动化任务并读取历史记录](run-tasks.md)
- [配置消息通道并测试连接](../channels-callbacks/manage-channels.md)
- [查询自动化任务 API](api-reference.md)