Skip to main content
The cron tool enables agents to schedule one-time reminders, recurring tasks, and time-based automation using intervals, cron expressions, or specific timestamps.

​
Tool Name

cron

​
Description

Schedule reminders and recurring tasks. Supports three actions: add, list, and remove.

​
Parameters

​
action
string
required
Action to perform: "add", "list", or "remove"
​
message
string
Reminder message to deliver (required for add action)
​
every_seconds
integer
Interval in seconds for recurring tasks (e.g., 300 for every 5 minutes)
​
cron_expr
string
Cron expression for scheduled tasks (e.g., "0 9 * * *" for daily at 9 AM)
​
tz
string
IANA timezone for cron expressions (e.g., "America/Vancouver", "Europe/London"). Only used with cron_expr.
​
at
string
ISO datetime for one-time execution (e.g., "2026-02-12T10:30:00")
​
job_id
string
Job ID to remove (required for remove action)

​
Return Value

Returns:
  • add: Success message with job name and ID
  • list: Formatted list of scheduled jobs
  • remove: Confirmation or “not found” message
  • error: Error message for invalid parameters or context issues

​
Configuration

CronTool(cron_service=cron_service_instance)

​
Context Management

# Set delivery context for scheduled messages
cron_tool.set_context(
    channel="telegram",
    chat_id="123456"
)
Scheduled messages are delivered to the configured channel/chat.

​
Actions

​
add - Schedule New Job

Create a new scheduled task. Must specify one of: every_seconds, cron_expr, or at.

​
Recurring with Interval

{
  "action": "add",
  "message": "Take a break and stretch!",
  "every_seconds": 3600
}
Returns: 
Created job 'Take a break and stretch!' (id: job_abc123)
Runs every hour (3600 seconds).

​
Recurring with Cron Expression

{
  "action": "add",
  "message": "Daily standup reminder",
  "cron_expr": "0 9 * * 1-5",
  "tz": "America/New_York"
}
Returns: 
Created job 'Daily standup reminder' (id: job_def456)
Runs weekdays (Mon-Fri) at 9:00 AM EST.

​
One-Time at Specific Time

{
  "action": "add",
  "message": "Meeting with design team",
  "at": "2026-03-15T14:30:00"
}
Returns: 
Created job 'Meeting with design team' (id: job_ghi789)
Runs once on March 15, 2026 at 2:30 PM, then automatically deletes.

​
list - Show Scheduled Jobs

{
  "action": "list"
}
Returns: 
Scheduled jobs:
- Daily standup reminder (id: job_def456, cron)
- Take a break and stretch! (id: job_abc123, every)
- Server backup (id: job_xyz999, cron)

​
remove - Delete Job

{
  "action": "remove",
  "job_id": "job_abc123"
}
Returns: 
Removed job job_abc123

​
Schedule Types

​
Interval (every)

Runs repeatedly at fixed intervals: 
{
  "action": "add",
  "message": "Check server status",
  "every_seconds": 300
}
  • Simple and predictable
  • Measured from previous execution completion
  • Good for: monitoring, polling, regular checks

​
Cron Expression (cron)

Runs at specific times matching a cron pattern: 
{
  "action": "add",
  "message": "Weekly report",
  "cron_expr": "0 17 * * 5",
  "tz": "Europe/London"
}
Cron format: minute hour day month day_of_week Examples:
  • "0 9 * * *" - Every day at 9:00 AM
  • "*/15 * * * *" - Every 15 minutes
  • "0 0 1 * *" - First day of each month at midnight
  • "0 9 * * 1" - Every Monday at 9:00 AM
  • "30 14 * * 1-5" - Weekdays at 2:30 PM
Good for: daily tasks, business hour alerts, scheduled reports

​
One-Time (at)

Runs once at a specific datetime: 
{
  "action": "add",
  "message": "Project deadline",
  "at": "2026-06-01T17:00:00"
}
  • ISO 8601 format required
  • Automatically deleted after execution
  • Good for: reminders, deadlines, one-off events

​
Timezones

The tz parameter requires IANA timezone names: Common Timezones:
  • America/New_York - US Eastern
  • America/Los_Angeles - US Pacific
  • America/Chicago - US Central
  • America/Denver - US Mountain
  • America/Vancouver - Pacific
  • America/Toronto - Eastern Canada
  • Europe/London - UK
  • Europe/Paris - Central Europe
  • Asia/Tokyo - Japan
  • Asia/Shanghai - China
  • Australia/Sydney - Australia
Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones Without timezone: 
{
  "cron_expr": "0 9 * * *"
}
Uses server’s local time (not recommended for production). With timezone: 
{
  "cron_expr": "0 9 * * *",
  "tz": "America/New_York"
}
Runs at 9 AM Eastern Time, handling DST automatically.

​
Error Cases

​
Missing Message

{
  "action": "add",
  "every_seconds": 60
}
Returns: 
Error: message is required for add

​
No Schedule Specified

{
  "action": "add",
  "message": "Reminder"
}
Returns: 
Error: either every_seconds, cron_expr, or at is required

​
Invalid Timezone

{
  "action": "add",
  "message": "Test",
  "cron_expr": "0 9 * * *",
  "tz": "Invalid/Timezone"
}
Returns: 
Error: unknown timezone 'Invalid/Timezone'

​
Invalid Date Format

{
  "action": "add",
  "message": "Meeting",
  "at": "2026-13-45 25:99:99"
}
Returns: 
Error: invalid ISO datetime format '2026-13-45 25:99:99'. Expected format: YYYY-MM-DDTHH:MM:SS

​
Recursive Cron (Security)

{
  "action": "add",
  "message": "Spawn more jobs",
  "every_seconds": 10
}
Returns (if called from within a cron job execution): 
Error: cannot schedule new jobs from within a cron job execution
This prevents infinite recursion and resource exhaustion.

​
Job Not Found

{
  "action": "remove",
  "job_id": "nonexistent_job"
}
Returns: 
Job nonexistent_job not found

​
Use Cases

​
Daily Reports

{
  "action": "add",
  "message": "Generate daily sales report",
  "cron_expr": "0 18 * * *",
  "tz": "America/New_York"
}

​
System Monitoring

{
  "action": "add",
  "message": "Check disk space and CPU usage",
  "every_seconds": 600
}

​
Meeting Reminders

{
  "action": "add",
  "message": "Team sync in 5 minutes",
  "at": "2026-03-06T14:55:00"
}

​
Business Hours Alerts

{
  "action": "add",
  "message": "Check support queue",
  "cron_expr": "0 9-17 * * 1-5",
  "tz": "America/Los_Angeles"
}
Runs every hour from 9 AM to 5 PM, Monday-Friday (Pacific Time).

​
Job Lifecycle

  1. Create: Job added with schedule and message
  2. Schedule: CronService calculates next run time
  3. Execute: At scheduled time, agent is triggered with message
  4. Deliver: Message sent to configured channel/chat
  5. Repeat (or Delete): Recurring jobs reschedule; one-time jobs delete

​
Persistence

Cron jobs are persisted across restarts (implementation-dependent). Check your CronService configuration for persistence details.

​
Implementation

See nanobot/agent/tools/cron.py:11 for the CronTool implementation. See nanobot/cron/service.py for the CronService implementation.

Build docs developers (and LLMs) love

Get started for freeTalk to us