Skip to main content
集成 Agent

使用自然语言管理 Schedule

在 Forward Session 中使用自然语言创建、查询、修改和归档 Schedule。

除了调用 Schedule API，终端用户也可以在 Web 或 IM Channel 会话中描述任务内容和执行时间，由 Agent 创建 Schedule。创建后，任务会按约定时间自动运行，无需保持当前会话在线。 Schedule 执行时可使用 Template / Identity Config 中启用的文件。创建会话中的附件不会自动复制到 Schedule；如需配置专属文件，请通过 HTTP 创建或更新 Schedule的 resources 数组指定。当前自然语言创建和修改工具不提供 resources 参数；HTTP API 的文件配置和执行不依赖本页的托管工具开关。

使用前提

执行 Schedule 管理操作前，需要在当前 Template 或 Identity 的有效配置中启用对应的 Schedule 托管能力：
能力托管工具
创建 Schedulecreate_forward_schedule
查询 Schedulelist_forward_schedules
修改 Scheduleupdate_forward_schedule
归档 Scheduledelete_forward_schedule
Template 默认不启用这些能力。schedule 能力组合统一配置下列四项能力；也可按工具名独立配置。managed_tool_config 是 Template 请求体的顶层字段，可通过以下接口配置：
场景接口
创建 Template 时启用POST /api/v1/forward/templates
为已有 Template 启用或调整POST /api/v1/forward/templates/{template_id}
创建 Template 时，将 managed_tool_config 与 name、model、environment_id 等字段放在同一层： 
curl -s -X POST 'https://api.qoder.com/api/v1/forward/templates' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Schedule assistant",
    "model": "ultimate",
    "environment_id": "env_xxx",
    "managed_tool_config": {
      "enabled_tools": [
        "create_forward_schedule",
        "list_forward_schedules",
        "update_forward_schedule",
        "delete_forward_schedule"
      ]
    }
  }'
为已有 Template 启用或调整托管工具时，只需更新该字段： 
curl -s -X POST 'https://api.qoder.com/api/v1/forward/templates/tmpl_xxx' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "managed_tool_config": {
      "enabled_tools": [
        "create_forward_schedule",
        "list_forward_schedules",
        "update_forward_schedule",
        "delete_forward_schedule"
      ]
    }
  }'
更新时，enabled_tools 会整体替换当前 Forward 托管能力基线，请同时保留其他仍需启用的托管能力。详细参数见 创建 Template 和 更新 Template。 也可以将 enabled_tools 配置为 ["schedule"]，同时启用创建、查询、修改和归档。存量配置若只显式列出了创建、查询、归档三个工具，不会自动启用修改能力，需要补上 update_forward_schedule 或改用 schedule 组合。

按 Identity 覆盖

如果同一 Template 下的不同 Identity 需要不同的 Schedule 能力，可在 Identity Config 中按工具名设置单点开关： 
{
  "identity_config": {
    "managed_tool_config": {
      "create_forward_schedule": {
        "enabled": false
      }
    }
  }
}
Identity Config 中未出现的工具继承 Template 基线；单项传 null 删除覆盖，managed_tool_config: null 清空全部覆盖。详细合并和冲突规则见 创建或更新 Identity Config。 存量 Identity 仍兼容使用 identity_config.tools.<name>.enabled=false 禁用继承的托管工具；新接入应使用 identity_config.managed_tool_config。

工具可见性与开启指引

使用有效的默认 Forward MCP 配置时，交互会话在新请求完成配置刷新后，即使未启用 Schedule，模型也能看到这四个工具；已有同名自定义工具时保留原工具。能看到工具不代表有执行权限，调用时还会校验当前 Template 与 Identity 的有效开关以及资源访问权限。
工具结果错误码含义与处理
schedule_feature_disabled对应能力未开启，本次操作不执行。Agent 应提示用户在模板页面「工具」中开启 Schedule 并保存；已开启时请管理员检查 Identity 覆盖配置。无配置权限的用户应联系助手管理员。
schedule_configuration_changed当前会话尚未应用已开启的新配置。请由用户重新发起请求，必要时重新进入会话，以刷新配置。
两类错误均为工具结果中的业务错误，retryable=false；Agent 不应自动重复调用。开启后也应由用户重新发起请求以刷新配置。 这些工具错误不是 Schedule CRUD API 新增的 HTTP 错误。开关不影响直接调用 Schedule API，也不会暂停已有 Schedule。Schedule 执行会话不暴露管理工具；旧 Custom Tool 路径保持原有行为，不适用关闭后仍可见的规则。

创建 Schedule

在会话中说明以下信息：
  • 什么时候执行：例如“每天上午 9 点”、“每周一 10 点”或“2 小时后”。
  • 执行什么任务：说明要处理的对象和目标。
  • 输出要求：例如条目数、格式、筛选条件或是否需要附带来源。
  • 时区：涉及跨时区协作时，建议明确说出时区，例如“北京时间”或“美国太平洋时间”。未指定时区时，默认按 Asia/Shanghai 解释。

周期执行

每个工作日上午 9 点，汇总过去 24 小时的 AI 行业新闻，
选出最重要的 5 条，并附上来源链接。

每周一上午 10 点，整理上周的项目进展、风险和待办事项，
按 Markdown 表格输出。

单次执行

今天下午 4 点提醒我准备项目评审材料。

2 小时后检查这份报告，列出所有数据前后不一致的地方。

固定间隔检查

从 2027 年 5 月 1 日上午 9 点到下午 6 点，每 30 分钟检查一次机票价格，
低于 600 元时告诉我航班、时间和购买链接。
对于监控类任务，请同时说明检查频率、业务日期、年份、开始时间、结束时间和触发条件；缺少这些关键信息时，Agent 会先尝试向你确认。 Schedule 创建成功后，Agent 会在当前会话中返回创建结果。你可以继续询问 Agent 查看该 Schedule，确认任务名称、执行规则和时区是否符合预期。

创建失败与错误码

以下说明 create_forward_schedule 的创建失败，供接入方读取错误码、展示原因并决定下一步操作。它与HTTP 创建 Schedule、查询/修改/归档工具的错误及创建后的 Run 执行或消息送达失败分开处理。 需要接收创建失败回调时，订阅 Schedule 管理工具结果 Webhook。下表覆盖创建入口的现有稳定业务错误码；未提供细分码或结果不确定的情况也在后文单独列出。

先确认错误来自哪个入口

入口失败判断错误码位置
Forward Builtin MCP 工具的业务返回is_error=true；HTTP 200 也可能表示业务失败structured_content.error_code
旧 Custom Tool 的工具结果事件user.tool_result 或 user.custom_tool_result 的 is_error=true解析 content 中 type=text 项的 text 为 JSON，再读取 error.code
MCP 请求级错误HTTP 非 2xx，使用 HTTP 错误信封error.code，但部分错误可能不包含此字段；同时读取 error.type、HTTP 状态及 request_id（如有）
创建失败 Webhook（已订阅时）事件类型为 forward.schedule.create_faileddata.error.code；另有 category、message、requires_input
error.message、structured_content.message 和自然语言回复文案不保证稳定，不应通过匹配文案分支处理。单次调用遇到多个问题时返回首先命中的错误，不会一次返回所有校验错误。

时间规则与业务错误码

下表中的 MCP 错误码位于 structured_content.error_code，旧工具错误码位于解析后的 error.code。Webhook 单独说明的差异见后文。
错误码适用入口失败场景处理建议
trigger_policy_time_too_soonMCP、旧工具once 的目标时间小于或等于服务端当前时间；或传入的 stop_at 小于或等于当前时间核对真实当前时间、完整日期和时区，重新确认用户意图后使用未来时间；不要直接把过去的日期改为次日
trigger_policy_too_frequentMCP、旧工具interval 小于 1 分钟；或 cron 超过 5 字段（包括含秒字段的写法）重复任务改为至少 1 分钟，cron 使用 5 字段表达式；一次性提醒使用 once
invalid_trigger_policyMCP、旧工具表达式缺失或无法解析、所需时区无法解析、时间窗口不合法；delay 用在非 once 类型、与 expression 同传，或 duration 不合法等策略校验错误按下方策略规则修正。MCP 缺少策略对象或 type 等结构错误可能先返回 HTTP 400，见“参数与权限失败”
invalid_sinksMCP、旧工具从 IM 来源推导出的通知目标配置未通过校验，例如必要目标信息缺失或路由不合法检查渠道绑定和通知目标后重新发起请求。模型不应自行传入 sinks 覆盖来源
schedule_feature_disabledMCP当前 Template 或 Identity 没有启用此项 Schedule 能力在模板工具配置中开启并保存，或联系管理员检查 Identity 覆盖配置；修正后重新发起，不自动重试
schedule_configuration_changedMCP当前配置已启用，但会话尚未应用对应工具配置重新发起请求以刷新会话配置；仍不可用时重新进入会话，不自动重试
schedule_owner_unsupportedMCP当前归属及其凭据能力暂不支持创建 Schedule联系管理员检查该归属的 Schedule 支持情况；保持原请求重试无法解决
策略规则
类型或字段有效规则与边界
once.expression一次性绝对时间必须严格晚于服务端当前时间。once 不受 1 分钟最小间隔限制，未来 10 秒的提醒可以创建
once.delay相对一次性提醒使用 ISO 8601 duration，例如 PT10S、PT2M；仅工具入口支持，服务端换算为绝对时间；不能与 expression 同传
interval.expression使用至少 1 分钟的 ISO 8601 duration，例如 PT1M、PT15M、P1D。PT30S 返回频率过高；30s 格式不合法，返回策略格式错误
cron.expression使用 5 字段 cron，例如 0 9 * * *；6 字段或更多字段的表达式被按频率过高拒绝
timezone工具未指定时区时默认 Asia/Shanghai。绝对时间有 offset 时按其绝对时间解释；无 offset 的时间按指定时区解释
start_at / stop_at时间需可解析；stop_at 必须晚于当前时间，并在同时设置时晚于 start_at。once 不支持这两个窗口字段
自然语言创建使用 cron、once 或 interval。MCP 不接受 manual；HTTP 直接创建支持 manual 的约定不适用于该工具。

参数与权限失败

这些场景并不总以 MCP 的业务结果返回，不能只检查 structured_content.error_code。
场景旧工具结果MCP 同步返回处理建议
工具参数类型错误、字段不合法、缺少执行内容、名称或描述超限、包含不支持的控制字符通常为 invalid_requestHTTP 400，error.type=invalid_request_error，可能无 error.code修正参数后重新提交
缺少 trigger_policy、type 或类型不受支持invalid_trigger_policyHTTP 400，invalid_request_error，可能无细分码补齐策略；只传工具支持的类型
模型传入 user_id、identity_id、template_id、environment_id、sinks 或 metadata 等归属/来源字段invalid_requestHTTP 400，invalid_request_error，可能无细分码移除字段，由当前会话确定归属和来源
来源身份、会话上下文缺失或不匹配；当前身份/资源访问校验被拒绝invalid_identity；部分归属冲突仍使用 invalid_requestHTTP 403，error.type=permission_error，部分上下文异常可能走其他 HTTP 错误检查身份、资源授权和当前会话；必要时重新进入会话或联系管理员
在 Schedule 执行产生的会话中再次调用 Schedule 管理工具schedule_tool_forbidden_in_schedule_runHTTP 403，permission_error，可能无细分码回到普通用户会话创建，避免递归创建任务
工具不存在或会话未获准使用该工具可能没有该工具的结果事件HTTP 404 not_found_error 或 HTTP 403 permission_error，可能无细分码检查工具配置和会话，不将其当作频率或时间问题
执行内容使用非空 initial_events，或兼容的 instruction；事件类型须为 user.message，内容不得为空。MCP 对字段结构的前置校验与旧工具不同，同一非法输入在两个入口可能得到不同返回。
当前返回的兼容差异
场景同步返回与 Webhook 差异
来源 IM 渠道已停用当前 MCP 同步调用走 HTTP 500 api_error，可能无细分码；旧工具同步结果兜底为 invalid_request。已订阅的创建失败 Webhook 将其归一为 invalid_sinks
当前归属不支持 ScheduleMCP 业务返回 schedule_owner_unsupported；旧工具同步结果仍为 invalid_request。对应 Webhook 中 MCP 保留 schedule_owner_unsupported，旧工具保留 invalid_request 并标记 category=forbidden
部分归属冲突旧工具同步结果可能为 invalid_request，已订阅的失败 Webhook 可归一为 invalid_identity、category=forbidden；MCP 同步调用也可能走无细分码的 HTTP 错误
不要把 invalid_request 一律理解为用户参数错误；它也可能是旧入口尚未细分的拒绝或异常。Webhook 的归一错误码不能反推同步返回一定含有相同字段。

失败示例

MCP：重复任务间隔为 30 秒
当 trigger_policy={"type":"interval","expression":"PT30S"} 时，业务返回示例如下；HTTP 状态为 200，调用方仍应按 is_error=true 处理失败。 
{
  "is_error": true,
  "content": [
    {
      "type": "text",
      "text": "Trigger policy granularity must be at least 1 minute."
    }
  ],
  "structured_content": {
    "error_code": "trigger_policy_too_frequent",
    "message": "Trigger policy granularity must be at least 1 minute."
  }
}
旧工具：一次性目标时间已过
假设服务端当前时间已经晚于 2026-07-29T11:00:00+08:00。下例为工具结果事件 content[].text 解析后的 JSON，事件自身另有 is_error=true。 
{
  "tool_name": "create_forward_schedule",
  "success": false,
  "name": "11点开会提醒",
  "trigger_policy": {
    "type": "once",
    "expression": "2026-07-29T11:00:00+08:00",
    "timezone": "Asia/Shanghai"
  },
  "error": {
    "code": "trigger_policy_time_too_soon",
    "message": "schedule time too soon"
  }
}
失败时不保证存在 schedule_id；不要要求它固定为空字符串。旧工具被递归隔离拒绝时，结果可只有 error，不保证补齐 tool_name、success 或触发策略字段。
MCP：参数错误，没有细分错误码
例如请求缺少工具必需的策略对象，HTTP 400 的返回可以是： 
{
  "type": "error",
  "request_id": "req_example",
  "error": {
    "type": "invalid_request_error",
    "message": "invalid Forward MCP tool arguments"
  }
}
创建失败 Webhook
订阅 forward.schedule.create_failed 后，forward.schedule.create_failed 的 data 中相关字段如下： 
{
  "tool_call": {
    "id": "stcall_example",
    "name": "create_forward_schedule",
    "session_id": "sess_example",
    "invocation_path": "mcp"
  },
  "error": {
    "code": "trigger_policy_time_too_soon",
    "category": "invalid_request",
    "message": "Schedule trigger time is too soon.",
    "requires_input": false
  }
}
requires_input=false 不表示允许自动重试。来源无法验证时可能不产生失败 Webhook；通知持久化、投递或工具结果回写失败也不能据此认定 Schedule 没有创建。

系统异常、结果不确定与重试

情况调用方处理
收到明确的时间、策略、能力或参数拒绝按错误原因修正或补充用户意图，再重新提交；保持同样参数反复请求无法解决
HTTP 401 / 403按认证或权限问题处理；不要让模型猜测身份或覆盖归属字段
HTTP 5xx、超时、断线、没有收到结果保留可用的请求/会话标识，先查询 Schedule 确认是否已创建，再决定是否重新创建；这些情况可能发生在创建已提交之后
工具未调用，模型在追问或只返回自然语言此时可能没有创建错误码；不能仅凭回复文案判定创建已成功或失败
任务已创建，之后执行或推送失败按 Schedule Run 或通知投递结果处理，不归类为创建失败
MCP 的每次实际创建请求独立处理，不按相同会话、Turn 或参数提供自动去重；不要在结果未知时自动重放创建。旧工具相同可信调用标识的重放规则也不能当成所有入口通用的幂等保证。 schedule_not_found、schedule_archived、schedule_match_ambiguous 等属于已有 Schedule 的管理场景，不应作为常规创建校验错误展示。接入方自行封装的顶层 error_code、error_message、operation、rule_description 等字段，不是上述各入口统一承诺的返回结构。

查询 Schedule

可以查询当前用户可见的 Schedule，也可以通过名称、任务内容或状态缩小范围。 
列出我当前的所有定时任务。

我有哪些和机票有关的定时任务？

查看我已归档的定时任务。

修改 Schedule

可以修改任务名称、描述、执行内容，以及执行时间、频率和监控窗口。例如： 
把每天早上的 AI 新闻汇总改到北京时间上午 10 点，其他设置保持不变。

把机票价格检查改为每 15 分钟执行一次，保留原来的开始和结束时间。

修改 Schedule sched_019f00112233445566778899aabbccdd：
以后汇总 10 条新闻，并为每条附上来源链接，执行时间不变。
可使用 Schedule ID 精确指定任务，也可通过名称、描述或执行内容中的关键词查询。修改范围限定为当前会话 Owner 和 Identity 下的任务；查询匹配多项时不会修改任何任务，Agent 会返回候选项并请你指定 Schedule ID。没有匹配项时也不会创建新任务。

修改工具参数

Agent 使用 update_forward_schedule 完成修改。以下为工具参数，不是 HTTP 更新 Schedule 的请求体；调用方无需自行构造内部 MCP 调用。
参数类型是否必填说明
schedule_idstring与 query 二选一非空 Schedule ID，精确指定任务。
querystring与 schedule_id 二选一非空关键词，匹配名称、描述或初始事件内容；仅唯一匹配时修改。
namestring否非空名称，最多 256 个字符。
descriptionstring否描述，最多 2048 个字符；空字符串清空描述。
instructionstring否非空执行指令；只适用于原任务恰好包含一条 user.message 初始事件。与 initial_events 互斥。
initial_eventsarray否完整替换初始事件列表，1～50 条；每条仅包含 type: user.message 和非空 content。多条事件保留在数组中的顺序。与 instruction 互斥。
trigger_policyobject否按子字段局部修改触发策略，至少包含一个字段；未传字段沿用当前配置。
必须至少提供 name、description、instruction、initial_events、trigger_policy 中的一项。所有参数拒绝 null 和未知字段。工具不接受 identity_id、template_id、environment_id、resources、sinks、execution、metadata 或状态字段；需要修改这些配置时使用相应的管理 API。 trigger_policy 支持以下子字段：
字段类型说明
typestringcron、once 或 interval；工具不接受 manual。切换类型时必须同时提供新的 expression，或为 once 提供 delay。
expressionstring5 字段 cron、once 的绝对时间或 interval 的 ISO 8601 duration；与 delay 互斥。
delaystring仅用于 once 的正数相对延迟，例如 PT10M；替换原绝对触发时间。
timezonestringIANA timezone；省略时沿用原时区。
start_atstring开始时间；接受按 timezone 解释的本地秒级时间或带 offset 的 RFC3339；空字符串清除该边界。
stop_atstring结束时间；格式同 start_at；空字符串清除该边界。
修改 cron 或 interval 时，未传的监控窗口边界保持不变。改为 once 时清除继承的监控窗口，不能为 once 设置非空 start_at / stop_at。修改 interval 规则后从本次更新时点重新计算后续触发时间；规则未变时保留现有下一次触发时间。 例如，仅把每天执行的 cron 任务的时间改为上午 10 点，保留原时区和监控窗口，工具参数为： 
{
  "schedule_id": "sched_019f00112233445566778899aabbccdd",
  "trigger_policy": {
    "expression": "0 10 * * *"
  }
}
清除结束时间而保留其他设置： 
{
  "schedule_id": "sched_019f00112233445566778899aabbccdd",
  "trigger_policy": {
    "stop_at": ""
  }
}
通过关键词唯一定位任务并替换执行内容（原任务只有一条初始消息）： 
{
  "query": "AI 新闻汇总",
  "instruction": "汇总过去 24 小时的 10 条 AI 新闻，为每条附上来源链接。"
}
将任务改为 10 分钟后执行一次： 
{
  "schedule_id": "sched_019f00112233445566778899aabbccdd",
  "trigger_policy": {
    "type": "once",
    "delay": "PT10M"
  }
}

修改结果

工具结果 status含义
updated已修改，返回任务 ID、名称、schedule_status、initial_events_version、触发策略和可用时的 next_trigger_at。
unchanged规范化后的请求与当前设置一致；不更新版本、updated_at 或下一次触发时间。
not_foundquery 没有匹配项；不修改、不创建任务。
multiple_matchesquery 匹配多个任务；返回候选项，请指定一个 schedule_id 后再修改。
status 是本次工具操作结果，schedule_status 才是任务的 active / paused 状态。修改暂停任务不会自动恢复执行；需要时通过恢复 Schedule 单独恢复。精确 ID 不存在或已归档时返回工具业务错误。 仅执行内容实际变化时递增 initial_events_version，名称和触发规则修改不递增该版本。已有 Run 继续遵循输入版本与绑定规则，不会因修改而重写历史记录。next_trigger_at 为工具结果字段，不是 HTTP Schedule 对象新增字段。

归档 Schedule

可以通过 Schedule ID 精确归档，也可以通过任务名称或内容描述。自然语言中仍可使用“删除”，但系统不会物理删除数据。 
删除 Schedule sched_019f00112233445566778899aabbccdd。

删除每天早上的 AI 新闻汇总任务。
如果描述匹配多个 Schedule，系统不会执行归档，而会返回候选项供你指定具体的 Schedule ID。自然语言“删除”实际会归档 Schedule：归档后不再产生新的 Schedule Run；Schedule 记录可按 ID 查询，也可通过 include_archived=true 列出，历史 Schedule Run 仍会保留。已有的 pending 或 running Run 不会被取消。

查看执行结果

  • 在普通 Web 会话中创建的 Schedule，执行结果会回到创建任务的原会话。即使执行时会话不在线，下次打开该会话时仍可接收尚未展示的结果。
  • 在 IM Channel 会话中创建的 Schedule，执行结果会投递到对应的 Channel 会话。
  • 也可以通过 列出 Schedule Runs 和 获取 Schedule Run API 查看执行记录、状态与错误信息。
Schedule 会在独立的执行 Session 中运行，不会把执行过程混入创建任务的会话上下文。

接收管理工具结果通知

需要在业务系统中接收创建、查询、修改或归档工具的结果时，可订阅 Schedule 管理工具结果 Webhook。这些通知与 Schedule Run 的执行成功、失败通知相互独立；创建和归档成功复用现有的 forward.schedule.created、forward.schedule.archived 事件。 修改工具实际保存了变更、结果为 updated 时发送 forward.schedule.updated；配置与当前值相同、结果为 unchanged 时不发送通知，仍可在当前会话中查看结果。确定性业务失败、无匹配或多项匹配通过 forward.schedule.update_failed 通知。基础设施故障或提交结果不确定时，不保证产生业务失败通知，不能以未收到回调判断修改失败。 例如，订阅修改的实际变更和确定性失败通知： 
{
  "events": [
    "forward.schedule.updated",
    "forward.schedule.update_failed"
  ]
}
已有精确订阅需显式添加新事件；订阅 * 会自动接收。修改成功事件提供 schedule_id、updated_at、schedule_version 等摘要，不包含任务指令或完整初始事件。该通知仅覆盖管理工具调用，直接调用 HTTP 更新 Schedule不产生该成功事件。

使用限制

  • cron 和 interval 类型的触发粒度或执行间隔不得小于 1 分钟。once 类型的相对延迟任务不受该频率下限限制，但延迟时长必须大于 0。
  • Schedule 运行期间不能再创建、查询、修改或归档其他 Schedule，以避免定时任务自我复制或循环管理。

相关

创建 Schedule

列出 Schedules

更新 Schedule API

暂停 Schedule

归档 Schedule