Skip to main content
Agent integrations

Manage schedules with natural language

Create, list, and archive schedules with natural language in a Forward Session.

Use natural language in a Forward Session to create, list, and archive schedules. In addition to calling the API, end users can describe a task and its timing in the web app or an IM Channel. The Agent creates the Schedule, which then runs automatically without requiring the original Session to remain online.

Prerequisites

Before managing schedules, enable the corresponding Schedule managed capabilities in the effective configuration of the current Template or Identity:
  • Create schedules: create_forward_schedule
  • List schedules: list_forward_schedules
  • Archive schedules: delete_forward_schedule
Templates do not enable these capabilities by default. A single Schedule switch in the template page’s Tools section configures all three capabilities together; the API still supports configuring each tool independently. managed_tool_config is a top-level Template field. Configure it when you create a Template or update an existing one: Example for creating a Template: 
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"
      ]
    }
  }'
Example for updating an existing 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 replaces the complete Forward managed capability baseline. Include any other managed capabilities that must remain enabled.

Override by Identity

If different Identities under the same Template need different Schedule capabilities, set individual switches by tool name in Identity Config: 
{
  "identity_config": {
    "managed_tool_config": {
      "create_forward_schedule": {
        "enabled": false
      }
    }
  }
}
Tools omitted from Identity Config inherit the Template baseline. Set an individual tool to null to remove its override, or set managed_tool_config: null to clear all overrides. See Upsert Identity Config for complete merge and conflict rules. Existing Identities can still use identity_config.tools.<name>.enabled=false to disable an inherited managed tool. New integrations should use identity_config.managed_tool_config.

Tool visibility and enablement

With a valid default Forward MCP configuration, interactive Sessions can see all three tools after a new request refreshes the configuration, even when Schedule is disabled. An existing custom tool with the same name is preserved. Tool visibility does not grant permission: calls still validate the effective Template and Identity switches and resource access permissions.
Tool result error codeMeaning and action
schedule_feature_disabledThe capability is disabled and the operation is not performed. The Agent should ask the user to enable Schedule in the template page’s Tools section and save. If already enabled, an administrator should check Identity overrides. Users without configuration permission should contact the assistant administrator.
schedule_configuration_changedThe current Session has not applied the newly enabled configuration. The user should send a new request and, if needed, reopen the Session to refresh it.
Both are business errors in tool results with retryable=false; the Agent must not automatically repeat the call. After enabling Schedule, the user should also send a new request to refresh the configuration. These are not new HTTP errors for the Schedule CRUD API. The switches do not affect direct Schedule API calls or pause existing Schedules. Schedule execution Sessions do not expose management tools. The legacy Custom Tool path retains its previous behavior and does not follow the rule that disabled tools remain visible.

Create a schedule

In the conversation, specify:
  • When to run, such as every day at 9:00 AM, every Monday at 10:00 AM, or in two hours.
  • What the task should do.
  • The required output.
  • The timezone. If omitted, the default is Asia/Shanghai.

Recurring tasks

Every weekday at 9:00 AM, summarize AI industry news from the past 24 hours.
Select the five most important stories and include source links.

Every Monday at 10:00 AM, summarize last week's project progress, risks, and action items.
Format the result as a Markdown table.

One-time tasks

Remind me at 4:00 PM today to prepare the project review materials.

In two hours, review this report and list every data inconsistency.

Fixed-interval tasks

From 9:00 AM to 6:00 PM on May 1, 2027, check flight prices every 30 minutes.
If the price drops below CNY 600, tell me the flight, time, and purchase link.
For monitoring tasks, specify the frequency, business date, year, start and end times, and trigger condition. The Agent asks follow-up questions if required information is missing. After creation, the Agent returns the result. You can also ask it to show the newly created Schedule and confirm its name, trigger rule, and timezone.

List schedules

You can list visible schedules and filter by name, task content, or status. For example: 
List all my current scheduled tasks.

Which of my scheduled tasks are related to flights?

Show my archived scheduled tasks.

Archive a schedule

Archive a Schedule by its ID or by its name or task content. You can still say "delete" in natural language, but the system does not physically delete data. For example: 
Delete Schedule sched_019f00112233445566778899aabbccdd.

Delete the daily morning AI news summary task.
If multiple schedules match, the Agent does not archive any of them. It returns the candidates so that you can select one by Schedule ID. In natural-language management, "delete" archives the Schedule: no new Schedule Runs are created, the Schedule remains retrievable by ID or with include_archived=true, and historical runs remain available. Existing pending or running runs are not canceled.

View execution results

  • A Schedule created in the web app returns results to the original Session. If you go offline, pending results are delivered the next time you open that Session.
  • A Schedule created in an IM Channel sends results to the corresponding Channel Session.
  • You can also use the API to list Schedule Runs or get a Schedule Run.
Each Schedule Run uses an independent execution Session and does not mix context with the Session that created the Schedule.

Limitations

  • The minimum granularity or interval for cron and interval triggers is one minute.
  • A relative delay for a once trigger is exempt from the minimum frequency, but the delay must be greater than zero.
  • While a Schedule is running, it cannot create, list, or archive other schedules. This prevents self-replication and recursive schedule management.

Create a schedule

List schedules

Pause a schedule

Archive a schedule

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference
Manage schedules with natural language - Qoder CN