# Jobs 定时任务

> 配置触发器、目标和重试，检查每次执行记录。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

Job 用于在指定时间自动运行 Agent 或 Agentflow，适合例行检查和定期整理资料。任务要求、所属 Project 和执行时间保存后，Server 会按计划发起执行，并记录每次结果。

先在 Chat 中手动验证同样的任务，确认模型、工具和目录都可用。定时执行期间 Server 必须保持运行；分离部署时，控制面负责调度，数据面负责执行。

## 配置步骤

1. 在 Jobs 创建任务，在 **Project ID** 中选择 Project，在 **Agent ID** 中选择要运行的 Agent 或 Agentflow。没有选择执行目标的任务也能保存，但运行时会失败并进入重试。
2. 写明提示词，选择 **Trigger Type** 并填写执行时间或触发值。
3. 需要修改任务名称、失败重试次数或启用状态时，点击对话框底部的 **Advanced**，在 **Job Name**、**Max Retry Count** 和 **Enabled** 中设置。**Max Retry Count** 默认为 3，任务默认启用；**Job Name** 留空时自动生成。
4. 首先使用未来的一次性任务验证，确认 Job 日志和项目执行记录符合预期后，再新建一个周期任务。一次性任务成功后会暂停并禁用，之后把它改为周期触发或重新启用，它都不会再次运行。

| 触发方式 | 示例 | 时间语义 |
| --- | --- | --- |
| Once | 未来的 RFC 3339 时间，如带 `Z` 的 UTC 值 | 必须是未来时间 |
| Interval | `00:15:00` | 使用正数时长，格式为小时:分钟:秒。第一次在创建后 15 分钟执行，之后从上一次成功执行结束时再计算 15 分钟 |
| Cron | `0 1 * * *` | 标准五段，按 UTC 计算，每天 01:00 UTC |

客户端显示本地时间，但 Cron 按 UTC 计算。不要把过去的 Once 时间当作“立即执行”。Interval 不是正数的“小时:分钟:秒”时长，或 Cron 不是五段时，输入框下方会显示错误，保存按钮不可用；五段但字段取值无效的 Cron 在保存时由 Server 返回 “Invalid cron trigger value”。保存后在任务列表的 **Next Run** 中核对下一次执行时间。

![AGW Desktop：Cron Job 的未保存示例。创建前需选择执行目标，并确认计划与提示词。](/images/screenshots/job-create.png)
{caption="AGW Desktop：Cron Job 的未保存示例。创建前需选择执行目标，并确认计划与提示词。"}

## 写一条能独立执行的任务要求

定时任务开始时未必有人补充说明，提示词应交代资料位置、时间范围和输出要求。例如：“读取项目中的本周进展记录，列出已完成事项、未解决问题和下一步建议；缺少记录时明确说明，不要推测。”使用前要为目标 Agent 配好读取能力。

`0 1 * * *` 表示每天 UTC 01:00，对新加坡或中国标准时间是当天 09:00。保存后在任务列表或详情的 **Next Run** 中核对下一次执行时间。若设置最多重试 2 次，则本轮最多尝试 3 次：首次执行加两次重试。

## 执行、重试与暂停

同一 Project 的定时任务串行，不同 Project 可以并行。每次执行都会在该 Project 中新建一个会话，以 Full access 权限运行，并自动拒绝需要人工回答的提问和审批。一次性任务成功后暂停并禁用；周期任务成功后安排下一次执行。失败后在 30 秒后重试，`MaxRetryCount` 不含首次尝试。重试耗尽后任务暂停并禁用，周期任务也不再安排下一次执行；需要继续运行时，应修正问题后新建任务。

每次执行尝试都会记录时间、结果和错误。禁用任务只阻止后续调度，不会中断正在运行的任务；执行期间编辑或删除可能被拒绝，需要等本次执行结束。调度器会提前读取即将到期的任务，改期后应再次核对任务状态和执行记录。

没有执行时检查初始化、启用状态、下一次运行时间和有效目标。对于写入外部系统的任务，应让操作可重复执行，不能把项目锁视为 exactly-once 保证。

## Job Logs：查看每次执行结果

Job Logs 记录一个 Job 的每次执行尝试，用来确认任务是否运行成功、是否发生重试，以及失败原因。它记录执行结果；模型的完整回复和工具活动需要进入 Chat 查看。

### 打开执行日志

1. 在 Jobs 列表找到任务，点击该行的日志入口，进入 **Job Logs**。
2. 根据执行时间找到要检查的记录，查看状态、尝试次数和错误信息。
3. 点击该行的 **Go to Chat** 打开这次执行对应的会话，查看对话和执行内容；这次执行还没有会话记录时，只打开该 Job 所属的 Project。

任务详情中的 **Execution Logs** 也可以查看尝试记录和错误，**Back to Jobs** 则返回任务列表。

### 如何理解字段

| 字段 | 含义 |
| --- | --- |
| Status | `Succeeded` 表示该次尝试成功结束，`Failed` 表示失败 |
| Attempt | 本轮执行的尝试序号：`#1` 是首次尝试，`#2` 是第一次重试，不是任务累计运行次数 |
| Job ID | 这些记录所属的任务标识，同一个 Job 的多条记录使用相同 ID |
| Time | 本次尝试的开始时间，以及已有的结束时间；按客户端本地时间显示 |
| Error | 失败原因；没有错误信息时显示 `-` |
| Actions | 通过 `Go to Chat` 查看对话内容 |

例如，同一轮执行先出现 `Failed / #1`，随后出现 `Succeeded / #2`，表示首次失败、重试成功。周期任务成功后会重置重试计数，因此后续记录再次出现 `#1` 是正常现象；应结合时间区分不同轮次。

### 用日志排查问题

- **没有记录**：先检查任务是否启用、是否到达执行时间，以及当前是否仍在运行。日志在尝试结束并记录结果时写入，空列表不一定表示调度没有启动。
- **执行失败**：先看 Error，再通过 Go to Chat 检查模型回复和工具活动。连接不到模型、工具执行失败或工作目录不可用时，结合 Server 日志定位原因。
- **日志成功但结果不符合预期**：Succeeded 表示执行成功结束，仍需检查实际输出、生成文件或外部操作是否符合任务要求。
- **有失败记录但任务已恢复正常**：保留的失败记录不会因后续重试成功而消失，按时间检查后续尝试和任务当前状态。

## 定时与后台执行

Jobs 可以在指定时间、固定间隔或 Cron 计划下运行 Agent 或 Agentflow，适合周期汇总、例行检查等工作。后台 Agent 能力则用于把子任务交给其他 Agent，并在后续获取结果。

1. 先确认 Project、执行目标和所需工具可以正常工作。
2. 为周期任务创建 Job，填写任务要求和触发时间；需要委派子任务时配置 Background Agents 能力。
3. 在任务记录中查看状态、结果与错误，按实际需要调整计划。

关闭 Chat 页面不会自动取消执行；但 Server 和实际执行节点必须保持运行。后台 Agent 不能停下来等待新的人工审批；无人值守 Job 遇到必须由人回答的问题或 HumanGate 时也无法自动完成。持续运行不代表所有任务都能在服务重启后无缝恢复，恢复能力取决于部署与执行方式。

[配置工具与 Skills](/zh/docs/guides/tools-skills/) · [了解记忆能力](/zh/docs/features/memory/) · [查看执行状态](/zh/docs/guides/chat/)

## 实现与参考

- [Scheduler](https://github.com/zxyao145/agw/blob/main/src/server/Agw.Jobs/README.zh-CN.md)

- [Job Logs UI](https://github.com/zxyao145/agw/blob/main/src/clients/packages/jobs/src/ui-web/pages/jobs/logs/page.tsx)
- [Attempt outcomes](https://github.com/zxyao145/agw/blob/main/src/server/Agw.Jobs/Scheduling/Attempts/JobAttemptOutcomeRecorder.cs)

---

反链：

- [使用指南](/zh/docs/guides/)
- [核心概念](/zh/docs/start/concepts/)