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. Anyone with an editor grant on that namespace edits 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: a file in your personal space in Fontana Files that turns the definition on or off for you. Fontana keeps the next due time for cron and one reused chat thread beside it. 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 an editor grant on the agent’s namespace). 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"; project is the Workspace and workflowPath is the workflow file inside it):

{
  "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",
        "project": "NAV production",
        "workflowPath": "Daily NAV.wf.json"
      }
    }
  ]
}

On the two exception events you can leave workflowPath out and keep project. The schedule then watches every workflow in that Workspace, which matches the Workspace-wide Exception Management view.

Manual example (schedule.kind is "manual"; a command that never auto-runs). Optional project binds it to a Workspace, and an optional workflowPath narrows it to one workflow in that 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 records the end of a build of the watched workflow
• exception_raised - evaluated when a build records new exception tickets in the watched Workspace (one agent fire per build, with every new ticket)
• exception_status_changed - evaluated when an exception’s status changes (severity-only updates do not fire; one fire per status change)
• email_received - evaluated when inbound SMTP writes MIME to an operator-created agent’s mailbox (no project). 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 view filter. The agent runs when any condition matches any exception ticket the event touched. 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 runs the clause over the watched workflow’s current tickets 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 build that records new exception data, starts that count again. You need read access to the watched Workspace 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 build that raises many tickets still starts one turn, and each recorded change starts at most one turn. Use workflow_getException with each ticket id; do not list every ticket in the Workspace to find the batch.

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

Activate for yourself

Turn a definition On or Off on the same schedules.json panel. Each activation is one small file in your personal space in Fontana Files, schedules/<agent id>/<schedule id>.yaml, holding enabled: true or enabled: false. Because it is a file, your activations come back when the tenant is restored from Fontana Files. Turning a schedule on needs agents:read and read access to the agent’s namespace. Without them the change is refused and the activation stays as it was.

Fontana Agent and Agents Agent work with the same files through chat:

• mcp_ffs_get_file (the files ability) - read an agent’s shared definitions (cron, event, and manual) from its schedules.json
• mcp_ffs_put_file (the files ability) - turn a schedule on or off for you by writing your activation file
• agents_triggerAgentSchedule - fire any agent’s schedule now, named by agent_id and schedule_id, the schedule’s id in that agent’s schedules.json. 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 Agent Automation panel lists the Agent event triggers for that workflow. You can create an event schedule for a chosen agent package from there when you have an editor grant on that package’s namespace. Event cards on that panel also include Run now. A timer that runs the workflow itself is set on the node that needs it, in the workspace editor, and the fire times are UTC there too: see Scheduled runs.

In AI chat, the lightning control beside the selected agent opens the same schedule list as the agent sidebar. When you have an editor grant on the agent’s namespace, + 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 the watched workflow file with workflow_searchWorkflows without a query (for example nameContains: "NAV"; each hit names its Workspace, the project, and the .wf.json path inside it, the workflow_path) or from the open workflow in 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, project, workflow_path, and prompt. It writes the shared definition only and turns it on for nobody.
4. Write your activation file with mcp_ffs_put_file to turn the schedule on for you. The upsert result names the file.

Do not pass placeholders such as "current" or "this" as ids.

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. Fontana also sets your activation file to enabled: false, so the file and the schedule agree; turn it On again to clear the reason.

Related

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