LiteLLM Agent Control Plane CRON 调度实战:如何定时自动运行 Agent 并生成新会话
LiteLLM Agent Control Plane CRON 调度实战:如何定时自动运行 Agent 并生成新会话
LiteLLM Agent Control Plane(LiteLLM Agent Platform,简称 LAP)是一个统一的 AI Agent 管控平台,让你用一个入口调用 OpenCode、Claude Managed Agents、Cursor、Deep Agents 等所有 Agent 运行时。除了随时手动对话,LAP 还内置了 CRON 定时调度能力:为任意 Agent 配置一条 cron 表达式,平台会按时间点自动触发 Agent 运行,每次定时运行都会自动创建一个全新的会话并写入会话历史,无需你打开浏览器或写任何脚本。
本文带你从零理解 CRON 调度的工作机制,并给出 UI 与 API 两种配置方式,帮你在 10 分钟内搭好第一个定时任务 ⏰。
为什么需要 CRON 定时运行 Agent?
手动触发 Agent 只适合即时问答。而很多真实场景需要"到点自动干活":
- 📊 每日晨报:每个工作日早上 9 点自动汇总数据并生成报告
- 🧹 周期性巡检:每 15 分钟检查一次系统状态、告警或日志
- 📅 固定提醒/摘要:每周一自动生成上周工作摘要
- 🔄 后台批处理:定时执行数据清洗、内容生成等长任务
LAP 的调度器内置在网关进程中,基于标准的 5 段 cron 表达式(分 时 日 月 周)并支持独立时区设置,因此"每天 9 点"是按你配置的时区计算的,而不是服务器所在的 UTC 时间。
调度器是如何工作的?
整个调度链路由三个部分组成,源码分别位于:
- 调度循环:src/http/managed_agents/routines/scheduler.rs
- 触发执行:src/http/managed_agents/routines/trigger.rs
- 数据表结构:src/db/managed_agents/routines/schema.rs
1. 每分钟轮询一次
服务启动时(见 src/main.rs)会启动一个后台调度任务,每 60 秒扫描一遍数据库中所有 status = active 的定时任务,检查是否有"到点未执行"的任务。
2. 判断是否到期(防重复执行)
调度器会按任务的 cron 表达式和时区,向前回溯查找最近一次应触发的时间点(最长回溯 32 天,覆盖服务短暂停机的情况)。如果该时间点晚于 last_run_at(上次执行时间)或任务创建时间,就认为到期并立即触发——否则跳过。这一设计保证了:
- 同一个触发点不会重复执行两次
- 服务停机后重启,错过的任务在回溯窗口内可以补跑
- 任务创建时间晚于某个触发点时,不会"补触发"过去的时间(例如上午 10 点创建"每天 9 点"任务,当天 11 点不会执行,而是等到次日 9 点)
3. 创建新会话并投递 Prompt
触发时(trigger.rs)LAP 会为任务绑定的 Agent 创建一个全新会话,会话标题自动命名为"<任务名> run",然后把定时任务的 prompt 投递到该会话中异步执行。任务若未单独填写 prompt,则回退使用 Agent 自身保存的 prompt。
每次执行完成后,调度器会把 last_run_id、last_session_id、last_run_at 写回任务记录,方便你在 UI 中直接查看最近一次运行的会话和日志。
快速上手:用 UI 创建第一个定时任务
步骤一:先有一个可用的 Agent
在 Web UI(本地为 http://localhost:4000,使用 master key 登录)中点击 New Agent,选择运行时(如 OpenCode、Claude Managed Agents)、模型和系统提示词后保存。
💡 定时任务本质上是"到点替你点一次 Run",所以 Agent 本身必须能手动跑通,再配置调度。
步骤二:添加 Schedules
打开目标 Agent → Schedules → Add schedule,即可为该 Agent 添加一条 cron 表达式。每个定时运行都会创建一个新会话,并出现在该 Agent 的会话历史中(参见官方文档 docs/channels/ui.mdx 的 CRON schedules 一节)。
UI 的调度编辑器(src/ui/src/components/schedule-editor.tsx)支持常用频率的可视化选择:
| 频率选项 | 说明 | 对应 cron 示例 |
|---|---|---|
| On demand | 仅手动触发 | — |
| Hourly | 每小时 | 0 * * * * |
| Daily | 每天定点 | 0 9 * * * |
| Weekdays | 工作日定点 | 0 9 * * 1-5 |
| Weekly / Monthly | 每周 / 每月定点 | 0 9 * * 1 / 0 9 1 * * |
| Custom | 自定义表达式 | */15 * * * * |
同时可以选择时区(默认 UTC),调度器会按该时区解释 cron 表达式。UI 侧的管理页面位于 src/ui/src/app/routines/page.tsx,支持创建、编辑、暂停(改 status)、删除和手动触发测试。
步骤三:手动 Trigger 验证
保存后不必干等下个触发点:点击任务旁的 Zap(触发) 按钮可立即执行一次。运行成功后,会话历史里会出现一条名为"<任务名> run"的新会话,点进去就能看到 Agent 的流式输出和工具调用过程。
用 API 管理定时任务
如果你希望把调度纳入 DevOps 流程,可以直接调用 REST API。路由定义在 src/http/managed_agents/routes.rs:
| 操作 | 方法与路径 |
|---|---|
| 列出任务 | GET /api/routines?agent_id=<id> |
| 创建任务 | POST /api/routines |
| 更新任务 | PATCH /api/routines/{routine_id} |
| 删除任务 | DELETE /api/routines/{routine_id} |
| 手动触发 | POST /api/routines/{routine_id}/trigger |
创建请求体字段(见 schema.rs):
agent_id(必填):要定时运行的 Agentname(必填):任务名,将用于新会话标题prompt(可选):本次定时运行的提示词,缺省用 Agent 的 promptcron(必填):5 段 cron 表达式timezone(可选):IANA 时区,如Asia/Shanghai,默认UTCstatus(可选):active/ 非 active(暂停)
例如"每个工作日北京时间 9 点运行晨报 Agent":
curl -X POST http://localhost:4000/api/routines \
-H "Authorization: Bearer <MASTER_KEY>" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_xxx",
"name": "工作日晨报",
"prompt": "生成今日数据晨报,突出异常指标。",
"cron": "0 9 * * 1-5",
"timezone": "Asia/Shanghai"
}'
手动触发返回的 202 响应中包含 run_id、session_id 和 event_url(形如 /v1/sessions/{session_id}/events/stream),可据此订阅 SSE 事件流实时跟进这次运行的输出。
CRON 表达式速查(支持的语法)
LAP 内置了轻量 cron 解析器(scheduler.rs),支持标准 5 段语法:分 时 日 月 周,其中:
- 单值:
0 9 * * *→ 每天 09:00 - 步长:
*/15 * * * *→ 每 15 分钟 - 区间:
0 9 * * 1-5→ 周一至周五 09:00 - 逗号列表:
0 9,18 * * *→ 每天 09:00 与 18:00 - 星号/问号:
*与?均表示"任意值" - 星期
0或7都表示周日
常见配置示例:
| 需求 | cron | 时区 |
|---|---|---|
| 每小时巡检 | 0 * * * * |
任意 |
| 每天 9 点晨报 | 0 9 * * * |
Asia/Shanghai |
| 工作日 9 点 | 0 9 * * 1-5 |
Asia/Shanghai |
| 每 15 分钟 | */15 * * * * |
任意 |
| 每月 1 号 0 点 | 0 0 1 * * |
UTC |
查看运行记录与排查问题
- 会话历史:每次定时运行都是独立会话(标题为"<任务名> run"),在对应 Agent 的 Sessions 列表中可查看、回放或续聊。
- 最近运行字段:任务记录中的
last_session_id/last_run_at可在 Routines 页面直接看到,点击即可跳转最近一次运行。 - 常见疑问:
- 为什么没触发? 确认
status为active、cron 段数为 5、时区设置符合预期;任务创建时间晚于触发点时,首次执行在下一个触发点。 - 停机会丢任务吗? 服务重启后 32 天回溯窗口内的到期任务会被补跑一次,超出窗口的触发点会被跳过。
- 同一时间点会重复跑吗? 不会,调度器以"最近触发点 > 上次执行时间"作为唯一判据,天然去重。
- 为什么没触发? 确认
- 更多运行时与调度的组合方式,可参考 docs/runtimes/deepagents.mdx 中的 CRON schedules 章节。
总结
LiteLLM Agent Control Plane 的 CRON 调度把"定时跑 Agent"做成了平台级能力:
- 调度器每分钟轮询、按 cron + 时区判断到期,内置防重与 32 天补跑窗口;
- 每次触发自动创建全新会话并投递 prompt,运行过程完整留存在会话历史中;
- 配置方式灵活:UI 可视化频率选择,或 REST API 全量管理(创建/更新/删除/手动触发);
- 支持步长、区间、列表等标准 cron 语法,覆盖从"每 15 分钟巡检"到"每月 1 号报表"的各类自动化场景。
下一步,不妨给你的 Agent 加上第一条"每天 9 点"的定时任务,让 Agent 真正开始自动打工 🚀。

