> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenash.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Scheduling & execution
> Control how and when a custom agent runs — on a schedule, when something happens, or on demand — and whether it reports or acts.
Once you've built a custom agent, you decide *when* it runs and *what it's allowed to do* once it's running. This page covers the triggers that wake an agent up, how a run plays out from start to finish, and the difference between an agent that recommends actions and one that takes them.
## When to use this
Reach for scheduling and execution settings when you want a custom agent to do its work without you having to start it by hand. For example:
* A morning operations summary that lands in your inbox at 6am every day.
* An agent that springs into action the moment a specific kind of alert fires — say, a delivery falling behind schedule.
* A watcher that keeps checking on an in-flight delivery until it's resolved.
* A one-off run you kick off yourself to test the agent or get an answer right now.
You can also attach more than one trigger to the same agent — for instance, one that runs every morning on a schedule and another that runs whenever a matching alert arrives.
Creating and changing schedules is permission-gated. Managing an agent's runs is typically available to org admins and operations managers, not every user. If you can't see these settings, ask your Nash administrator.
## How a run works
A run is one session where the agent does its work. You configure three things that shape every run: the **trigger** that starts it, an optional **follow-up** behavior that lets it keep working over time, and the **stop conditions** that end it.
### Triggers — what starts a run
Each trigger declares one way the agent wakes up:
| Trigger | What it does |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **On a schedule** | The agent runs on a recurring clock you define (for example, daily at 6am). |
| **When something happens** | The agent runs when a matching Nash alert fires. The alert's details (the job or delivery in question) are handed to the agent so its first pass already knows what it's looking at. |
You can attach several triggers to one agent, each producing its own runs.
The "when something happens" trigger is closely related to the [Entity monitor](/nash-agent/entity-monitor), which keeps watching a single delivery, order, or route until it reaches a final state.
### Follow-up passes — keep working until the job is done
By default, an agent runs once per trigger and then finishes. That's the right choice for most reporting and one-shot tasks.
You can instead set the agent to keep working in follow-up passes on a fixed interval. Each follow-up pass gives the agent a fresh look at what's changed since last time, plus a short carry-forward summary of what it found earlier — so it stays focused on the current situation rather than re-reading its whole history. This is what you want when the agent needs to watch something evolve, like checking back on a delivery every 15 minutes until it's delivered or canceled.
You choose how often the follow-up passes happen, anywhere from once a minute up to once a day.
### Stop conditions — when a run ends
A run ends when any of these is true:
* It hits the **stop condition** you configured — a time limit, an event that signals the work is done, or no automatic end at all (you stop it yourself).
* It reaches a **safety deadline**. Every run has a hard ceiling on how long it can stay alive (12 hours by default, adjustable). This applies even to runs with no automatic end condition, so nothing runs forever.
* It hits the **spend or token cap** set on the agent.
* It **repeatedly fails**. If the agent errors several times in a row, the run stops automatically rather than spinning.
* For a watcher, the thing it was watching **reaches a final state** (completed, failed, canceled) or can no longer be found.
Turning a trigger off or deleting it also closes any runs it currently has open.
### After a run finishes
Each run shows up in the agent's run history with its status, a summary, any output it produced, and its token usage and cost. When a run finishes — whether it succeeded or failed — it can notify the people or groups you've configured, based on whether you want to hear about every run, only failures, only successes, or only when the run's results match a condition you set (for example, only when a check comes back failing).
## Report-only vs. auto-execute
This is the most important safety choice for an automated agent. It's a property of the agent itself, and it applies to every run that agent produces.
| Mode | What the agent does |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Report only** (default) | The agent investigates and writes up what it found and what it *would* do. It does not take any real action — anything that would change your operation is surfaced as a recommendation, not performed. |
| **Auto-execute** | The agent can carry out actions itself — for example, canceling a delivery, requesting a refund, or reassigning a provider — without waiting for you. |
New agents start in **report only**, and any agent you duplicate is also forced into report only as a safety default. You promote an agent to auto-execute deliberately, once you trust what it's doing.
### How confirmations fit in
Even in auto-execute mode, you can keep specific destructive actions behind a human OK. For those actions, the agent pauses and surfaces a confirmation request instead of acting — the action only happens after someone approves it.
Some actions always require confirmation no matter the mode — for example, sending an SMS or placing a voice call. The agent will never fire these on its own; they wait for explicit approval.
If you're watching a delivery with follow-up passes, each new pass replaces any still-pending confirmation requests from the previous pass. That way your approvals queue only ever shows the agent's latest proposals, not stale ones.
## Set up a schedule
In the agent builder, add a trigger to the custom agent and choose **On a schedule**.
Enter how often the agent should run as a cron expression — for example, `0 6 * * *` for daily at 6am. You can leave it blank as a placeholder; an empty schedule simply does nothing until you fill it in.
Pick the time zone for the schedule.
Schedules currently run against UTC. The time zone you choose is stored, but the run time is interpreted in UTC for now — so set your cron expression in UTC.
Decide whether this agent should **report only** or **auto-execute**, and choose which destructive actions still require confirmation.
Save the agent. The schedule takes effect immediately and runs on the cadence you set.
## Turn a chat into a scheduled report
You don't have to build a scheduled agent from scratch. When a chat session has done something worth repeating — a summary you pulled together, a check you ran by hand — choose **Schedule as a report** from the session menu. Nash reads what the conversation did and drafts a scheduled agent from it: a name, a cadence, a time zone, and the recipients, laid out in a card you can edit before you confirm. Once you save, it runs on the schedule you set like any other scheduled agent.
## Run on demand
You don't have to wait for a trigger. Use **Run now** to start a run immediately — it ignores the configured trigger and starts right away. A few things to know:
* A manual run belongs to you, so it shows up in your own chat history as well as the agent's run history.
* Manual runs always start fresh, so clicking **Run now** twice in a row gives you two distinct runs.
* A manual run works even if the agent is paused — it's an explicit override on your part.
Pausing an agent silences all of its automated triggers at once without deleting anything. Resume it to bring the triggers back. Manual **Run now** still works while paused.
Pause is the quick way to stop an agent from running automatically while you adjust it, investigate a problem, or take it offline temporarily — no need to delete and rebuild its triggers.
## FAQ
Yes. Attach as many triggers as you need to a single agent. A common pattern is a daily scheduled summary plus an event trigger that fires whenever a matching alert arrives.
Every run has a hard safety deadline (12 hours by default, adjustable up to a week). It applies on top of whatever stop condition you chose — even a run with no automatic end is force-stopped at the deadline. A watcher also closes itself when the thing it's watching reaches a final state.
You can edit a trigger's details — its schedule, time zone, follow-up interval, stop condition, and on/off state. To switch a trigger to a different *kind* (say, from a schedule to an event), remove it and add a new one.
Turning off a single trigger stops just that one (and closes any runs it has open). Pausing the agent silences all of its triggers at once. Both leave your configuration intact so you can re-enable later.
## Related
Define a reusable agent — its instructions, scope, tools, and output.
Keep watching a delivery, order, or route until it's resolved.
How destructive actions are gated behind your approval.
Give your agents reference material to ground their work.