让Omni自动干活:定时Agent运行与后台任务调度的完整教程

原创2026-10-26 09:52:531,963 阅读

让Omni自动干活:定时Agent运行与后台任务调度的完整教程

Omni 是一款开源、可自托管的 AI Agent,能够跨各种工作工具查找上下文、分析信息并执行任务。本教程带你掌握 Omni 定时 Agent 运行与后台任务调度功能:创建一个 Agent、配置 cron 或间隔调度,让它无需人工干预地定期自动执行工作,并了解底层队列如何保证任务可靠完成。

Omni 定时 Agent 项目配置界面,展示任务指令与数据源范围设置

什么是 Omni 的定时 Agent:给 AI 装上一块"时钟"

在 Omni 中,Agent 是一个可以被自动触发的 AI 工作者。你只需写下任务指令(例如"汇总本周的邮件和待办事项"),再指定运行计划,Omni 就会到点自动执行、把结果记录下来。

与普通对话不同,定时 Agent 是非交互式的:它不会等你确认,而是按白名单自主完成工具调用。核心能力包括:

  • 🕐 两种调度方式:cron 表达式(如"每周一 9 点")和 interval 间隔(如"每 3600 秒"),见 cron_utils.py
  • 🔐 数据源白名单:每个 Agent 只能访问你勾选的数据源,并支持单独授予读(read)/写(write)权限
  • 💾 持久化运行记录:每次运行都会落库,可查状态、摘要和完整执行日志
  • 🔁 自动重试:失败后按 30s / 120s / 300s 退避重试,最多 3 次

Agent 与运行记录的数据结构定义在 065_create_agents_tables.sql 迁移脚本中,包含 agents(Agent 定义)和 agent_runs(运行历史)两张表。

创建定时 Agent:四步从零配置

在 Omni 网页端进入 Agents 页面,点击新建即可进入配置表单(源码位于 web/src/routes/(app)/agents/new/+page.svelte/agents/new/+page.svelte))。

第一步:填写名称与任务指令

名称是 Agent 的标识,指令(Instructions)则直接决定它"干什么活"。写得越具体,结果越可靠,例如:

"每天早上检查邮件数据源中未读的重要邮件,整理成简报摘要,标注紧急程度。"

第二步:选择执行计划(cron 或 interval)

表单内置了常用调度预设,覆盖了绝大多数使用场景:

预设 调度类型 实际值 说明
Every hour interval 3600 每小时一次
Every 6 hours interval 21600 每 6 小时一次
Daily at 9am cron 0 9 * * * 每天上午 9 点
Weekly Monday 9am cron 0 9 * * 1 每周一上午 9 点
Custom cron cron 自定义表达式 自由编写 cron

interval 的值单位是秒;cron 采用标准五段式表达式(分 时 日 月 周)。所有表达式在保存前都会经过 validate_schedule 校验,非法值无法提交。

第三步:圈定数据源与权限范围

在数据源列表中勾选 Agent 可访问的来源,每个来源可分别开启 read(只读检索)和 write(允许写入)权限。默认只读,这样定时任务不会误改你的数据——这是后台自动运行的安全底线。

第四步:选择模型并发布

可为 Agent 指定专用模型;不选时使用工作区默认模型,避免运行时因"未配置模型"而失败。点击创建后跳转到 Agent 详情页,任务即进入调度队列。

手动触发与实时进度跟踪

除了定时自动运行,你还可以随时手动触发一次任务,适合先"试跑"验证效果:

  • 触发接口:POST /agents/{agent_id}/trigger,成功后返回 202 和 run_id(实现见 routers/agents.py)
  • 若该 Agent 已有任务正在执行,会返回 409 agent_already_active,保证同一 Agent 不会并发跑两份
  • 进度跟踪:GET /agents/{agent_id}/runs/{run_id}/stream 以 SSE(Server-Sent Events)推送实时事件,前端可逐条展示 Agent 的思考与工具调用

每次运行的状态机为 pending → running → completed / failed,运行中的 Agent 会实时写入执行日志,方便事后复盘。

后台任务调度的三层架构

理解调度如何"可靠地自动干活",只需抓住三层结构:

1️⃣ 调度物化器(Scheduler Materializer)

scheduler.py 中的物化器默认每 30 秒轮询一次数据库,找出到期的 Agent,为其创建一条 pending 运行记录。它只负责"登记任务",从不直接执行——这样调度与执行彻底解耦,重启也不丢任务。若某 Agent 已有活动运行,当轮会安全跳过。

2️⃣ 持久化任务队列(Durable Queue)

pending 记录存储在 PostgreSQL 中,属于"持久化工作项"。队列工作器通过带租约(lease)的认领机制领取任务:认领后状态变为 running,并生成 claim_token 和租约截止时间(默认 300 秒),防止多个节点重复执行同一个任务。

3️⃣ 执行工作器(Queue Worker)

queue_worker.py 领取任务后交给 executor.py 执行——它镜像了聊天循环,但没有流式输出和人工审批环节,最多迭代 15 轮工具调用。执行期间每 30 秒发送一次心跳续租;即使进程崩溃,陈旧租约恢复循环也会在 30 秒内发现并重新分配任务,实现"至少一次"的投递语义。

可调的调度参数一览

所有调度参数都通过环境变量配置(见 config.py),默认值对大多数部署已经够用:

参数 默认值 作用
AGENT_SCHEDULER_POLL_INTERVAL 30 秒 调度轮询间隔
AGENT_MAX_CONCURRENT_RUNS 3 同时运行的 Agent 任务上限
AGENT_RUN_LEASE_SECONDS 300 秒 任务租约时长
AGENT_RUN_HEARTBEAT_INTERVAL_SECONDS 30 秒 心跳续租间隔
AGENT_RUN_MAX_ATTEMPTS 3 失败最大重试次数
AGENT_RUN_BACKOFF_SECONDS 30,120,300 重试退避时间
AGENT_MAX_ITERATIONS 15 单次运行最大工具调用轮数
AGENT_RUN_CLAIM_POLL_INTERVAL_SECONDS 5 秒 队列认领轮询间隔

💡 调优建议:任务变多时调大 AGENT_MAX_CONCURRENT_RUNS;需要更精确的触发时间时调小 AGENT_SCHEDULER_POLL_INTERVAL(触发精度不会超过轮询间隔)。

常见问题(FAQ)

Q:到点没有触发? 先确认 Agent 处于启用状态(is_enabled),再看调度轮询是否在运行——日志中会打印 "Agent schedule materializer started"。若该 Agent 上一次运行还没结束,本轮会被跳过。

Q:任务失败后会怎样? 按 30s → 120s → 300s 退避重试,最多 3 次;仍失败则标记为 failed 并记录错误信息,可在运行历史中查看摘要。

Q:Agent 能写数据吗? 只有你在白名单中显式授予 write 权限的数据源才可以,且组织级 Agent 还支持 allowed_actions 工具白名单进一步收窄能力范围。

总结

Omni 的定时 Agent + 后台任务调度,让"AI 自动干活"变得简单又可靠:

  1. 四步配置:指令 + 调度计划 + 数据源白名单 + 模型
  2. 两种调度:cron 表达式与秒级间隔,覆盖从每小时到每月的计划
  3. 可靠性兜底:持久化队列、租约认领、心跳续租、失败退避重试,全程无需人工看管

现在就可以创建一个"每日晨报 Agent",体验把重复工作完全交给 Omni 的省心感 🚀

登录后查看全文
omni