如何让Agent到点自动开工?learn-agent-architecture 的Cron、睡眠与远程触发器实战教程

原创2026-10-14 12:22:031,932 阅读

如何让Agent到点自动开工?learn-agent-architecture 的Cron、睡眠与远程触发器实战教程

learn-agent-architecture 是一个从 0 开始拆解 AI Agent 架构的开源教程仓库,它逐章带你实现一个完整的 Agent。本文聚焦其中的第 14 章 Scheduling(调度):如何通过 Cron 定时任务、sleep 延迟和远程触发器,让 Agent 无需人工输入,就能在指定时间自动开工、自动汇报。读完你不仅懂原理,还能直接跑起来。🤖

一、问题:没有调度层,Agent 只能"等活干"

先认识一下所有 Agent 共享的核心流程——Agent loop:调用模型、执行工具、把结果放回对话、再调用模型,循环往复。

Agent loop 核心循环与定时调度触发关系图

问题在于:这个 loop 的每一轮都由用户输入启动。你按了回车,它才动。

但真实场景里,很多工作是"到点才做"的:

  • ⏰ 每天早上 9 点生成一份日报
  • 🔁 每 5 分钟轮询一次 CI 状态,有结果才通知
  • ⏳ 10 秒后自动重试一次刚才失败的命令
  • 📨 收到外部系统 webhook 时立刻处理

少了调度这一层,Agent 只能被动响应,无法主动开工。所以调度层必须做到四件事:

  1. 把"什么时间做什么"保存到单一轮次之外(持久化)
  2. 由独立组件监控时间,不阻塞主 loop
  3. 时间一到(fire),把对应的 prompt 放进队列
  4. 按需让计划在重启后依然存在

二、核心机制:时钟只"排队",loop 才"干活"

这一章最关键的设计思想是把时钟和 loop 分开:

learn-agent-architecture 第14章 Agent定时调度 Cron队列机制图

  • 左侧(时钟侧,daemon 线程):Scheduler 每秒醒来一次检查有没有到期的任务。注意它从不调用模型——fire 的动作只是"把 prompt 塞进队列"。
  • 右侧(loop 侧,前台):driver 在两轮对话之间清空队列,把每个被触发出来的 prompt 当成一条新的用户消息,交给原本处理用户输入的那套 loop 去跑。权限、hooks、记忆、错误恢复全部照常生效。

一个 schedule 本质就是一份数据:要跑的 prompt、一个触发时间、可选的重复间隔。由此派生出四种典型形态:

形态 行为 典型场景
one-shot(一次性) 触发一次后自动删除 "1 秒后统计文件数"
recurring(周期性) 触发后重新装填到下一个间隔 "每 30 秒轮询 CI"
durable(持久化) 写入 JSON,重启后自动重载 夜间备份任务
heartbeat(心跳) 周期性"问一个问题",没事就闭嘴 无 webhook 来源的巡检

创建调度只需要一行代码(完整实现在 scheduler.py):

sched.create("统计当前目录文件数并汇报", due=time.time() + 1, channel="console")

due 是绝对触发时间,every 传间隔秒数即变成周期任务,durable=True 则落盘,channel 指定答案发到哪里。

无人值守的答案去哪儿?deliver 与 [SILENT]

被时钟触发的执行没有人坐在屏幕前等,所以答案必须有出路。每个任务可以带一个 channel(控制台、Slack、短信……),deliver 负责把该轮回答路由过去。

还有一个很巧妙的约定:如果 Agent 检查完发现"没什么值得汇报的",就以 [SILENT] 开头回答,deliver 检测到前缀后直接跳过发送。这样心跳巡检可以跑得密密的——每次只花一次模型调用,但不会刷屏打扰你(避免"通知疲劳")。💡

三、三种触发方式:Cron、sleep 与远程触发器

1️⃣ Cron:真正的"到点自动开工"

周期性任务触发后会重新装填(re-arm 到 now + every),一次性任务触发后自动删除。durable 任务会被存成 JSON 文件(scheduled_tasks.json),下次启动时 Scheduler 用同一路径重建即可自动恢复——今天排的"每晚 10 点备份",重启进程后依然有效。

⚠️ 注意一个常见误区:durable ≠ 永远开机。本地 durable 计划只在"进程重启"后存活;如果主机直接关机,它是不会 fire 的。想要离线也能触发,需要配合下面第 3 种方式。

2️⃣ Sleep:延迟一小段时间再干

Claude Code 等系统提供的 SleepTool 本质就是一个延迟的 one-shot 调度。官方 demo 演示的正是这个:把一个 prompt 排在 1 秒后,启动 tick 线程,等时钟追上后,调度器自动入队,driver 把它当新用户轮次执行——全程没有人按回车。

learn-agent-architecture 第13章 后台执行与通知队列机制图

这里和第 13 章 Background execution的思想一脉相承:耗时工作在 loop 之外跑,结果通过队列 + 通知在后续轮次注入。调度的 tick 线程就是建立在第 13 章的后台执行能力之上(daemon 线程,永不阻塞主 loop)。

3️⃣ 远程触发器:主机不在线也能被叫醒

本地时钟的最大限制是"主机得开着"。remote trigger 的思路是把触发源外置:一个常开的网关服务(gateway)持有任务列表,到点后把 prompt 投递给 Agent 进程。

  • Hermes Agent 就是典型:gateway 本身是 server 进程,cron 按用户时区在 gateway tick 上触发,无人值守也能 fire,输出直接投递到聊天平台。
  • 入站消息一侧由第 19 章 MCP / plugins / channels补齐:Slack、SMS 等外部消息经 gate 过滤后包成 <channel> 标签进入队列,和调度触发走的是同一条路。

官方教程给出的选择顺序很值得记住:能用推送就用推送(来源能主动调用 Agent,触发零成本)→ 不支持推送才用心跳轮询 → 真正和时间绑定的工作(比如周一报表)才用 Cron。

四、动手跑起来:两条命令,先离线后在线

git clone https://gitcode.com/gh_mirrors/aw/learn-agent-architecture
cd learn-agent-architecture

第一步:离线自检(不需要 API key、不联网)。test.py 用一个"假时钟"手动拨时间,确定性验证一次性触发、周期重装填、重启重载、channel 投递和 [SILENT] 静默:

python sections/14-scheduling/src/test.py         # 输出 14 scheduling: ok

第二步:在线 demo(需要 ANTHROPIC_API_KEY)。demo.py 排一个"1 秒后统计文件数"的一次性任务,看着它自己 fire、自己跑完一个完整 Agent 轮次,并把答案投到 console channel:

uv run python sections/14-scheduling/src/demo.py

完整章节讲解(含各系统对比与更多细节)见 第 14 章 Scheduling。

五、避坑清单:生产环境最常见的 5 个坑

  1. 重复触发(Double fire):一次很快的 tick 可能在同一个 cron 分钟内命中两次 → 记录"上一次触发的分钟"去重。
  2. 大量任务同一时刻 fire:给周期任务加确定性 jitter,把触发时间错开。
  3. cron 表达式写错:在 create 时就校验,加载时跳过无效条目。
  4. loop 正忙:不要强行插入——prompt 入队,等两轮之间再 drain(本章的标准做法)。
  5. 通知疲劳:心跳每次 tick 都汇报,用户很快学会无视它 → 让 prompt 自己判断"值不值得说",否则回 [SILENT]。

另外还有一个物理限制:时钟是"取样",不是"盯事件"。两次 tick 之间出现又消失的变化它看不见——解决办法是改读日志/游标,或者把来源换成推送。

六、进阶:调度只是"让 loop 自己动起来"的第一步

当 Agent 能按时醒来后,还可以继续往下看学习路径(完整路线图见 各章节):

总结:调度的精髓只有一句话——时钟只负责入队,loop 负责执行。把"何时做"存成数据,让 fire 动作退化成一次普通的入队,所有既有的权限、记忆、恢复机制就自动全部生效。这也是 learn-agent-architecture 教会你的最重要的一课:强大的 Agent 能力,往往来自 loop 外面那一层薄薄的 harness。⚡

登录后查看全文
learn-agent-architecture