Deploying an Agent to Run on a Schedule

A scheduled agent is production software triggered by time. It needs one durable run identity per schedule window, overlap prevention, time-zone clarity, catch-up policy, secrets, health checks, alerts, and a manual rerun that cannot duplicate effects.

After this lesson, you can deploy a scheduled workflow with safe concurrency and recovery.

Specify Schedule Semantics

Write:

timezone and calendar
intended window
late-start tolerance
overlap policy: forbid, queue, or replace
missed-run policy: skip or catch up
maximum run duration
data cutoff and watermark
manual rerun rule
owner and alert route

Cron describes a trigger, not business semantics. GitHub Actions documents schedule syntax and behavior; other platforms differ. Verify the selected platform’s timezone, delays, default branch, concurrency, and inactivity behavior.

Create a Stable Run Key

For a daily PKT report:

run_key = tenant + workflow_version + business_date

Insert the key under a uniqueness constraint before work. A retry resumes or reports the same run. Use a watermark for the last committed source event rather than “now minus 24 hours,” which can skip or duplicate records.

Deploy as a Least-Privilege Service

Pin dependencies, use managed secrets, restrict network and data access, set CPU/memory/time limits, and separate development from production. Include structured logs, metrics, failure alert, and a runbook. Test restoration and secret rotation.

Worked Example

A Karachi distributor creates a daily exception digest at 08:00 PKT. It reads orders through a read-only API, flags deterministic exceptions, drafts summaries, and publishes to a private review queue. It never contacts customers.

The run key is shop12:exceptions:v3:2026-07-19. If the scheduler triggers twice, the second process sees the existing run. If yesterday’s run is still active, overlap is forbidden and an alert fires. A manual rerun uses the same key unless an authorized operator creates a new revision. The watermark advances only after the report commits.

Failure Cases to Diagnose

Schedule timezone assumed: document and test it.
Two instances overlap: use durable uniqueness and locking.
Lookback uses local clock arithmetic: use watermarks and consistent timestamps.
Manual rerun creates duplicate emails: bind effects to run/effect IDs.
Workflow runs under a personal user: create a service identity and offboarding plan.
Success alert only: alert failure, overdue, and missing run.
No catch-up policy: decide what missed windows mean.

🇵🇰 Pakistan Angle

Pakistan does not currently observe seasonal daylight changes, but overseas clients and hosted schedulers may use UTC or another zone. Store machine time consistently and show PKT business windows explicitly. Review Ramadan, Eid, and public-holiday behavior as a business calendar decision.

Expect power or network interruptions at operator locations. The scheduler, state, and alerts should not depend on an employee laptop. If a local dependency is unavailable, checkpoint and notify rather than repeatedly contacting customers or issuing transactions.

Hands-On Exercise

Complete the schedule semantics contract.
Define run key, watermark, and overlap lock.
Deploy or diagram the service identity and secret path.
Test duplicate trigger, late start, missed run, timeout, and manual rerun.
Execute the failure runbook.

Done means: repeated or delayed triggers produce one correct effect set, and operators can see, stop, resume, or rerun safely.

Completion Rubric

Timezone, overlap, missed-run, and catch-up rules are explicit.
Durable run uniqueness prevents duplicates.
Watermarks define source completeness.
Production identity and secrets are least-privilege.
Missing, overdue, and failed runs alert owners.
Manual rerun and restoration are tested.

Sources

Key takeaway: scheduled autonomy needs durable run identity, explicit time semantics, overlap control, watermarks, and operated recovery—not just a cron expression.