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. The file lives in the agent’s Fontana Files namespace beside AGENT.md. Operators with agents:write edit it in AI → Agents or File System (/files). 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.

What is an agent schedule?

A shared definition (id, name, prompt, and trigger) stored in an agent package, plus your personal activation (enabled state, next due time for cron, and one reused chat thread). Triggers are a UTC cron expression, a workflow run event for one specific workflow, or manual (never auto-run).

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 once the saved file has synced. 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. In File System, the same file opens with the rendered schedules as Preview and the JSON as Source. If the file cannot be parsed, the last good schedules stay in effect and the error shows on the agent page and in the File System page.

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"; a command that never auto-runs). Optional workflowId binds it to a workspace. Optional condition is Show when: the command appears on that workspace’s exception rows and board cards when the row matches and you have turned that schedule on. A blank condition is offered on every row. The button uses the agent’s colour, with the agent’s face on the left. While it starts, the label is Calling and the agent’s name, with a spinner on the right. After the thread exists, the label is View thread and a chat icon on the right opens that thread. A person runs it from the row, or an agent runs it with Run now. A run from an exception row includes that exception in the thread. Play in the exception view menu starts the agent for the whole exception grid. The exception view also lists every trigger on the workspace beside view settings. The menu is titled Run agent commands, with Edit on the right, then Manual and Scheduled. Each row stays collapsed. Clicking a row opens that agent’s settings on the Schedules tab in the chat sidebar. Play shows a spinner, then View thread, which opens that thread. Edit opens Triggers. When you add a workspace trigger, the title in the box starts from the trigger you picked and stays editable.

{
  "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.

Workflow and exception event schedules can store a condition: property, operator, and value, the same row as a conditional colour rule. The agent runs when any condition matches any exception ticket on the triggering run. A blank condition fires on every matching event. Cron and email schedules fire without a condition. On a manual command the same condition is Show when for exception rows, not a fire gate. Run now starts the agent when a condition is set. Test now checks the latest completed run of the watched workflow and leaves the agent unstarted.

Every matching event fires all enabled activations for that definition (any activation owner). A turn that an activation started does not start that same activation again when it changes an exception status. Other activations of the definition still run. Each matching ticket records that the agent was triggered. If the last History items on every matching ticket are only from agents, the trigger is refused and History records “possible agent infinite loop rejected”. How many items count is an AI preference (default 10). A person changing the ticket, or a workflow run that loads new exception data, starts that count again. 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

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.

In AI chat, the lightning control beside the selected agent opens the same schedule list as the agent sidebar. When you have agents:write, + Add new Schedule creates a definition for that agent. The control stays available when the agent has no schedules yet.

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

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

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.

Related

• Agents - packages, tools, and handoff
• Human in the loop - approval and interruption patterns