定时任务

定时任务接口需要 Bearer Key，并且只操作当前账号的任务。

接口

方法与路径	说明
GET /api/v1/schedule/tasks	查询任务列表。
POST /api/v1/schedule/tasks	创建任务，成功返回 201。
GET /api/v1/schedule/tasks/{id}	查询单个任务。
PATCH /api/v1/schedule/tasks/{id}	更新任务或状态。
DELETE /api/v1/schedule/tasks/{id}	删除任务，成功返回 204。
POST /api/v1/schedule/tasks/{id}/run	立即异步执行任务。

任务对象包含以下字段（时间戳均为 Unix 毫秒）：

字段	类型	说明
id	string	任务 ID
agentId	string	智能体 ID
agentName	string?	智能体展示名称
name	string	任务名称
description	string	描述
cron	string	标准 5 段 cron
timezone	string	IANA 时区
prompt	string	运行时发送给智能体的内容
status	string	active、paused、archived
enabled	boolean	是否启用（与 status 一致）
healthOk	boolean?	智能体可用性健康检查
healthReason	string?	健康检查失败原因
lastSessionId	string?	最近一次运行的会话 ID
runCount	number	已运行次数
lastRunAt	number?	最近运行时间
lastRunOk	boolean?	最近运行是否成功
lastRunError	string?	最近运行错误信息
nextRunAt	number?	下次运行时间
createdAt	number	创建时间
updatedAt	number	更新时间

查询任务列表

无参数。

GET /api/v1/schedule/tasks HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200，data 为 { items }：

{
  "code": "0",
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "sc-01JQ2R8X1A3B4C5D6E7F8GB",
        "agentId": "raagent/daily-report-9c4d2e1f",
        "agentName": "日报助手",
        "name": "工作日报",
        "description": "每个工作日生成日报",
        "cron": "0 18 * * 1-5",
        "timezone": "Asia/Shanghai",
        "prompt": "汇总今天的工作并生成日报",
        "status": "active",
        "enabled": true,
        "healthOk": true,
        "healthReason": null,
        "lastSessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
        "runCount": 8,
        "lastRunAt": 1722730200000,
        "lastRunOk": true,
        "lastRunError": null,
        "nextRunAt": 1722783600000,
        "createdAt": 1722600000000,
        "updatedAt": 1722730200000
      }
    ]
  }
}

错误：401 凭据缺失或无效。

创建任务

字段	位置	类型	必填	可选值	默认值	限制
name	Body	string	是	—	—	最短 1
agentId	Body	string	是	当前账号可用智能体 ID	—	最短 1
cron	Body	string	是	标准 5 段 cron	—	进一步由 cron 解析器验证
timezone	Body	string	否	IANA 时区，例如 Asia/Shanghai、UTC	Asia/Shanghai	必须是有效 IANA timezone
description	Body	string	否	—	空字符串	—
prompt	Body	string	否	运行时发送给智能体的内容	空字符串	—

POST /api/v1/schedule/tasks HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{
  "name": "工作日报",
  "agentId": "raagent/daily-report-9c4d2e1f",
  "cron": "0 18 * * 1-5",
  "timezone": "Asia/Shanghai",
  "description": "每个工作日生成日报",
  "prompt": "汇总今天的工作并生成日报"
}

HTTP 201，data 为创建后的任务对象：

{
  "code": "0",
  "message": "ok",
  "data": {
    "id": "sc-01JQ2R8X1A3B4C5D6E7F8GB",
    "agentId": "raagent/daily-report-9c4d2e1f",
    "agentName": "日报助手",
    "name": "工作日报",
    "description": "每个工作日生成日报",
    "cron": "0 18 * * 1-5",
    "timezone": "Asia/Shanghai",
    "prompt": "汇总今天的工作并生成日报",
    "status": "active",
    "enabled": true,
    "healthOk": true,
    "healthReason": null,
    "lastSessionId": null,
    "runCount": 0,
    "lastRunAt": null,
    "lastRunOk": null,
    "lastRunError": null,
    "nextRunAt": 1722783600000,
    "createdAt": 1722600000000,
    "updatedAt": 1722600000000
  }
}

错误：400 校验失败（如 cron 无法解析、timezone 无效、智能体不可用）；401 凭据缺失或无效；404 智能体不存在。

查询单个任务

参数	位置	类型	必填	可选值	默认值	限制
id	Path	string	是	当前账号的任务 ID	—	最短 1

GET /api/v1/schedule/tasks/sc-01JQ2R8X1A3B4C5D6E7F8GB HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200，data 为任务对象：

{
  "code": "0",
  "message": "ok",
  "data": {
    "id": "sc-01JQ2R8X1A3B4C5D6E7F8GB",
    "agentId": "raagent/daily-report-9c4d2e1f",
    "agentName": "日报助手",
    "name": "工作日报",
    "description": "每个工作日生成日报",
    "cron": "0 18 * * 1-5",
    "timezone": "Asia/Shanghai",
    "prompt": "汇总今天的工作并生成日报",
    "status": "active",
    "enabled": true,
    "healthOk": true,
    "healthReason": null,
    "lastSessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
    "runCount": 8,
    "lastRunAt": 1722730200000,
    "lastRunOk": true,
    "lastRunError": null,
    "nextRunAt": 1722783600000,
    "createdAt": 1722600000000,
    "updatedAt": 1722730200000
  }
}

错误：404 任务不存在或不属于当前账号。

更新任务或状态

参数	位置	类型	必填	可选值	默认值	限制
id	Path	string	是	当前账号的任务 ID	—	最短 1

PATCH 字段均为可选：

字段	位置	类型	必填	可选值	默认值	限制
name	Body	string	否	—	—	最短 1
agentId	Body	string	否	当前账号可用智能体 ID	—	最短 1
cron	Body	string	否	标准 5 段 cron	—	进一步由 cron 解析器验证
timezone	Body	string	否	有效 IANA timezone	—	最短 1
description	Body	string	否	—	—	—
prompt	Body	string	否	—	—	—
status	Body	string	否	active、paused、archived	—	—

PATCH /api/v1/schedule/tasks/sc-01JQ2R8X1A3B4C5D6E7F8GB HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{
  "name": "工作日晚报",
  "timezone": "Asia/Shanghai",
  "status": "paused"
}

HTTP 200，data 为更新后的任务对象：

{
  "code": "0",
  "message": "ok",
  "data": {
    "id": "sc-01JQ2R8X1A3B4C5D6E7F8GB",
    "agentId": "raagent/daily-report-9c4d2e1f",
    "agentName": "日报助手",
    "name": "工作日晚报",
    "description": "每个工作日生成日报",
    "cron": "0 18 * * 1-5",
    "timezone": "Asia/Shanghai",
    "prompt": "汇总今天的工作并生成日报",
    "status": "paused",
    "enabled": false,
    "healthOk": true,
    "healthReason": null,
    "lastSessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
    "runCount": 8,
    "lastRunAt": 1722730200000,
    "lastRunOk": true,
    "lastRunError": null,
    "nextRunAt": null,
    "createdAt": 1722600000000,
    "updatedAt": 1722730200000
  }
}

恢复任务时将 status 更新为 active。修改 cron、timezone 或状态后，调度器会按新配置计算下一次执行时间。错误：400 校验失败；404 任务不存在或不属于当前账号。

删除任务

参数	位置	类型	必填	可选值	默认值	限制
id	Path	string	是	当前账号的任务 ID	—	最短 1

DELETE /api/v1/schedule/tasks/sc-01JQ2R8X1A3B4C5D6E7F8GB HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 204，无响应体。删除后调度器停止该任务。错误：404 任务不存在或不属于当前账号。

立即执行

参数	位置	类型	必填	可选值	默认值	限制
id	Path	string	是	当前账号的任务 ID	—	最短 1

POST /api/v1/schedule/tasks/sc-01JQ2R8X1A3B4C5D6E7F8GB/run HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

HTTP 202，响应不使用统一 envelope：

{
  "sessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
  "status": "processing"
}

202 只表示运行已接受。随后使用 GET /api/v1/sessions/{id} 和 GET /api/v1/sessions/{id}/messages 查询状态与结果。错误：404 任务不存在；400 智能体不可用；503 运行所需服务暂不可用。