LiteLLM Agent Control Plane CRON 调度实战:如何定时自动运行 Agent 并生成新会话

原创2026-10-13 20:58:271,623 阅读

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 时间。

调度器是如何工作的?

整个调度链路由三个部分组成,源码分别位于:

LAP 平台会话界面,展示定时运行 Agent 后自动生成的新会话对话记录

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)、模型和系统提示词后保存。

LAP 平台创建 Agent 界面,可选择 Agent、Runtime 与模型后一键 Run 运行

💡 定时任务本质上是"到点替你点一次 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(必填):要定时运行的 Agent
  • name(必填):任务名,将用于新会话标题
  • prompt(可选):本次定时运行的提示词,缺省用 Agent 的 prompt
  • cron(必填):5 段 cron 表达式
  • timezone(可选):IANA 时区,如 Asia/Shanghai,默认 UTC
  • status(可选):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"做成了平台级能力:

  1. 调度器每分钟轮询、按 cron + 时区判断到期,内置防重与 32 天补跑窗口;
  2. 每次触发自动创建全新会话并投递 prompt,运行过程完整留存在会话历史中;
  3. 配置方式灵活:UI 可视化频率选择,或 REST API 全量管理(创建/更新/删除/手动触发);
  4. 支持步长、区间、列表等标准 cron 语法,覆盖从"每 15 分钟巡检"到"每月 1 号报表"的各类自动化场景。

下一步,不妨给你的 Agent 加上第一条"每天 9 点"的定时任务,让 Agent 真正开始自动打工 🚀。

登录后查看全文
litellm-agent-control-plane