Skip to main content

Scheduled tasks

A scheduled task (Scheduled Task, the Deployment resource in the API and CLI) binds an agent to a trigger configuration — scheduled by cron expression or triggered manually — and is suited to unattended tasks like daily rollups and periodic inspections.

A scheduled task (the Deployment resource in the API and CLI) binds an agent to a trigger configuration: scheduled triggers execute automatically on a cron expression, and manual triggers execute when you click Run. Each trigger creates a session, sends the initial messages fixed at creation to the agent, and records the execution and its results as a run. The 部署 (Deployments) page in the console sidebar is the management entry for scheduled tasks. Scheduled tasks suit unattended periodic tasks: daily data rollups, periodic inspections, hourly syncs. For multi-turn interactive tasks, use sessions instead.

Create in the console

Open the Deployments page in the console, click Create, and configure:
  • Name: The task name.
  • Description (optional): Its purpose.
  • Agent: The agent to run.
  • Environment (optional): The environment to run in.
  • Environment variables (optional): Injected into the session runtime.
  • Credentials (optional): Bind a vault for MCP services and skills to reference.
  • Initial messages: Sent to the agent as the initial user messages on each trigger, 1 to 50 items.
  • Files (optional): Mounted into the session the task runs.
  • Metadata (optional): Custom key-value pairs.
  • Trigger: Manual or scheduled.
When configuring a scheduled trigger, the console previews the next 5 run times:
FieldDescription
FrequencyHourly, daily, weekdays, weekly, monthly, or custom cron
Cron expressionStandard five fields (minute hour day month weekday); * any, */5 every 5 units, 1-5 a range
TimezoneThe timezone the expression runs in, for example (GMT+08:00) Asia/Shanghai

Triggers and run records

Manual tasks are triggered by clicking Run from the list or detail page; scheduled tasks trigger automatically on the expression. Each trigger produces a run record, viewed on the Run History tab of the task detail page:
  • Run ID: The identifier of a single execution, prefixed drun_.
  • Trigger source: manual or scheduled.
  • Status: running, succeeded, or failed.
  • Session: The session ID created for this run; query its event history and output as with any session.
  • Start / end time.

Pause and archive

  • Pause: Stops scheduled triggering while keeping the configuration; after resuming, execution continues on the original expression.
  • Archive: An archived task can no longer be triggered; the operation is idempotent.

Manage via API and CLI

Create a deployment that runs at 9 AM (Asia/Shanghai) on weekdays. For the full parameters and response fields, see Create Deployment API: 
curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/deployments" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily order rollup",
    "agent": {
      "id": "agent_xxx",
      "version": 12
    },
    "environment_id": "env_xxx",
    "schedule": {
      "type": "cron",
      "expression": "0 9 * * 1-5",
      "timezone": "Asia/Shanghai"
    },
    "initial_events": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Roll up yesterday's order data"
          }
        ]
      }
    ]
  }'
agent.version pins the agent version; omit it to use the latest. When updating a task, setting schedule to null clears the schedule and reverts it to manual. Common operations:
OperationAPICLI
Trigger a runTrigger Deployment Runbl managed-agent deployment run
Pause / resumePause, Resumebl managed-agent deployment pause / unpause
View run recordsList Deployment Runsbl managed-agent deployment runs list

Next steps

Deployment API

The full API for scheduled tasks and run records

Webhook Event Subscriptions

Subscribe to status-change events for scheduled tasks and runs