# 运行自动化任务并读取历史记录

触发自动化任务后，保存返回的历史记录 ID，并使用它查询状态、结果和事件。触发请求被接受只表示历史记录已经创建或进入队列，不表示智能体已经完成任务。

## 开始之前

- 已创建并启用自动化任务；
- 已根据任务的 `trigger.mode` 取得任务 ID 或服务名称；
- 本次 `payload` 符合任务配置的输入 Schema；
- 已评估任务可能调用的外部工具、写入操作和模型用量。

## 选择运行方式

| 场景 | 使用方式 | 需要保存的值 |
| --- | --- | --- |
| 调用 API 类型任务 | 按服务名称调用 Dynamic Service | 历史记录 ID `run_id` |
| 手动验证已有任务 | 对任务 ID 创建一次运行 | 历史记录的 `id` |
| 等待计划触发 | 从任务或工作区历史记录列表查找新记录 | 历史记录的 `id` |
| 由第三方事件触发 | 检查回调规则目标，再查询历史记录列表 | 历史记录的 `id` |

## 调用 API 类型任务

服务名称仅在任务响应或详情中的 `api_summary.service_name` 存在时可用。不要根据任务名称自行拼接：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/dynamic-services/invoke" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "service_name": "<SERVICE_NAME>",
    "payload": {
      "input": "Summarize this incident report"
    }
  }'
```

命中自动化任务时，接口返回已创建历史记录的标识和初始状态。保存 `data.run_id`；如果响应提供 `result_url`，仍应先根据状态判断结果是否已经可读取。

## 手动运行任务

下面的请求对已有 Cron 任务创建一次手动运行，适合联调计划任务：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-automation-tasks/<TASK_ID>/runs" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"input":"test"}}'
```

请求成功后，从 `data.id` 保存历史记录 ID。手动运行不会改变任务的 Cron 配置。

## 查询历史记录状态

```bash
curl \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-automation-runs/<RUN_ID>" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

| 状态 | 含义 | 调用方动作 |
| --- | --- | --- |
| `queued` | 历史记录已经创建，任务尚未开始运行 | 有界等待后再次查询。 |
| `running` | 智能体正在执行 | 继续查询；需要定位进度时读取事件。 |
| `input_required` | 运行需要补充输入 | 检查事件和任务设计；不要继续无条件轮询。 |
| `pending_approval` | 运行等待批准 | 按当前产品提供的批准入口处理。 |
| `succeeded` | 运行成功终止 | 读取最终结果。 |
| `failed` | 运行失败终止 | 检查 `error` 和最近事件，修正后再决定是否重新运行任务。 |
| `canceled` | 运行已取消 | 不再等待结果；确认是否需要重新运行。 |
| `expired` | 历史记录已经过期 | 检查任务和依赖耗时，再重新运行任务。 |

轮询时设置总等待时间和最大次数。不要对写入或具有外部副作用的任务自动无限重试。

## 读取结果

历史记录进入 `succeeded` 后读取结果：

```bash
curl \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-automation-runs/<RUN_ID>/result" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

| 字段 | 返回条件 | 说明 |
| --- | --- | --- |
| `final_text` | 运行产生最终文本时 | 面向读者的最终文本结果。 |
| `structured_output` | 运行产生结构化输出时 | 应结合任务的输出契约解析。 |
| `output_validation_status` | 配置或执行输出校验时 | 表示结构化输出是否通过校验。 |
| `output_validation_error` | 输出校验失败时 | 用于定位不符合输出契约的字段。 |
| `artifact_refs` | 本次运行产生可引用产物时 | 指向本次运行输出的资源引用；它不是工作流 ArtifactHandle。 |
| `error` | 本次运行失败或结果包含错误时 | 保存错误代码和脱敏消息用于排查。 |

`artifact_refs` 中的引用用于定位自动化任务本次运行产生的外部或持久化结果。具体引用类型、ID、URI 和元数据由实际历史记录返回，不应假定每次运行都有 Artifact。

## 查看历史记录事件

当状态长时间不变、工具调用失败或需要了解执行顺序时，查询事件列表：

```bash
curl \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-automation-runs/<RUN_ID>/events?limit=50&offset=0" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

事件用于检查运行过程中记录的类型、状态、消息和时间。事件列表不代替最终结果；历史记录成功结束后仍应读取结果接口。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 触发返回成功但没有结果 | 初始状态和历史记录 ID | 查询历史记录详情，不立即重复触发。 |
| 历史记录一直处于 `queued` | 创建时间、最近事件和依赖资源 | 设置等待上限；超出后保留历史记录 ID 和事件摘要。 |
| 运行 `failed` | `error`、输出校验错误和最近事件 | 修正输入、凭据或工具配置后创建新运行。 |
| 结果没有 `artifact_refs` | `final_text`、`structured_output` 和任务设计 | 只有运行实际产生引用型结果时才会返回该字段。 |

## 下一步

- [查询自动化任务和历史记录 API](api-reference.md)
- [接收第三方事件并触发任务](../channels-callbacks/receive-route-events.md)
- [查看 API 通用的异步与重试规则](../../common/pagination-async-idempotency.md)