Scheduled Runs

Scheduled runs automate recurring agent execution. The PostgreSQL-backed scheduler creates runs against a configured assistant at defined intervals, combining cron scheduling with the full Agent Server execution lifecycle.

At each trigger, the scheduler creates a new run, assigns it to an available worker slot, executes the assistant, and records the result. This gives you hands-off, repeatable agent execution without manual intervention.

How Scheduled Runs Work

The execution flow follows a simple pipeline:

Scheduler triggers at the configured cron interval
Creates Run against the selected assistant with the input template
Assigns to Worker based on slot capacity and concurrency limits
Executes the assistant within the Agent Server runtime
Records result with status, duration, and output

Each step participates in the same run lifecycle documented on the Runs page. Scheduled runs appear alongside manually triggered runs in the execution history, tagged with their schedule source.

Creating a Scheduled Run

Select Assistant

Choose which assistant to execute on the schedule. The assistant must already be configured in the Agent Server. Only assistants in an active state are available for scheduling.

Define Input Template

Configure the input payload that the assistant receives on each execution. Input templates support variable substitution for dynamic values:

{{date}} — current date in ISO format
{{day_of_week}} — weekday name (Monday, Tuesday, etc.)
{{timestamp}} — Unix timestamp at trigger time
{{run_number}} — sequential counter for this schedule


{
  "input": "Generate the daily summary report for {{date}} ({{day_of_week}}). Include metrics from the last 24 hours."
}

Configure Schedule

Set a cron expression defining the execution frequency. See Automation Scheduling for detailed cron syntax reference and timezone handling.

Set Session Mode

Choose how the assistant manages conversational state across runs:

new — Creates a fresh session for each run. The assistant starts with no prior context. Best for stateless tasks like report generation or data sync.
persistent — Reuses the same session across runs. The assistant accumulates context over time. Best for monitoring tasks that track trends or detect changes.

Activate

Enable the scheduled run. The scheduler begins evaluating at the next matching cron tick. You can pause and resume at any time without losing the schedule configuration.

Schedule Configuration

A scheduled run is defined by a JSON configuration object:


{
  "assistant_id": "asst_daily_report",
  "schedule": {
    "cron": "0 9 * * 1-5",
    "timezone": "America/New_York"
  },
  "input_template": "Generate the daily summary for {{date}}.",
  "session_mode": "new",
  "max_concurrent": 1,
  "skip_if_running": true,
  "timeout": 300
}

Configuration fields:

assistant_id — The assistant to execute (required)
schedule.cron — Standard 5-field cron expression (required). See Automation Scheduling for syntax details.
schedule.timezone — IANA timezone name (default: UTC)
input_template — Parameterized input with variable substitution
session_mode — new (stateless) or persistent (accumulates context). Default: new
max_concurrent — Maximum simultaneous runs from this schedule (default: 1)
skip_if_running — Skip trigger if previous run is still active (default: true)
timeout — Maximum execution time per run in seconds

Common Patterns

Daily Summary Agent

Runs every morning, aggregates data from the previous day, and generates a report.

Cron: 0 9 * * 1-5 (weekdays at 9 AM)
Session mode: new — each report is independent
Input: "Summarize activity for {{date}}."

Health Monitor Agent

Runs every 5 minutes, checks system health metrics, and alerts on anomalies.

Cron: */5 * * * *
Session mode: persistent — tracks trends across checks, detects deviations from baseline
Skip if running: true — avoid stacking checks

Data Sync Agent

Runs hourly, synchronizes data between systems with incremental updates.

Cron: 0 * * * *
Session mode: new — each sync is a clean operation
Max concurrent: 1 — prevent conflicting writes

Cleanup Agent

Runs weekly, archives old records, and optimizes storage.

Cron: 0 3 * * 0 (Sunday at 3 AM)
Session mode: new — stateless cleanup pass
Timeout: 600 — allow extra time for large archives

Monitoring

Execution History

The scheduled runs view displays a list of past executions with status, duration, and output summary. Each entry links to the full run detail page for deeper inspection.

Success and Failure Tracking

Monitor the reliability of your scheduled agents:

Success rate — Percentage of runs completing without error over a configurable time window
Failure reasons — Categorized error types (timeout, assistant error, capacity exhaustion)
Consecutive failures — Alert threshold for repeated failures indicating a systemic issue

Next-Run Countdown

The schedule detail view shows a live countdown to the next scheduled execution, along with the computed trigger time adjusted for the configured timezone.

Manual Trigger

Execute a scheduled run immediately outside of the normal cron cycle. This is useful for:

Testing a new schedule configuration before waiting for the first tick
Re-running after a failure without waiting for the next interval
Validating input template rendering with current variable values

Manual triggers create a standard run tagged with trigger: manual for auditability.

Scheduled Runs vs Automation Triggers

Automation triggers fire workflows in response to events or schedules. Scheduled runs fire agent assistants on the Agent Server. Both use the same cron engine under the hood, but target different execution runtimes.

Feature	Scheduled Runs	Automation Triggers
Target	Agent assistant	Workflow
Runtime	Agent Server (LLM-backed)	Workflow engine (DAG-based)
State management	Session mode (new/persistent)	Workflow state (stateless per run)
Use case	Recurring AI tasks, monitoring, reports	Data pipelines, integrations, batch jobs

Choose scheduled runs when your task requires reasoning, natural language processing, or adaptive behavior. Use automation triggers for deterministic, multi-step data pipelines.