Octop 定时任务 API：通过 REST 计划自动化专家任务

使用 Octop 的 /api/agents//cron 端点，通过 cron 表达式、间隔或一次性日期计划自动化专家任务。

使用 cron 表达式、间隔或一次性日期计划专家任务，实现自动化。

​

路由

/api/agents/{agent_id}/cron

​

端点

方法	路径	描述
GET	/cron/settings	获取服务器时区信息
GET	/agents/{aid}/cron	列出定时任务
POST	/agents/{aid}/cron	创建定时任务
GET	/agents/{aid}/cron/{cid}	获取定时任务详情
PATCH	/agents/{aid}/cron/{cid}	更新定时任务
DELETE	/agents/{aid}/cron/{cid}	删除定时任务
POST	/agents/{aid}/cron/{cid}/run-now	立即触发任务

​

创建定时任务

​

每日早报

curl -X POST http://127.0.0.1:8088/api/agents/1/cron \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "每日早报",
    "trigger": "0 9 * * *",
    "prompt": "总结今日待办事项并发送早报",
    "task_type": "agent"
  }'

​

每 30 分钟一次

curl -X POST http://127.0.0.1:8088/api/agents/1/cron \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "trigger": "interval:30",
    "prompt": "检查未处理的工单",
    "task_type": "text"
  }'

​

一次性任务

curl -X POST http://127.0.0.1:8088/api/agents/1/cron \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "trigger": "date:2025-06-01T09:00:00",
    "prompt": "发送发布提醒",
    "task_type": "agent"
  }'

​

请求字段

name · string

可选显示名称。省略时服务端从 prompt 推导。

trigger · string · 必填

触发定义。cron 表达式、interval:N（分钟）或 date:ISO8601。

prompt · string · 必填

触发时发送给专家的提示词。最大 2000 个字符。

task_type · string

"agent"（完整专家回合）或 "text"（简单文本生成）。

session_key · string

复用现有对话会话而不是创建新会话。

fresh_thread · boolean

若为 true，每次触发都创建一个全新的对话线程。

model · string

仅对此定时任务覆盖默认模型。

​

触发器格式

格式	示例	描述
cron 表达式	0 9 * * *	标准 5 字段 cron 语法
interval:N	interval:30	每 N 分钟重复
date:ISO8601	date:2025-06-01T09:00:00	单次执行

cron 表达式根据服务器时区解析。通过 GET /api/cron/settings 获取当前服务器时区。

​

立即运行

无需等待下一个计划运行即可立即触发任务：

curl -X POST http://127.0.0.1:8088/api/agents/1/cron/3/run-now \
  -H 'Authorization: Bearer <token>'

返回 204 No Content，将任务入队立即执行，不影响其下一个计划运行时间。

将 fresh_thread 与每日 cron 任务结合使用，可为每天创建独立、按日期划分的对话线程，避免历史信息相互干扰。