Cron schedules

Put fixed schedules in cron/. Harnest discovers them automatically in both ADK and LangGraph projects.

Folder layout

my-agent/
├── tasks/build_report.py
├── cron/daily_report.py
└── lifecycle/storage.py

Use one schedule per Python file, with a matching export: daily_report.py defines daily_report. Nested folders are unsupported; names beginning with _ or . are ignored. No import in agent.py is needed.

Declare an application-owned schedule

This example queues a report at 09:00 UTC, Monday–Friday:

from harnest.task import task


@task(queue="reports", max_retries=3)
async def build_report(account_id: str) -> dict:
    """Build one account report on the reports queue."""

    return {"account_id": account_id, "status": "ready"}

from harnest import cron
from tasks.build_report import build_report


daily_report = cron.Cron(
    "0 9 * * 1-5",
    task=build_report,
    arguments={"account_id": "acct_123"},
)

Target a root @task and pass JSON-safe arguments matching its signature.

Start the scheduler

harnest serve .

Keep this process running. harnest run does not activate schedules.

Schedule contract

Rule	Supported value
Fields	Minute, hour, day of month, month, day of week
Timezone	`UTC` only
Syntax	`*`, ASCII numbers, comma lists, ascending ranges, `/step`
Replicas	Shared task/cron provider atomically commits each occurrence

Tasks may retry; make their side effects idempotent. See task execution. Scheduled tasks that invoke an agent need an explicit service principal to access governed tools and MCP operations. For schedules created by tools at runtime, see Dynamic schedules.

Overview

Get started

Guides

Cron schedules

Folder layout

Declare an application-owned schedule

Start the scheduler

Schedule contract

​Folder layout

​Declare an application-owned schedule

​Start the scheduler

​Schedule contract

Folder layout

Declare an application-owned schedule

Start the scheduler

Schedule contract