Skip to content

Scheduled Operations#

Managed agents can run tasks on a schedule — recurring via cron expressions and intervals, or one-shot via relative and absolute timers.

Schedule formats#

Five formats are supported. Use whichever is most natural in conversation:

Format Example Behavior
One-shot relative in 20 minutes, in 2 hours Runs once, then auto-deleted
One-shot absolute at 3pm, at 14:30 Runs once at the next occurrence, then auto-deleted
Interval every 2 hours, every 30 minutes Recurring, converted to a cron expression internally
Daily every day at 9am Recurring daily at the specified time
Cron expression 0 9 * * 1 Recurring, standard five-field cron syntax

One-shot tasks are automatically deleted from the schedule after they execute. Recurring tasks persist until you remove them.

Task lifecycle#

  1. Create — you ask the agent to schedule a task through conversation. The agent calls schedule_task with a name, schedule, and instruction.
  2. Persist — the task is saved and scheduled.
  3. Execute — when the timer fires, the agent is invoked with the task instruction. Results are delivered to your conversation thread, prefixed with Scheduled Task: [name].
  4. Deliver — the agent uses its tools to complete the instruction, delivering results step by step.
  5. Cleanup — for one-shot tasks, the schedule entry is automatically deleted after execution. Recurring tasks remain active.

Creating a Scheduled Task#

Tell your agent through conversation:

Run a compliance check every Monday at 9am.

In 2 hours, check the deployment status and report back.

Every day at 6pm, summarize what changed in the production namespace today.

At 3pm, remind me to review the PR for the auth service.

Run a cost analysis every Friday at 5pm using cron: 0 17 * * 5

The agent confirms the schedule and begins executing on the next occurrence.

Managing tasks#

Ask the agent to list or remove tasks:

What tasks do you have scheduled?

Delete the Monday compliance check.

The agent uses three tools for schedule management:

Tool Purpose
schedule_task Create a new scheduled task
list_scheduled_tasks View all scheduled tasks
delete_scheduled_task Remove a task by ID

Tool availability during execution#

Scheduled tasks execute in a restricted mode. The agent has access to:

  • Memory tools — search, write, and delete memory entries
  • Infrastructure tools — shell, kubectl, AWS, GitHub, and other connected systems

The agent does not have access to during scheduled execution:

  • Workspace file updates (Soul, User Profile, Vision, Heartbeat)
  • Settings changes (autonomy, verbosity, heartbeat interval)
  • Schedule management tools (no creating or deleting tasks from within a task)
  • Subagent delegation

This restriction ensures scheduled tasks focus on their defined purpose without modifying agent configuration as a side effect.

Budget awareness#

Scheduled tasks respect spending controls. If the organization's spending limit is exceeded when a task fires:

  • The task is skipped gracefully
  • You receive a notification explaining that the task could not run due to budget constraints
  • The skip is not counted as a failure — the task remains scheduled for its next occurrence

Timezone handling#

Scheduled tasks use the agent's configured timezone (default: UTC). Change it through conversation:

Set your timezone to America/New_York.

The timezone is also configurable directly on the agent's settings. All schedule times are interpreted in the agent's timezone.

Scheduled tasks vs. heartbeat#

Both run periodically, but they serve different purposes:

Heartbeat Scheduled tasks
Purpose Always-on monitoring Specific jobs at specific times
Instructions Defined in the Heartbeat workspace file Defined per task
Alert suppression Yes (duplicate and semantic) No (always delivers results)
Schedule Single interval (e.g., every 2 hours) Multiple independent schedules
One-shot support No Yes

Use heartbeat for continuous monitoring. Use scheduled tasks for discrete jobs with specific timing.