Run an agent on a schedule

This guide takes an agent from "answers when asked" to "runs every morning on its own": set the right trigger, declare the schedule, deploy, and confirm the runs fire. The Schedules reference covers the schedule model in depth; this page is the walkthrough.

Before you start

• Schedules apply only to scheduled / autonomous agents. This is the one constraint that trips people up, so it comes first: schedules declared on a human-triggered agent are dropped at create — not an error — and cleared if a skill edit switches the agent to human-triggered. If your agent's trigger is wrong, everything else in this guide silently does nothing.
• No acting on a person's behalf. An autonomous agent has no requesting person, so tools that act as an individual user (per-user connected accounts) cannot resolve on a scheduled run. Schedule work the agent can do as itself or through a workspace service connection.
• An agent. If you don't have one yet, walk through Create an agent with the skill builder first — this guide picks up at its configure screen.

Step 1 — set the trigger to scheduled / autonomous

On the configure screen — during creation, or when applying a skill edit to an existing agent — find the Trigger section and select Scheduled / autonomous instead of Human-triggered.

This does two things: it tells the platform the agent runs without a requesting person (which changes how its tools are allowed to act — see Creating an agent), and it makes the agent eligible to carry schedules at all.

Step 2 — declare the schedule

The console sets the trigger, but it does not yet expose a schedule editor — the schedules themselves are declared through the platform API, as the schedules list on the agent's create request (or on a skill-edit apply for an existing agent):

{
  "schedules": [
    {
      "id": "weekday-status-check",
      "cron": "*/5 9-17 * * 1-5",
      "task": "Check the status page and summarize any incidents.",
      "channel": "slack",
      "channel_target": "C0123456789"
    }
  ]
}

Field by field:

• id — a name for the schedule, unique within the agent. Required.
• cron — when to run. Either a standard 5-field cron expression (minute, hour, day-of-month, month, day-of-week — with *, numbers, ranges, steps, and comma lists) or one of the shortcuts @hourly, @daily (or @midnight), @weekly, @monthly, @yearly (or @annually). @every <duration> intervals are rejected — use a 5-field expression instead. The expression is validated when you submit, so a bad one fails the request with a specific reason rather than silently never firing.
• task — the natural-language instruction the agent receives on each run, exactly as if a person had typed it in chat. Required — this is what the run does.
• channel / channel_target (optional) — deliver the run's result to a channel the agent is connected to: channel names the adapter (for example slack), channel_target the destination ID.

Two things that are not this mechanism, so you don't chase them:

• Telling the skill builder "run it on a schedule" shapes the drafted skill — what the agent does and how — but does not attach a platform schedule. The schedule is agent configuration, declared as above.
• Asking the deployed agent in chat ("check this every morning and post it here") uses the agent's own built-in schedule tools — real, and useful for ad-hoc recurring work, but those schedules live in the agent runtime rather than in its configuration. See Memory and scheduling. Declared schedules are the platform-owned, survives-anything path.

Step 3 — deploy the agent

Schedules take effect at deploy: the platform materializes the agent's declared schedules when it is deployed, and reconciles them on every redeploy — schedules you add, change, or remove take effect with the next deploy, and removed ones are pruned.

Deployment is deliberately resilient here: if schedule setup can't complete during a deploy, the agent itself still deploys — the deploy logs a warning and the next redeploy retries the schedules. A schedule problem never takes down an otherwise-healthy rollout.

From then on, the platform owns the timer. On each tick it invokes the agent with the schedule's task, authenticated like any other platform call — the agent needs no scheduling code, no extra permissions, and no extra network access. And a scheduled run is not a bypass: the same egress allowlist, guardrails, approvals, and quota checks apply as on any human-triggered run.

Step 4 — verify it fires

Don't declare and walk away — confirm the first tick.

• The agent's Activity tab. A scheduled run appears like any other execution, with its full event timeline. If the cron says every five minutes, you should see a run within five minutes of the deploy.
• Governance → Events. Scheduled activity emits its own audit events: schedule_fire when a schedule triggers a run, schedule_complete when the run finishes (fields.success distinguishes success from failure), and schedule_skip when a tick was skipped — which happens by design when the previous run is still in progress, since runs never stack. schedule_modify records schedule changes. Filter the Events screen to the agent and look for the schedule_fire / schedule_complete pair.

Scheduling a CI-built agent

CI-deployed agents work differently: their repository owns scheduling. Schedules are part of the runtime configuration baked into the image at build time, so the platform does not manage schedules for them — change the spec in the repo and push a new image through the pipeline. See Deploy a CI-built agent.

Troubleshooting

• The schedule never fires, and nothing errored. Almost always the trigger: schedules on a human-triggered agent are dropped at create and cleared on a skill edit that switches the trigger, silently in both cases. Set the trigger to Scheduled / autonomous (Step 1), declare the schedule again (Step 2), and redeploy.
• Diagnose flags it for you. The Diagnose panel includes a schedule pre-check: an autonomous agent whose recent events show schedule changes but no schedule_fire is flagged, so a silently dead schedule doesn't go unnoticed.
• The create or edit request was rejected. Schedule validation fails fast with the exact problem — a duplicate or missing id, a missing task, a cron field out of bounds, or an @every interval (not supported — use a 5-field expression or a shortcut).
• The deploy warned about schedules. The agent is up; only its schedules didn't fully apply. Redeploy to retry — reconciliation runs on every deploy.