第7章 定时任务 · Omnigent

定时任务 定时任务是一种已保存的提示词，按预定义周期自动触发 Agent 会话。指定目标 Agent、提示词、重复规则以及运行位置，Omnigent 便会在每次计划时间点自动启动该 Agent，无需人工值守。 定时任务由四个内置工具管理，所有 Agent 均可直接调用。这些工具属于框架层面并自动注册，因此 Agent 可以在运行时自行创建、查询、更新或删除自己的周期性任务，无需在 Agent YAML 配置中显式启用。底层实现上，Runner 会将这些工具调用映射到 Omnigent 服务器的 /v1/scheduled-tasks REST 接口。 内置工具 工具 | 说明 sys_scheduled_task_create | 创建周期性任务 sys_scheduled_task_list | 列出你的定时任务及其调度和状态 sys_scheduled_task_update | 更新任务的可变字段 sys_scheduled_task_delete | 删除任务，使其停止触发 任务的作用域限定在调用者（或在禁用认证时的单个本地用户）。你只能查看和管理自己的任务；无法枚举或操作他人拥有的任务。 创建任务 sys_scheduled_task_create 接受以下字段： - name（必填）— 人类可读的任务名称，例如 nightly triage。 - prompt（必填）— 每次触发时下发给 Agent 的指令。 - rrule（必填）— 重复规则（见“重复规则”一节）。 - agent_id（必填）— 要运行的 Agent，例如 ag_abc123（可通过 sys_agent_list 或 sys_agent_get 获取）。 - execution_target（可选）— 每次触发的运行位置：connected_host（默认）或 managed_sandbox。详见“任务运行位置”。 - host_id（可选，仅限 connected_host）— 将运行锁定到当前工作区的特定已连接主机。若省略，任务将在触发时运行于你在线的主机上；若当时无在线主机，则会记录一次失败运行。已存在的托管沙箱主机不可被锁定。 - workspace（可选，仅限 connected_host）— 主机上的现有绝对路径，用于启动触发会话的 Runner。必须配合 host_id 使用；若省略，则从该主机的家目录启动。 - timezone（可选）— 评估规则所用的 IANA 时区，例如 America/Los_Angeles。默认为 UTC。 - model_override（可选）— 针对单次运行的模型覆盖设置。若省略，则使用 Agent 默认模型。 - reasoning_effort（可选）— 针对单次运行的推理强度提示，例如 high。若省略，则使用 Agent 默认值（即规范中的 executor.reasoning_effort，或规范未设置时的 harness 默认值）。 创建完成后，任务会按计划自动触发，直至被删除。 重复规则 调度基于 RFC 5545 RRULE 字符串，并在任务的时区内进行求值。示例如下： FREQ=DAILY;BYHOUR=9;BYMINUTE=0 # 每天上午9点 FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0 # 工作日上午9点 规则在创建或更新任务时会被校验。若语法错误、永远不会触发、仅触发一次或触发频率高于最小间隔，规则将被拒绝（返回 HTTP 400）。任务至少需触发两次，且频率不得超过每小时一次——任意两次连续触发之间的最小间隔为 60 分钟。 暂停、更新与删除 sys_scheduled_task_update 仅修改传入的字段，其余保持不变。可更新的字段包括：name、prompt、rrule、timezone、model_override、reasoning_effort、workspace、host_id、execution_target 以及 state。 将 execution_target 设为 managed_sandbox 会将任务切换至每次运行都创建新沙箱的模式，并清除已锁定的 host_id 和 workspace；请勿在同一次更新中设置这两个字段。若切换回 connected_host，任务将处于未锁定状态，直到重新指定主机。 state 字段接受 active 或 paused 两个值： - 传入 state=paused 可暂停任务触发而不删除。 - 传入 state=active 可恢复任务。 若要彻底移除任务，请使用 sys_scheduled_task_delete，删除操作无法通过 update 完成。 任务运行位置 execution_target 决定每次触发时任务运行在哪台机器上。 connected_host（默认） 任务运行在你自己的某台已连接主机上。可以通过 host_id（以及可选的 workspace）锁定特定主机，或者两者都留空，由 Omnigent 在任务触发时解析你最近活跃的在线主机，并从该主机的家目录启动。服务器托管的沙箱主机永远不会被此解析逻辑选中，锁定此类主机作为 host_id 也会被拒绝——交互式会话中产生的热沙箱若其状态泄漏到运行中会造成破坏，且一旦沙箱销毁即失效。 若无法解析到在线主机（或锁定的主机离线），本次触发将被记录为失败运行。 managed_sandbox 每次触发都会创建一个全新的服务器托管沙箱——这与在聊天中选择“新建沙箱”的路径相同（参见“云沙箱主机”）。会话在沙箱内由服务器创建的干净工作区中启动，因此 host_id 和 workspace 必须留空；若创建或更新时将它们与 managed_sandbox 组合使用，请求会被拒绝。服务器必须已配置托管沙箱——未配置的服务器会在创建时拒绝该任务，而不是在每次触发时失败。 自动化创建的沙箱遵循服务器标准的沙箱生命周期，与聊天创建的沙箱完全一致：自动化本身不会覆盖超时设置，也不会在运行结束时终止沙箱。服务器管理员应根据自动化频率和资源预算，选择合适的作用域、空闲超时及清理策略；仅启用托管沙箱并不能保证短关机时间。 触发时如何运行 当任务到达预定时间时，Omnigent 会： 1. 重新读取任务记录——若任务在计时器启动后已被删除或暂停，则跳过本次触发。在内置账户认证模式下，运行还会确认任务所有者仍是已注册的同一账户，且目标 host_id 属于该所有者；若任务所有者账户已被移除，任务将被标记为已删除，运行记录中会标记错误码 owner_deleted。 2. 仅为本次触发解析启动目标。connected_host 任务按上述方式填充未锁定的主机和工作区；managed_sandbox 任务无主机启动，并在第 4 步绑定新沙箱。解析出的值绝不会写回任务记录。 3. 创建绑定到任务 Agent 的会话，携带存储的 model_override 和 reasoning_effort，并授予任务所有者对新会话的所有权，以便查看运行过程。 4. 启动 Runner——在解析出的主机上，或在全新建的沙箱中——并下发提示词，使 Agent 实际执行。 5. 记录本次运行——更新任务的最后运行时间戳和运行的对话 ID。 几项调度保证： - 数据库是唯一事实来源。服务器启动时，所有处于 active 状态的任务都会从存储中重新布防。 - 错过的触发不会补发。若服务器在任务预定时间宕机，只会布防下一个未来时间点——Omnigent 不会回填过去的触发。 - 重叠触发会被跳过。若下一次触发到来时，上一次运行仍在进行中，则该次触发将被丢弃。 - 被移除的账户停止触发。当管理员移除某成员时，该用户的所有任务会被标记为已删除。若该用户名后续被重新注册，也不会看到或继承旧账户的任务。