# 自动化任务 API 参考

本页汇总自动化任务和历史记录的 Product API。服务地址、个人访问令牌和工作区作用域见 [Product API 开始使用](../../product-api/getting-started.md)。

## 接口

| 方法 | 相对路径 | 用途 |
| --- | --- | --- |
| `POST` | `/workspaces/{workspace_id}/agent-automation-tasks` | 创建任务。 |
| `GET` | `/workspaces/{workspace_id}/agent-automation-tasks` | 列出和筛选任务。 |
| `GET` | `/workspaces/{workspace_id}/agent-automation-tasks/{task_id}` | 读取任务。 |
| `PATCH` | `/workspaces/{workspace_id}/agent-automation-tasks/{task_id}` | 部分更新任务。 |
| `DELETE` | `/workspaces/{workspace_id}/agent-automation-tasks/{task_id}` | 归档任务。 |
| `POST` | `/workspaces/{workspace_id}/agent-automation-tasks/{task_id}/runs` | 手动运行任务并创建历史记录。 |
| `GET` | `/workspaces/{workspace_id}/agent-automation-tasks/{task_id}/runs` | 列出某个任务的历史记录。 |
| `GET` | `/workspaces/{workspace_id}/agent-automation-runs` | 列出工作区中的历史记录。 |
| `GET` | `/workspaces/{workspace_id}/agent-automation-runs/{run_id}` | 读取历史记录详情。 |
| `GET` | `/workspaces/{workspace_id}/agent-automation-runs/{run_id}/result` | 读取历史记录结果。 |
| `GET` | `/workspaces/{workspace_id}/agent-automation-runs/{run_id}/events` | 读取历史记录事件。 |
| `POST` | `/workspaces/{workspace_id}/dynamic-services/invoke` | 按服务名称触发 API 类型任务。 |

请求使用 `X-API-Key: <PAT>`。工作区资源通过路径中的 `{workspace_id}` 确定作用域。

## 任务对象

| 字段 | 类型 | 返回条件 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 始终返回 | 任务 ID。 |
| `workspace_id` | string | 始终返回 | 任务所属工作区。 |
| `agent_id` | string | 始终返回 | 任务每次运行时调用的智能体。 |
| `instruction_text` | string | 始终返回 | 固定运行指令。 |
| `trigger` | object | 始终返回 | 当前触发模式及其配置。 |
| `status` | string | 始终返回 | 任务当前状态。 |
| `version` | integer | 始终返回 | 任务配置版本。 |
| `next_trigger_at` | string | 计划任务可计算下一次运行时返回 | 下一次计划触发时间。 |
| `api_summary` | object | API 类型任务可提供时返回 | 包含服务名称等调用摘要。 |
| `last_run_summary` | object | 已有历史记录摘要时返回 | 最近一次运行的摘要信息。 |
| `created_at` | string | 始终返回 | 创建时间。 |
| `updated_at` | string | 始终返回 | 最近更新时间。 |

创建和更新字段见[创建和管理自动化任务](manage-tasks.md)。任务列表可按智能体、状态、触发模式和关键词筛选，并使用 `limit`、`offset` 分页。

## 历史记录对象

| 字段 | 类型 | 返回条件 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 始终返回 | 历史记录 ID。 |
| `automation_task_id` | string | 始终返回 | 历史记录所属的自动化任务。 |
| `automation_task_version` | integer | 始终返回 | 本次运行使用的自动化任务配置版本。 |
| `trigger_type` | string | 始终返回 | `cron`、`api`、`callback` 或 `manual`。 |
| `trigger_config_snapshot` | object | 始终返回 | 创建历史记录时保存的触发配置。 |
| `status` | string | 始终返回 | 当前历史记录状态。 |
| `final_text` | string | 产生最终文本时返回 | 最终文本。 |
| `structured_output` | object | 产生结构化结果时返回 | 结构化输出。 |
| `artifact_refs` | array | 产生引用型结果时返回 | 结果引用列表。 |
| `error` | object | 本次运行失败或有错误信息时返回 | 错误详情。 |
| `started_at` | string | 运行开始后返回 | 开始时间。 |
| `completed_at` | string | 历史记录进入终态后返回 | 完成时间。 |

历史记录和事件列表使用 `limit`、`offset` 分页。运行任务后应保存历史记录 ID；状态与处理动作见[运行自动化任务并读取历史记录](run-tasks.md)。

## 错误和限制

| 现象 | 检查信息 | 恢复方式 |
| --- | --- | --- |
| `401` 或认证冲突 | `X-API-Key` 以及是否混入其他凭据 | 只使用当前 Product API 支持的 PAT Header。 |
| `403` | 工作区成员关系和目标智能体权限 | 使用具有相应资源权限的身份。 |
| `404` | 工作区、任务、历史记录或服务名称 | 从列表或创建响应重新取得 ID，不自行构造。 |
| `409` | 当前任务版本或状态 | 重新读取任务后再提交更新。 |
| 参数无效 | `trigger`、输入 Schema 和 `payload` | 按错误指出的字段修正，不重复提交相同请求。 |

## 任务指南

- [创建和管理自动化任务](manage-tasks.md)
- [运行自动化任务并读取历史记录](run-tasks.md)