Skip to content
Back to

Agent schedules

Agent schedules let you run AI work from package-authored definitions on a timer or when a workflow run finishes. 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. 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…"
      }
    }
  ]
}

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 a new workflow_exceptions row for that workflow
  • exception_status_changed - evaluated when set_status changes an exception status (severity-only updates do not fire)

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 exception metadata into the activation thread userContext (exceptionId, exceptionKey, status, severity, and for status changes previousStatus).

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 (cron and event metadata)
  • agents_activateAgentSchedule / agents_disableAgentSchedule - toggle your activation (agents:read)

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.

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”