# Schedules

Source: https://www.hyperagent.com/docs/concepts/agents/invocations/schedules

> For AI agents: the documentation index is at https://www.hyperagent.com/llms.txt and the complete documentation in one file at https://www.hyperagent.com/llms-full.txt. Any docs page is also served as Markdown by appending `.md` to its URL.

Put an agent on a recurrence: define the work, control its threads and write access, deliver the result, and review every run.

You have a report that should exist every Monday at 7 AM, whether or not you remembered to ask for it. A **schedule** is how you hand that job over: the agent receives the schedule's message, works in a thread, and delivers the result where you chose, with nobody watching.

Brief the job once, choose when it should run, and decide where the result
belongs. The agent repeats that work with fresh information on every
occurrence.

## How schedules work [#how-schedules-work]

Set a schedule in plain language or with the recurrence controls. Hyperagent
keeps the timing in your timezone and calculates each next occurrence.

The agent receives the schedule's message as its instructions. Template
variables can add the current date, time, weekday, or run count.

Choose whether runs start fresh or continue together, then decide whether
the agent may only read, ask before changes, or write unattended.

Hyperagent delivers the finished result after the run and records its
status, duration, thread, and errors in Run History.

## Create and configure a schedule [#create-and-configure-a-schedule]

On the agent's **Invocations** tab, open the **Scheduled** card and select **Create schedule**.

### Describe the routine [#describe-the-routine]

Enter timing and work together—for example, `Every Monday at 9 AM, check my inbox and summarize unread emails.` Select **Generate** to draft the complete schedule, or **Skip** to open the form directly.

### Confirm the recurrence [#confirm-the-recurrence]

Review the generated timing, timezone, and next occurrence. Every generated field remains editable.

### Brief the work and choose its thread [#brief-the-work-and-choose-its-thread]

Write instructions that can stand on their own, then decide whether each occurrence starts fresh or continues in an existing thread.

### Set guardrails and delivery [#set-guardrails-and-delivery]

Choose the write level, quiet-delivery behavior, completion notification, and destination before saving.

## Schedule configuration options [#schedule-configuration-options]



[Live Mode](https://www.hyperagent.com/docs/concepts/agents/invocations/live-mode) uses a rolling
monitoring interval and is configured from its own control on the agent, not
from the schedule builder.

## Set the timing and recurrence [#set-the-timing-and-recurrence]

### Set the recurrence [#set-the-recurrence]

Describe the timing in plain language—`Every weekday at 8:30` or `The last Friday of the month`—and let **Generate** build it, or configure the recurrence manually. Both paths produce the same schedule.

| You want              | You configure                                                              |
| --------------------- | -------------------------------------------------------------------------- |
| A daily brief         | **Daily** and a time                                                       |
| Weekdays only         | **Weekly**, the five weekday choices, and a time                           |
| Every other week      | **Weekly**, every 2 weeks                                                  |
| A monthly report      | **Monthly**, then a date or a slot such as First Monday or Last Friday     |
| High-frequency checks | **Hourly** or **Minutely**, keeping at least 5 minutes between occurrences |

Hyperagent stores every schedule as a standard recurrence rule, or RRULE, with an IANA timezone. If you already have an RRULE, the API accepts it directly.

### Template variables [#template-variables]

The message and new-thread naming hint support variables resolved in the schedule's timezone at runtime:

| Variable        | Resolves to                          |
| --------------- | ------------------------------------ |
| `{{date}}`      | The occurrence's date                |
| `{{time}}`      | The occurrence's time                |
| `{{dayOfWeek}}` | The weekday name                     |
| `{{isoDate}}`   | The date in ISO format               |
| `{{runCount}}`  | How many times this schedule has run |

A naming hint such as `Weekly pipeline report {{isoDate}}` keeps months of run threads sortable.

### Timezones and clock changes [#timezones-and-clock-changes]

Daily and coarser schedules preserve local wall-clock time through daylight-saving changes, so a 7 AM report stays at 7 AM. Sub-daily schedules measure elapsed time instead, so `Every 4 hours` remains four hours apart even when the clock changes.

## Choose how scheduled runs work [#choose-how-scheduled-runs-work]

### Choose a thread strategy [#choose-a-thread-strategy]

Every occurrence gets a clean thread carrying the agent's instructions,
skills, and memories but no history from earlier runs. Use it for work that
should stand on its own.

Every occurrence is appended to one existing thread, so the agent can read
what earlier runs left there. The thread must belong to this agent.

Use the optional **Thread naming hint** to derive each new thread's title from runtime variables or the work itself. Leave it empty to use the default name.

### Choose standard, alert, or Live behavior [#choose-standard-alert-or-live-behavior]

| Behavior     | How you configure it                                               | What you receive                                                                                                              |
| ------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| **Standard** | The schedule default                                               | Every run reports. Use it when the output should exist every time, such as a Monday report.                                   |
| **Alert**    | Enable **Only deliver when something needs attention**             | The agent explicitly reports a status after each run; all-clear runs stay quiet and only findings are delivered.              |
| **Live**     | Configure [Live Mode](https://www.hyperagent.com/docs/concepts/agents/invocations/live-mode) | Rolling monitoring with a 30-minute minimum, alert-style silence, and an automatic pause after repeated consecutive failures. |

Standard schedules keep at least five minutes between occurrences. Live Mode keeps at least thirty.

### How scheduled runs start [#how-scheduled-runs-start]

If the previous run is still working when the next scheduled time arrives,
the new run waits. A schedule never runs two jobs at once.

When a schedule continues an existing thread, it waits while someone is
actively using that thread and starts when they're finished.

The schedule keeps moving while paused, blocked by billing, or waiting on
another run. It starts at the next scheduled time without creating a
backlog.

### Run Now and completion [#run-now-and-completion]

**Run Now** starts an immediate occurrence without moving the recurrence. The next scheduled time remains unchanged. Use it to test the message, thread behavior, write controls, delivery, and completion notification end to end.

When a fixed-span recurrence has no future occurrences, the schedule marks itself **Completed** instead of remaining active indefinitely.

## Control writes and delivery [#control-writes-and-delivery]

### Integration writes and approvals [#integration-writes-and-approvals]

Scheduled runs work without you present and may act on content nobody reviewed first. Standard schedules therefore default to read-only.

Read connected apps normally without changing them. Most reporting and
monitoring jobs don't need more access.

Stop at the first attempted change and create an approval with an exact
preview of what would be sent.

Use the agent's normal integration access unattended. Reserve this for
schedules you've observed and trust.

Approving a pending write executes exactly the previewed action and nothing more. Denied or expired approvals can never execute. A run waiting for approval doesn't block the recurrence; later occurrences follow the normal schedule instead of stacking behind it.



### Deliver results [#deliver-results]

Hyperagent delivers after the run finishes, separately from the agent's integration permissions. A read-only schedule can therefore send its completed report to Slack, Telegram, or email.

| Destination       | Where the result lands                          |
| ----------------- | ----------------------------------------------- |
| **Thread**        | The run's thread, with no external copy         |
| **Slack channel** | The configured channel                          |
| **Slack DM**      | A direct message to the schedule creator        |
| **Telegram**      | The chat mapped to the schedule's target thread |
| **Email**         | The schedule creator's email address            |

**Notify when complete** is separate from report delivery. It sends a browser or mobile push after the run, including runs started with **Run Now**.

Two delivery rules prevent surprises:

* **The destination is snapshotted when the run starts.** Editing delivery during an active run can't redirect that result; the new destination applies on the next occurrence.
* **Delivery failures remain visible.** A completed run that couldn't deliver adds a warning to the schedule. A later successful delivery clears it.



## Monitor and manage a schedule [#monitor-and-manage-a-schedule]

### Run History [#run-history]

Every schedule records each occurrence in **Run History**, including its status, start time, duration, thread, and any error or result classification.



### Ownership on team agents [#ownership-on-team-agents]

A schedule belongs to its creator. Runs use that person's context, count against their usage, and keep that ownership even when other teammates use the agent.

The schedule doesn't continue under a missing owner. If its creator leaves the
workspace, it pauses. Teammates with run-only access to the shared agent can't
create or edit schedules.

## Troubleshooting and FAQs [#troubleshooting-and-faqs]

It serves the same recurring-job purpose with a visual and plain-language builder. Hyperagent stores the result as an RRULE with an IANA timezone. Daily and coarser schedules preserve local wall-clock time through clock changes; sub-daily schedules measure elapsed time.

The new occurrence is deferred. Occurrences from one schedule never run concurrently. In continue mode, they also wait while a person actively uses the target thread. The recurrence advances without building a backlog.

No. While a schedule is paused or blocked, the recurrence keeps advancing. When the schedule can run again, it fires at the next occurrence instead of catching up on everything it missed.

No. It starts an immediate occurrence while the next scheduled time stays where it was. Run Now counts as an unattended run, so write controls, delivery, and completion notifications still apply.

A Live schedule pauses after repeated consecutive errors, and a team schedule pauses when its creator leaves the workspace. A fixed-span schedule with no future occurrences becomes Completed instead. Other failures remain visible in Run History without automatically pausing a standard schedule.

That run was already active. Hyperagent snapshots delivery when a run starts, so an in-flight edit can't redirect it. The next occurrence uses the new destination.

Continue mode requires an existing thread that belongs to this agent. Select one of the agent's own threads.