• 简体中文

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

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

      路由

      /api/agents/{agent_id}/cron

      端点

      方法路径描述
      GET/cron/settings获取服务器时区信息
      GET/agents/{aid}/cron/examples工作区 .octop/manifest.json 的 {task_examples}（{zh,en} 字符串数组，展示时规范为 3 或 6 条）；缺失则为 null（页面保留默认卡片）。优先用同样带该字段的 GET /agents/{aid}/chat/welcome
      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"
  }'

      请求字段

      namestringbody

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

      triggerstringbody必填

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

      promptstringbody必填

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

      task_typestringbody

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

      session_keystringbody

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

      fresh_threadbooleanbody

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

      modelstringbody

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

      触发器格式

      格式示例描述
      cron 表达式0 9 * * *标准 5 字段 cron 语法
      interval:Ninterval:30每 N 分钟重复
      date:ISO8601date: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 任务结合使用，可为每天创建独立、按日期划分的对话线程，避免历史信息相互干扰。