Scheduling

Scheduling tools let agents create recurring jobs, set up periodic wake-ups, and work with time.

schedule_task

Creates, deletes, or lists cron jobs for recurring scheduled work.

Create a scheduled task

schedule_task(
  action: "create",
  cron_expression: "0 9 * * 1-5",
  title: "Daily standup summary",
  instruction: "Review yesterday's activity and list today's priorities"
)

List scheduled tasks

schedule_task(action: "list")

Delete a scheduled task

schedule_task(
  action: "delete",
  task_id: "abc123"
)

Parameters

Parameter	Type	Required	Description
action	string	yes	create, delete, or list
target_agent	string	no	Agent to schedule the task for (omit to schedule for yourself)
cron_expression	string	for create	5-field cron expression
title	string	for create	Short title for the cron job
instruction	string	for create	Instructions to execute each time the cron fires
run_at	string	no	ISO 8601 datetime for the first run
task_id	string	for delete	The cron job ID to cancel

What happens when a job fires

1. The scheduler picks up the task at the scheduled time
2. A chat session is created for the assigned agent
3. The agent processes the task using its tools
4. Results are stored and can be delivered to the originating chat
5. The next run time is calculated from the cron expression

set_heartbeat

Configures how often an agent wakes up for a heartbeat check. During each heartbeat, the agent reads its HEARTBEAT.md workspace file and acts on whatever instructions it finds there.

set_heartbeat(interval_minutes: 30)

To disable heartbeats:

set_heartbeat(interval_minutes: 0)

Parameters

Parameter	Type	Required	Description
interval_minutes	integer	yes	Minutes between heartbeat wake-ups (set to 0 to disable)

get_time

Gets the current UTC time or computes a future/past time by adding offsets.

get_time()

get_time(add_hours: 2, add_days: 1)

Parameters

All parameters are optional. If none are provided, the tool returns the current UTC time.

Parameter	Type	Description
add_minutes	integer	Minutes to add (negative to subtract)
add_hours	integer	Hours to add (negative to subtract)
add_days	integer	Days to add (negative to subtract)
add_weeks	integer	Weeks to add (negative to subtract)
add_months	integer	Months to add (negative to subtract)

Related

• Tasks Overview: task types and lifecycle
• Task Scheduling: cron syntax and configuration