Scheduling Tasks (Experimental)

This feature is in the Experimental stage and under active development. Configuration schemas and behavior are subject to change. We recommend that you do not use this feature in production environments.

Prerequisites — Scheduled Tasks requires SQL-backed session persistence on the Web UI entrypoint (SQLite or PostgreSQL).

A scheduled task is an agent invocation that runs on its own, on a recurring schedule, at fixed intervals, or once at a specific time. You describe the message the agent receives, the target agent or workflow, and when the task fires. The Web UI entrypoint (the same process that serves the Solace Agent Mesh UI) holds the schedule, fires the task, and records the outcome.

Scheduled tasks live in the Schedules area in the sidebar. They are stored per user and are not tied to any one project. This page covers creating, managing, and monitoring scheduled tasks in the Agent Mesh UI.

Creating a Scheduled Task

On an empty deployment, the Schedules page offers two starting points:

  • Build with AI — Opens a Create Scheduled Task dialog with a natural-language description textarea. Suggestion chips prefill the textarea (for example, "Generate daily report at 9 AM"). Select Generate and the AI drafts the schedule type, target agent, and message from your description. Review and adjust before saving.

  • Create Manually — Opens the same Create Scheduled Task form with empty fields you fill in directly.

To create a task manually:

  1. In the sidebar, open Schedules.

  2. Select Create Manually.

  3. Give the task a Task Name (required); optionally add a Description.

  4. Choose a Schedule Type (Recurring Schedule, Interval, or One Time) and fill in its parameters. See Schedule Types.

  5. Choose a Timezone (required; defaults to your browser's zone).

  6. Under Task Configuration, choose a Target (Agent or Workflow), pick the target from the drop-down list, and write the Instructions the agent or workflow receives when the task fires. Output is fixed to Chat in the current release.

    If the workflow you choose declares an input schema that plain text cannot satisfy, the form lists the required and optional fields with their types. When you select the workflow and Instructions is empty, the form fills it with a JSON template of the required fields. The form adds the template only when you select or change the target, so it does not restore the template after you clear Instructions. Replace the template values with the input you want, and add optional fields as needed. The workflow receives the JSON object as its input each time the task fires.

    For such a workflow, the form displays an error and does not save the task until Instructions contains a JSON object that includes every required field and matches the field types and allowed values that the schema declares. A workflow whose input schema plain text satisfies, for example, one whose only required field is text, keeps the free-text Instructions field.

  7. Select Create and Activate to save and start firing immediately, or Create to save the task in a disabled state (resume it later from the task's Actions menu).

After saving, the Schedules page shows the task as a card with its schedule, next-run time, and status.

Schedule Types

Three schedule types are supported:

Type What you enter Example
Recurring Schedule A Frequency (Daily, Weekly, Monthly, or Custom (Cron Expression)) plus a Time picker. Custom (Cron Expression) opens a raw cron textbox with a live plain-English preview, format hint, canned examples, and syntax legend. Every Monday at 09:00.
Interval A numeric field plus a unit combobox (Seconds, Minutes, Hours, Days). Default 30 Minutes. Minimum 60 seconds; the UI enforces a one-year upper bound. Every 6 hours.
One Time A date picker plus a time picker. Fires once at that moment and never refires. November 17, 2026 at 09:00 UTC.

For a cron expression, the scheduler accepts the standard 5-field POSIX syntax (minute, hour, day-of-month, month, day-of-week). Second-precision schedules are not supported. Sunday is indexed as 0; the names sun through sat also work.

If the entrypoint misses a scheduled time, for example while Agent Mesh is stopped or restarting, the task runs once when the entrypoint is running again, provided that the run is less than misfire_grace_time_seconds late (10 minutes by default). If the run is later than that, the entrypoint skips it, records a Skipped execution that shows how late the run was, and logs a warning. Several missed times of one task produce at most one run. These rules apply to all three schedule types. For example, after a two-hour outage, the entrypoint skips the missed run of a task on a 30-minute interval because the run is more than 10 minutes late, and the task continues at its next scheduled time.

Managing Scheduled Tasks

Once you have created a task, the Schedules page shows it as a card in a grid. Each card carries the task name, the schedule description (Occurs: Daily at 09:00), the next-run relative time (Next run: In 23 hours), and a status pill (Active, Paused, or Error). The page header provides a Filter search box (filter by name, description, or agent), a Status filter, and a Refresh button.

Every card carries an Actions menu:

  • Run Now — Fires the task immediately without waiting for its next scheduled time. Only available when the task is enabled and not a one-time or declarative-config task.

  • Edit Task — Reopen the task form to change the schedule, target agent, or instructions.

  • View Execution History — Opens the full task detail page focused on the executions table.

  • Pause Task / Resume Task — Toggle the task's active status. A paused task stays registered but never fires. An execution that is already in progress finishes, and the scheduler skips a retry that is waiting to start.

  • Delete Task — Remove the task and its execution history.

Selecting a card opens a side panel on the right of the page. The panel shows the task's description, current status, schedule, primary actions (Run Now and Task Details), and a compact Execution History with the latest runs. Select Task Details to navigate to the full detail page, which shows the full configuration on the left (Name, Description, Schedule, Timezone, Agent, Output, Instructions) with an Edit button, and the full Execution History table on the right with columns for Run Time, Status, and Duration, plus a Date Range filter.

Reviewing Execution History

Every execution moves through a small state machine, surfaced in the Execution History table on the detail page and in the compact list in the side panel:

Status Meaning
Pending The schedule fired and the execution is recorded, but the task is not yet dispatched to the agent.
Running The worker dispatched the task; the agent is processing it.
Completed The agent returned a result, and that result was recorded.
Failed The execution ended in an error. Triggers include: the agent returned an error, the caller was unauthorized, or the entrypoint rejected the task because the agent entered an interactive state (see Production Considerations). An agent or workflow that finishes in a failed, rejected, or canceled state also ends the execution as Failed, for example when a workflow's input does not match its input schema.
Timeout The per-execution timeout elapsed before the agent finished, or before the entrypoint sent the task to the agent. The message on the execution shows which case applies. Distinct from Failed.
Cancelled The operator canceled the execution mid-run.
Skipped The scheduler did not run the task at a scheduled time for one of these reasons: the target agent was not discoverable, the task was already running from a previous fire, the entrypoint missed the scheduled time by more than misfire_grace_time_seconds (the execution shows how late the run was), the scheduler was unable to parse the schedule, or the task was paused while a retry was waiting. The schedule continues on cadence; the next fire produces a fresh execution.

Task-level status (shown on the card and side panel) is a separate concept: Active (running on cadence), Paused (registered but not firing), or Error (the schedule itself is in a bad state).

Production Considerations

A few things worth knowing before you rely on a scheduled task in production:

  • No human in the loop. A scheduled task runs with no user available to answer questions. If the agent's execution transitions the task into an input-required or auth-required state — for example, a Human-in-the-Loop (HIL) tool that pauses for approval, or an authentication step that needs an end-user OAuth callback — the entrypoint has no way to satisfy that request and rejects the task immediately. The execution lands in Failed with a clear error. To preflight, open a task's side panel, and select Run Now; a Failed execution with an interactive-state error means the agent hit one of these gates. Audit an agent's tools before scheduling it against it, or pre-configure any required credentials.

  • Restart recovery. If the entrypoint restarts while an execution is running, the execution continues. The entrypoint records the result from the agent when it arrives. If no result arrives before the task timeout elapses, the execution ends as Timeout. A task without its own timeout uses default_timeout_seconds. A scheduled time that the entrypoint misses during the restart follows the rules in Schedule Types.

  • Concurrent runs. The scheduler runs different tasks in parallel with no scheduler-wide cap. A task runs one execution at a time: if a fire arrives while the task's previous execution is still running, that fire produces a Skipped execution.

Operator Setup

This section is for the operator running the Web UI entrypoint, not for users authoring schedules from the UI. If you configure schedules from the Agent Mesh UI, you can skip this section.

The scheduler is configured on the Web UI entrypoint under the top-level scheduler_service: key:

# Web UI entrypoint config - scheduler_service fragment
scheduler_service:
  enabled: true
  default_timeout_seconds: 3600
  retry_delay_seconds: 60
  execution_history_keep_count: 100
  misfire_grace_time_seconds: 600
  auto_pause_after_consecutive_failures: 10

The defaults:

Key Default What it does
enabled true Master switch. Omitting the block also leaves the scheduler enabled; set to false explicitly to turn it off.
default_timeout_seconds 3600 (1 h) Per-execution wall-clock cap when a task does not set its own.
retry_delay_seconds 60 Delay between automatic retries when a task has automatic retries configured.
execution_history_keep_count 100 Per-task cap on history rows. Older executions are pruned.
misfire_grace_time_seconds 600 (10 min) How late a missed scheduled time can be and still run. The entrypoint skips a missed time that is later than this and logs a warning. Applies to recurring, interval, and one-time schedules.
auto_pause_after_consecutive_failures 10 Pauses a task after this many consecutive failed executions. Resume it explicitly from the task's Actions menu once you have investigated the failures.

The scheduler is on by default wherever SQL session persistence is configured — entrypoint configurations that omit scheduler_service: still get the feature. To opt out, add the block with enabled: false.

Related Topics