Skip to content
Back to

Agent schedules

Agent schedules let you run AI work from package-authored definitions on a timer, when a workflow run finishes, or only when you (or another agent) trigger them. Each agent package can include a schedules.json file. Operators with agents:write edit that file in AI → Agents. You activate a definition for yourself so the schedule can fire: it appends the prompt on one persistent messaging thread and runs the target agent.

Author definitions

Section titled “Author definitions”
  1. Open AI → Agents.
  2. Open the agent package (AGENT.md). Package folders open that file automatically.
  3. Open the Schedules tab. If the package has no schedules.json yet, choose Create schedules.json.
  4. Use My activations to add, edit, or delete shared definitions (requires agents:write). New rows from + Add schedule turn On for you after ingest. Cron schedules use an interactive UTC recurrence builder (interval, weekdays, time). Event schedules let you pick the run outcome and watched workflow. Manual schedules stay off the timer and event watchers until Run now or agents_triggerAgentSchedule. The JSON editor stays available for advanced edits; turn On for definitions you author only in JSON.

You can still open schedules.json directly in the file tree when it already exists.

Cron example (schedule.kind is "cron"):

{
  "schedules": [
    {
      "id": "daily-digest",
      "name": "Daily digest",
      "prompt": "Summarise overnight activity.",
      "schedule": { "kind": "cron", "expr": "0 8 * * *" }
    }
  ]
}

Event example (schedule.kind is "event"; workflowId is required):

{
  "schedules": [
    {
      "id": "on-nav-fail",
      "name": "On NAV failure",
      "prompt": "Investigate the failed NAV run and propose next steps.",
      "schedule": {
        "kind": "event",
        "event": "workflow_run_failed",
        "workflowId": "jd7…"
      }
    }
  ]
}

Manual example (schedule.kind is "manual"; never auto-runs):

{
  "schedules": [
    {
      "id": "on-demand-review",
      "name": "On demand review",
      "prompt": "Run the review playbook.",
      "schedule": { "kind": "manual" }
    }
  ]
}

Supported event keys:

  • workflow_run_completed (success or failure), workflow_run_failed, workflow_run_succeeded - evaluated when the workflow engine writes a terminal run_results row (completedAt set)
  • exception_raised - evaluated when sync_from_run inserts new workflow_exceptions rows for that workflow (one agent fire per run, with every new ticket)
  • exception_status_changed - evaluated when set_status changes an exception status (severity-only updates do not fire; one ticket per status write)
  • email_received - evaluated when inbound SMTP writes MIME to an operator-created agent’s mailbox (no workflowId). Delivery always stores the message; a turn starts only when this definition is present and your activation is On. See Agent email.

Every matching event fires all enabled activations for that definition (any activation owner). You need read access to the watched workflow to activate or fire an event schedule. Exception fires write the batch into the activation thread user context: selection.exceptionIds plus exception.exceptions (id, key, type, message, status, severity, assignee when set, and for status changes previousStatus). A run that raises many tickets still starts one turn. Use workflow_getException with each exceptionId; do not list every ticket on the workflow to find the batch.

Definitions do not store user ownership or enabled state. Those live on your activations.

Activate for yourself

Section titled “Activate for yourself”

On the same schedules.json panel, or via chat tools on Fontana Agent / Agents Agent:

  • agents_listAgentSchedules - discover shared definitions for any agent (omit agentId or pass another agent’s catalog id). Includes cron, event, and manual metadata
  • agents_activateAgentSchedule / agents_disableAgentSchedule - toggle your activation (agents:read)
  • agents_triggerAgentSchedule - fire any agent’s schedule now. Optional userContext JSON; when omitted, the triggering thread’s user context is copied onto the schedule thread

Each activation card has Run now on the Last run row, which fires that schedule immediately (same path as the timer or workflow event), including manual schedules. Unsaved edits must be saved first. Cron Run now still advances the next due time from the moment you fire.

On an open workflow, the right-toolbar Triggers panel lists Workflow cron triggers (backend runs) and Agent event triggers for that workflow id. You can create an event schedule for a chosen agent package from there when you have agents:write. Event cards on that panel also include Run now.

Each fire reuses the activation thread (created on first run). The thread appears in AI → Threads. Before the scheduled prompt is written, Fontana cancels any pending tool calls on that thread (tool results say they were cancelled by the incoming scheduled call) and discards an in-flight model turn so the new prompt owns the conversation. Deleting the package disables activations and removes shared definitions; historical threads stay.

Create event schedules from chat

Section titled “Create event schedules from chat”

You can ask Fontana Agent (or Agents Agent) to wire an event schedule without hand-editing JSON. The model resolves concrete ids first, then calls agents_upsertAgentEventSchedule:

  1. Resolve workflow_id with workflow_listUserWorkflows (for example nameContains: "NAV") or from host userContext.
  2. Resolve agent_id with agents_listAgents (for example nameContains: "XYZ") or the current thread agent id.
  3. Call agents_upsertAgentEventSchedule with required event, agent_id, workflow_id, prompt, and optional enabled (defaults to true).

Do not pass placeholders such as "current" or "this" as ids. Set enabled: false when you only want the shared definition written.

When a fire cannot run

Section titled “When a fire cannot run”

If the scheduled turn hits the conversation spending cap or message-order budget, the activation auto-disables and records a reason. Event schedules that lose workflow read access auto-disable at fire time.

Section titled “Related”