Skip to main content
集成 Agent

使用自然语言管理 Schedule

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

除了调用 Schedule API，终端用户也可以在 Web 或 IM Channel 会话中描述任务内容和执行时间，由 Agent 创建 Schedule。创建后，任务会按约定时间自动运行，无需保持当前会话在线。

使用前提

执行 Schedule 管理操作前，需要在当前 Template 或 Identity 的有效配置中启用对应的 Schedule 托管能力：
能力托管工具
创建 Schedulecreate_forward_schedule
查询 Schedulelist_forward_schedules
归档 Scheduledelete_forward_schedule
Template 默认不启用这些能力。模板页面「工具」中的一个 Schedule 开关统一配置下列三项能力；API 仍可按工具名独立配置。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.cn/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",
        "delete_forward_schedule"
      ]
    }
  }'
为已有 Template 启用或调整托管工具时，只需更新该字段： 
curl -s -X POST 'https://api.qoder.com.cn/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",
        "delete_forward_schedule"
      ]
    }
  }'
更新时，enabled_tools 会整体替换当前 Forward 托管能力基线，请同时保留其他仍需启用的托管能力。详细参数见 创建 Template 和 更新 Template。

按 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，确认任务名称、执行规则和时区是否符合预期。

查询 Schedule

可以查询当前用户可见的 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 事件。

使用限制

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

相关

创建 Schedule

列出 Schedules

暂停 Schedule

归档 Schedule