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.
What a scheduled run is
Section titled “What a scheduled run is”- 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.
Add a schedule
Section titled “Add a schedule”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.
Find its runs
Section titled “Find its runs”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.
Change, pause, or delete it
Section titled “Change, pause, or delete it”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.
With an assistant
Section titled “With an assistant”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.