Scheduler

Deploy and manage scheduled execution for agents and workflows via AgentOS cron jobs.

Run cron-based jobs in AgentOS with built-in schedule management and run history.

1pip install "kern-ai[scheduler]"

1from kern.agent import Agent
2from kern.db.postgres import PostgresDb
3from kern.models.openai import OpenAIChat
4from kern.os import AgentOS
5
6db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")
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 Schedule

Create a schedule with 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  }'

Create a schedule using the AgentOS UI:

Managing Schedules

Manage execution schedules via the AgentOS Control Panel. Select any row entry in the Scheduler details panel to view configuration details and run history.

Edit schedule configuration, enable or disable schedule , trigger it manually or delete it.

Schedule detail panel with configuration

Key Concepts

Concept	Description
Cron	Standard 5-field cron syntax: minute hour day-of-month month day-of-week
Endpoint	Path only (for example `/agents/greeter/runs`), not a full URL
Timezone	IANA timezone string, defaults to `UTC`
Retries	`max_retries` and `retry_delay_seconds` control failure retries
Run history	Each execution stores status, timing, input, output, and errors

Scheduler API

Operation	Endpoint
Create schedule	`POST /schedules`
List schedules	`GET /schedules`
Get schedule	`GET /schedules/{schedule_id}`
Update schedule	`PATCH /schedules/{schedule_id}`
Delete schedule	`DELETE /schedules/{schedule_id}`
Enable or disable	`POST /schedules/{schedule_id}/enable` and `POST /schedules/{schedule_id}/disable`
Trigger now	`POST /schedules/{schedule_id}/trigger`
List runs	`GET /schedules/{schedule_id}/runs`
Get run	`GET /schedules/{schedule_id}/runs/{run_id}`

Next Steps

Task	Guide
Start with a minimal setup	Basic Schedule
Manage schedules with REST	Schedule Management
Check request and response schemas	Schedule API schemas
Explore all scheduler examples	Scheduler Examples