Scheduler

Create and manage cron schedules with the Scheduler SDK and AgentOS.

Use Scheduler to create cron jobs, execute AgentOS endpoints, and track run history.

1pip install kern-ai[scheduler]

1from kern.db.sqlite import SqliteDb
2from kern.scheduler import ScheduleManager
3
4db = SqliteDb(id="scheduler-demo", db_file="tmp/scheduler.db")
5mgr = ScheduleManager(db)
6
7schedule = mgr.create(
8    name="weekday-report",
9    cron="0 9 * * 1-5",
10    endpoint="/agents/reporter/runs",
11    payload={"message": "Generate morning report"},
12    timezone="UTC",
13    max_retries=2,
14    retry_delay_seconds=30,
15)
16
17for s in mgr.list(enabled=True):
18    print(s.name, s.next_run_at)
19
20mgr.disable(schedule.id)

Run with AgentOS

Enable scheduler polling inside AgentOS:

1from kern.agent import Agent
2from kern.db.sqlite import SqliteDb
3from kern.models.openai import OpenAIChat
4from kern.os import AgentOS
5
6db = SqliteDb(id="os-db", db_file="tmp/os.db")
7
8greeter = Agent(
9    id="greeter",
10    model=OpenAIChat(id="gpt-4o-mini"),
11    instructions=["Reply with a short greeting."],
12    db=db,
13)
14
15app = AgentOS(
16    agents=[greeter],
17    db=db,
18    scheduler=True,
19    scheduler_poll_interval=15,
20).get_app()

Create a schedule through the Scheduler API:

1curl -X POST http://localhost:7777/schedules \
2  -H "Content-Type: application/json" \
3  -d '{
4    "name": "greeting-every-5m",
5    "cron_expr": "*/5 * * * *",
6    "endpoint": "/agents/greeter/runs",
7    "method": "POST",
8    "payload": {"message": "Say hello"},
9    "timezone": "UTC",
10    "max_retries": 2,
11    "retry_delay_seconds": 30,
12    "timeout_seconds": 3600
13  }'

Components

Component	Description
`ScheduleManager`	SDK API for create, list, update, enable, disable, delete, and run history
`SchedulePoller`	Claims due schedules on an interval and executes them concurrently
`ScheduleExecutor`	Calls schedule endpoints, handles retries, and writes run records
Scheduler API	REST endpoints for schedule lifecycle and manual trigger

Schedule Fields

Field	Default	Notes
`method`	`POST`	Allowed: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
`timezone`	`UTC`	IANA timezone string
`timeout_seconds`	`3600`	Request and polling timeout
`max_retries`	`0`	Retries after first failure
`retry_delay_seconds`	`60`	Delay between retry attempts

Behavior

Topic	Behavior
Cron format	Standard 5-field syntax: minute hour day-of-month month day-of-week
Endpoint format	Endpoint must be a path like `/agents/greeter/runs`
Validation	Invalid cron or timezone raises `ValueError` in SDK and `422` in API
Duplicate name	`ScheduleManager.create()` supports `if_exists="raise"`, `"skip"`, or `"update"`
Triggering	Use `POST /schedules/{id}/trigger` or `SchedulePoller.trigger()`
Run history	Each run stores status, attempt, timings, error, input, output, and requirements

Next Steps

Task	Guide
View schedules in AgentOS	os.kern.ndx.rocks/schedules
Deploy cron jobs for agents, workflows	AgentOS Scheduler
Manage schedule lifecycle	Schedule Management
Validate cron and timezone inputs	Schedule Validation
Inspect run records	Run History
Check API request and response schemas	Schedule API schemas