# 修改定时任务

`POST` `/api/agent/schedule/update`

修改指定定时任务的名称、描述、触发配置和执行指令，支持通过 reuseSession 控制是否复用会话。支持修改运行时变量、能力限制、模型思考参数和输出格式。任一运行特性字段传入时整组重建，未传字段回退到修改时点的智能体配置或系统默认值；runtimeVariables除外：不传保留，传空对象清除，传非空对象整体覆写。capabilityConfig只能收窄任务绑定智能体的已有能力。

**触发类型（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 处理；仅透传或展示该字段的调用方不受影响。

修改触发配置后调度计划会重新计算，可通过返回结果的 scheduleState 和 nextExecutionTime 确认新的调度情况。

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

## 请求参数

### 请求头参数

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

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| taskId | integer | 是 | 要修改的任务ID |
| taskName | string | 是 | 任务名称，用于展示和识别任务 |
| 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 | 否 | 是否复用会话，开启后任务执行时复用已有会话而非每次新建。开启时任务必须已关联会话 |
| bizKey | string | 否 | 业务键，用于标识任务关联的会话。传入后通过 bizKey 解析出对应的会话ID，优先级高于 sessionId |
| sessionId | integer | 否 | 来源会话ID，修改任务关联的会话 |
| runtimeVariables | object | 否 | 运行时变量，随任务保存并在每次触发时回填运行上下文。本字段采用增量语义：不传时保留已有值，传空对象时清除，传非空对象时整体覆写。变量不得包含密码、密钥等敏感信息 |
| 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图表代码块。任一运行特性字段传入时整组重建 |

## 响应

### 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处理 |