Scheduled tasks

Concept

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. In the console, the Deployments page in the sidebar is the management entry for scheduled tasks; the resource name in the API and CLI remains Deployment. Scheduled tasks suit unattended periodic work: daily data rollups, periodic inspections, hourly syncs. For multi-turn interactive tasks, see Delegate Work to an Agent.

Create a scheduled task

On the Deployments page, click Create and configure:

Field	Description
Name	The task name, up to 256 characters
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 the schedule, the console previews the next 5 run times:

Field	Description
Frequency	Hourly, daily, weekdays, weekly, monthly, or custom cron
Cron expression	Standard five fields (minute hour day month weekday); `` any, `/5` every 5 units, `1-5` a range
Timezone	The timezone the expression runs in, for example `(GMT+08:00) Asia/Shanghai`

Creating through the API returns an ID prefixed depl_. agent.version locks the agent version; omit it to use the latest. For full parameters and response fields, see Create Deployment API.

curl -X POST "$AGENTSTUDIO_URL/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"
          }
        ]
      }
    ]
  }'

When updating a task, set schedule to null to clear the schedule and fall back to manual. See Update Deployment API.

Runs and run records

Manual tasks are triggered by clicking Run from the console list or detail page, or by calling the Trigger Deployment Run API; scheduled tasks trigger automatically on the expression. Each trigger produces a run record, viewed on the Run History tab of the task detail page, with fields:

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.

For full fields and pagination parameters, see List Deployment Runs API and Get Deployment Run API.

Pause and archive

Pause: Stops scheduled triggering while keeping the configuration; after resuming, execution continues on the original expression. See Pause and Unpause.
Archive: An archived task cannot be triggered; the operation is idempotent. See Archive Deployment API.

Use the CLI

Operation	Command
Create a scheduled task (with a schedule)	`bl managed-agent deployment create`
Trigger a run now	`bl managed-agent deployment run`
Pause / resume	`bl managed-agent deployment pause` / `unpause`
View tasks	`bl managed-agent deployment list` / `get` / `search`
View run records	`bl managed-agent deployment runs list` / `runs get`

For more commands, see the Managed Agent command reference.

Next steps

Delegate Work to an Agent: Use sessions for multi-turn interactive tasks.
Deployment API: The full interface for scheduled tasks and run records.
Webhook notifications: Subscribe to status-change events for scheduled tasks and runs.

​Concept

​Create a scheduled task

​Runs and run records

​Pause and archive

​Use the CLI