Skip to content

Run an Agent on a Schedule

How do I have Support helper review open tickets every weekday morning without anyone asking? Add a schedule to the published agent. At each time it sets, the schedule sends its message to the agent in a new Live conversation, as if you had typed it.

A schedule replaces a workflow whose only job was to message an agent on a timer. Use a trigger when the work itself belongs in a workflow.

  • Each run is a new Live conversation on the latest published version. Publish before you add a schedule.
  • It runs as you, the owner, with your connections and approval rules, and it uses your organization’s usage balance.
  • Every run happens, even while an earlier run is still working or waiting for an approval. Pick a cadence that leaves each run time to finish.
  • Only the owner sees and manages schedules. An agent can have up to 10, and none can run more often than every 15 minutes.
  • Turning a schedule off stops its runs. While the agent is paused, its runs fail with The agent is paused.

In the app: open Agents → Support helper → Live → Schedules → New schedule. The button appears only in Live, and only for the owner.

  • Name: Morning ticket review. Each run’s title starts with it, followed by the date and time.
  • Message: what the agent receives each time, such as Review open tickets older than two days and draft follow-ups for each.
  • When: choose Every day, Weekdays, On selected days, or Monthly, then a time. For anything else, such as every two hours from 9 to 5 on weekdays, choose Custom (cron) and enter a five-field cron: 0 9-17/2 * * 1-5.
  • Time zone: defaults to your profile’s time zone, or your browser’s. The schedule runs in this zone, including across daylight saving changes.
  • Model: Agent default uses the agent’s own model. Choose another model for this schedule’s runs only.

Choose Create schedule. Use ⋯ → Run now to start one run immediately and check the result.

Scheduled runs appear in the agent’s Conversations list with the schedule’s name where Slack conversations show their channel. Choose ⋯ → View runs on a schedule, or select the name on a run, to show only that schedule’s runs. The filter is in the page address (?schedule=<id>), so you can bookmark it. Open a run to read it or reply, like any conversation.

When the latest run fails, the schedule shows a red icon. Point at it for the reason, such as The agent is paused or Out of usage credit. A run that starts without usage credit still opens its conversation, but the agent can’t answer until the balance is topped up.

Use ⋯ → Edit to change any field, and the switch on the schedule to turn it off and on. ⋯ → Delete removes the schedule; the conversations it started stay.

Schedule tools are owner-only and take the agent’s ID as a string. Find the agent with agent_list, then list its schedules with agent_schedule_list:

{ "agentId": "<agentId>" }

Create one with agent_schedule_create. Omit model for the agent’s default:

{
"agentId": "<agentId>",
"name": "Morning ticket review",
"message": "Review open tickets older than two days and draft follow-ups for each.",
"cron": "0 9 * * 1-5",
"timezone": "America/Chicago"
}

Note the returned scheduleId. agent_schedule_update takes agentId, scheduleId, and only the fields to change; enabled: false turns it off. agent_schedule_run starts one run now, and agent_schedule_delete removes the schedule. Each schedule in agent_schedule_list reports lastStatus, lastError, and lastConversationId; read that run with agent_conversation_history.

A cron outside the limits, such as one that runs every 5 minutes, or a time zone that isn’t an IANA name, is refused with a message saying why.