# 创建定时任务

`POST` `/api/agent/schedule/create`

创建新的定时任务并注册到调度器，支持一次性(ONE_TIME)、周期性(RECURRING)和Cron表达式(CRON)三种触发类型。支持通过 bizKey 标识会话（优先级高于 sessionId），支持通过 reuseSession 控制是否复用会话。支持配置与异步运行智能体接口同口径的运行时变量、能力限制、模型思考参数和输出格式。运行特性随任务固化并在每次触发时生效；全部不传时仍在执行时读取智能体最新配置。capabilityConfig只能收窄智能体已有能力，使用该字段时必须明确传入agentId。时间参数使用北京时间，格式 yyyy-MM-dd HH:mm:ss。

**触发类型（triggerType）**：
- ONE_TIME：一次性任务，在指定时间执行一次，执行后不再触发
- RECURRING：周期性任务，从起始时间开始按固定时间间隔重复执行
- CRON：Cron 表达式任务，按标准 Cron 表达式定义的时间规则执行

**响应中 triggerConfig 的时间口径**：
triggerConfig 以 JSON 字符串返回，其中 executeTime、startTime 为北京时间，格式 yyyy-MM-dd HH:mm:ss，与创建/修改时传入的时间口径一致，也与同一响应中的 nextExecutionTime、createdAt 保持一致。
历史上该字段曾以 UTC 的 ISO-8601（如 2026-09-07T16:00:00Z）返回，如果您解析了这两个时间字段，请按北京时间解析，不要再当作 UTC 处理；仅透传或展示该字段的调用方不受影响。

**迁移存量任务**：把其它系统的任务迁移进本平台时，可传入 createdAt 保留源端的创建时间，使迁移后任务列表按创建时间排序的表现与源端一致。该参数只覆盖任务的创建时间，不参与调度计算，首次触发时间仍完全由 triggerConfig 决定。
另有两点由 triggerConfig 本身决定、与 createdAt 无关的注意点：
- 源端已过期的 ONE_TIME 任务会因 executeTime 不是未来时间被拒绝，需要在迁移前自行过滤
- startTime 落在过去的 RECURRING 任务，注册后会被调度器视为逾期并立即真实执行一次（真实调用模型并投递结果），迁移时请先把 startTime 归一到未来时间

创建成功后任务的 taskStatus 为 ENABLED、scheduleState 为 SCHEDULED，可通过 nextExecutionTime 查看下次触发时间。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| taskName | string | 是 | 任务名称，用于展示和识别任务 |
| agentId | integer | 否 | 绑定的智能体ID，为空时使用主体的默认智能体 |
| bizKey | string | 否 | 业务键，用于标识任务关联的会话。传入后通过 bizKey 解析出对应的会话ID，优先级高于 sessionId |
| sessionId | integer | 否 | 来源会话ID，记录任务创建的上下文会话 |
| description | string | 否 | 任务描述，补充说明任务用途 |
| triggerType | string | 是 | 触发类型，可选值：ONE_TIME（一次性任务，在指定时间执行一次，执行后不再触发）、RECURRING（周期性任务，从起始时间开始按固定时间间隔重复执行）、CRON（Cron表达式任务，按标准Cron表达式定义的时间规则执行） |
| triggerConfig | TriggerConfigRequest | 是 | 触发配置，根据触发类型填写对应字段 |
|     executeTime | string | 否 | 执行时间（ONE_TIME 类型必填），北京时间，格式 yyyy-MM-dd HH:mm:ss |
|     startTime | string | 否 | 起始时间（RECURRING 类型必填），北京时间，格式 yyyy-MM-dd HH:mm:ss |
|     intervalSeconds | integer | 否 | 间隔秒数（RECURRING 类型必填），最小60秒 |
|     cronExpression | string | 否 | Cron表达式（CRON 类型必填），6字段格式：秒 分 时 日 月 周 |
| userInput | string | 是 | 任务触发时发送给智能体的指令，描述智能体应该执行的具体任务 |
| reuseSession | boolean | 否 | 是否复用会话，开启后任务执行时复用已有会话而非每次新建。开启时必须传入 sessionId 或 bizKey |
| runtimeVariables | object | 否 | 运行时变量，随任务保存并在每次触发时回填运行上下文。Finx服务可通过${ctx.KEY}占位符读取，沙箱脚本可通过同名环境变量读取。变量不得包含密码、密钥等敏感信息 |
| capabilityConfig | AgentRunCapabilityConfigRequest | 否 | 任务运行时的工具、Skill和Finx服务能力限制。未传时沿用智能体配置；传入时只能进一步收窄智能体已有能力，不能重新启用智能体已禁用的能力。该配置随任务固化，每次触发时生效 |
|     toolsEnabled | boolean | 否 | 是否允许调用工具。false时包括Skill在内的所有工具均不可调用；true不能重新启用智能体已禁用的工具 |
|     disabledTools | array | 否 | 本次运行额外禁用的工具内部名称列表，名称必须与系统注册名称精确匹配 |
|     enabledToolsOnly | array | 否 | 本次运行仅允许使用的工具内部名称列表，传入非空集合时采用白名单模式。需要调用Skill时必须包含skill |
|     skillsEnabled | boolean | 否 | 是否启用Skill。false表示禁用所有Skill；true不能突破智能体配置和工具层限制 |
|     disabledSkills | array | 否 | 本次运行额外禁用的Skill内部名称列表，名称必须与系统注册名称精确匹配 |
|     enabledSkillsOnly | array | 否 | 本次运行仅允许使用的Skill内部名称列表，传入非空集合时采用白名单模式 |
|     disabledFinxServices | array | 否 | 本次运行禁用的Finx服务内部名称列表，传入非空集合时采用黑名单模式。enabledFinxServicesOnly传入非空集合时，以白名单模式为准。 |
|     enabledFinxServicesOnly | array | 否 | 本次运行仅允许使用的Finx服务内部名称列表，传入非空集合时采用白名单模式。该字段优先级高于disabledFinxServices；同一服务同时出现在两个集合中时，以本字段为准。 |
| enableThinking | boolean | 否 | 是否启用思考模式（已废弃，请使用reasoningEffort）。true等效high，false等效disabled |
| reasoningEffort | string | 否 | 推理力度档位，可选值：disabled、low、medium、high、xhigh。参数优先级：thinkingBudget > reasoningEffort > enableThinking > 智能体默认档位 |
| thinkingBudget | integer | 否 | 思维链Token预算。传入后优先级高于reasoningEffort；内核会自动修正到模型支持范围 |
| temperature | number | 否 | 模型温度，取值范围0~2；不传时使用系统默认值 |
| supportedOutputFormats | array | 否 | 调用终端支持渲染的输出格式列表。例如传入echarts后，模型可输出ECharts图表代码块 |
| createdAt | string | 否 | 源端创建时间，仅用于将存量任务从其它系统迁移到本平台的场景，北京时间，格式 yyyy-MM-dd HH:mm:ss。传入后仅覆盖任务记录的创建时间，使迁移后任务列表按创建时间排序的表现与源端一致；不参与任何调度计算，nextExecutionTime、调度状态以及 triggerConfig 中的时间全部按原有逻辑处理。取值须不早于 2000-01-01 00:00:00 且不晚于当前时间，否则返回参数错误。不传时取系统当前时间 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | TaskInfo | 响应数据 |
|     id | integer | - |
|     sessionId | integer | - |
|     agentId | integer | - |
|     taskName | string | - |
|     description | string | - |
|     triggerType | string | 触发类型。ONE_TIME：一次性任务，在指定时间执行一次，执行后不再触发；RECURRING：周期性任务，从起始时间开始按固定时间间隔重复执行；CRON：Cron 表达式任务，按标准 Cron 表达式定义的时间规则执行 |
|     triggerConfig | string | - |
|     taskStatus | string | 任务开关状态，由调用方主动控制，暂停或恢复任务时改变。ENABLED：启用中，任务处于生效状态，会按配置的触发规则自动执行；DISABLED：已暂停，任务配置保留，但不再触发执行，可随时恢复。建议将该字段用于渲染「暂停 / 恢复」操作按钮的开关态 |
|     deliveryChannel | string | - |
|     scheduleState | string | 实时调度状态，由系统根据任务的实际调度情况实时计算，反映此刻任务在做什么。SCHEDULED：等待执行，任务已排入调度计划，将在 nextExecutionTime 指定时间触发；RUNNING：执行中，任务已被触发，正在运行；NOT_SCHEDULED：无后续执行计划，任务被暂停，或一次性任务已执行完毕。建议将该字段作为任务的主展示状态 |
|     nextExecutionTime | string | 下次触发时间，北京时间，格式 yyyy-MM-dd HH:mm:ss。scheduleState 为 NOT_SCHEDULED 时任务无后续执行计划，该字段为空 |
|     totalExecutionCount | integer | - |
|     createdAt | string | - |
|     payload | string | - |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |