1. Run an Agent on a Schedule
A cron trigger starts an agent at times that repeat, for example every Monday at 09:00. A once trigger starts an agent one time, at a date and time that you set. In this page, you build an agent that lists stale pull requests, and you run it with both triggers.
Step 1: Build the Stale PR Digest agent
The agent reads the open pull requests of a public GitHub repository. It lists the pull requests that have had no update for some days.
Go to Agent Studio → Agents and create an agent. In Agent name, type Stale PR Digest and click Create blank. In the editor, click New → New file, and create agents/stale-pr-digest/instructions.md with this content:
You write a digest of the stale pull requests in one public GitHub repository.
The prompt has the repository as `owner/name`. A pull request is stale when it is open and its last update is `days` days old or more.
1. Call the GitHub API one time in your shell. Put the repository in the URL:
`curl -sS -o pulls.json -w '%{http_code}\n' "https://api.github.com/repos/<owner>/<name>/pulls?state=open&sort=updated&direction=asc&per_page=50"`
2. If the status is not `200`, stop. Print the file, and report the status and the message from GitHub. Do not call the API again, because GitHub allows only a small number of calls without a sign-in.
3. Get the date of today with `date -u +%F`.
4. Read `pulls.json` with `jq` or `python3`. For each pull request, calculate the number of full days from `updated_at` to today.
5. Keep the pull requests where that number is `days` or more.
Write the digest in this form:
- One sentence: the repository, the number of stale pull requests, and the value of `days`.
- A table with the oldest update first: the number as a link to `html_url`, the title, the author, the date of the last update, and the days with no update. Mark a draft with "(draft)" after the title.
- If no pull request is stale, write only the sentence.
The API call returns a maximum of 50 open pull requests. If the file has 50, say that the digest can be incomplete.
Only read. Do not comment on, close or change a pull request.
Replace the content of agent.yaml with this, and commit:
apiVersion: agents.autoheal.ai/v1
name: Stale PR Digest
icon: clock-countdown
description: >-
Lists the open pull requests in one public GitHub repository that have had
no update for some days. Give it the repository as owner/name.
instructions: ./instructions.md
inputs:
prompt:
description: The repository, as owner/name.
days:
type: integer
description: A pull request is stale after this number of days with no update.
default: 14
model:
name: claude-haiku-5-5
max_tokens: 4096
limits:
model_requests: 10
timeout: 5m
system_tools: operation_type == "read"
integration_tools: "false"
The agent needs no Integration Connection. GitHub lets a client that does not sign in make only a small number of API calls in one hour, counted by IP address. For this reason, the instructions make one call and stop on an error. integration_tools: "false" gives the agent no integration tools, so it cannot write to an outside system with a tool.
Step 2: Run the agent one time
On the agent's Overview tab, type autohealai/astronomy-shop-template as the prompt. Set days to 0, so that each open pull request counts. Click Start run.
When the run ends, open the Summary. Check that the digest has a table with pull request #1, "fix(recommendation): set a timeout on product catalog calls". You can use any public repository with open pull requests.
Step 3: Create a cron trigger
Go to Agent Studio → Triggers, click New trigger, and select On a cron schedule. The editor opens a template that runs at 09:00 UTC from Monday to Friday. Replace its content with this definition:
apiVersion: triggers.autoheal.ai/v1
name: Weekly stale PR digest
cron:
expression: "0 9 * * MON"
timezone: Europe/London
run:
agent: agents:stale-pr-digest
with:
prompt: autohealai/astronomy-shop-template
days: 14
limits:
max_con: 1
| Part | What it does |
|---|---|
cron.expression | Five fields: minute, hour, day of month, month and day of week. 0 9 * * MON is 09:00 each Monday. |
cron.timezone | The time zone of the expression, as an IANA name such as UTC, Europe/London or Asia/Kolkata. It is necessary. |
with | The agent's inputs. A schedule has no event, so the values are usually fixed text. |
limits.max_con | The maximum number of runs of this trigger at the same time. |
Click Preview. The Schedule preview panel shows the Next runs in the trigger's time zone. Check that the first time is the next Monday at 09:00. Click Save.
Step 4: Run the schedule now
You do not have to wait until Monday. Open the trigger and click Edit. In the Schedule preview panel, click Trigger a live run, and then Trigger live run. The agent runs as if the time is now. A live run does not change the next times of the schedule.
Open the trigger's History tab. Check that it has one firing with the status Dispatched, and open its run. The digest is in the run's Summary.
Step 5: Run the agent one time at a set time
Click New trigger → Once, at a set time. Replace the content with this definition. Change at to a time five minutes from now, with your UTC offset:
apiVersion: triggers.autoheal.ai/v1
name: Stale PR digest once
once:
at: "2026-12-01T09:00:00+05:30"
run:
agent: agents:stale-pr-digest
with:
prompt: autohealai/astronomy-shop-template
days: 0
once.at is a date and time with its UTC offset, for example +05:30 or Z for UTC. A time without an offset is an error.
Click Save. On the trigger's Overview tab, Planned run shows Upcoming. After the time, refresh the page. Check that Planned run shows Open its run, and that the run's Summary lists pull request #1.
Step 6: Pause the schedule
Open Weekly stale PR digest and click Disable. A disabled trigger does not run on its schedule. Later, Autoheal does not run the times that passed while the trigger was off. Click Enable to start the schedule again.
Delete the once trigger after its run. Open it, click More actions → Delete trigger.
What to know
- The schedule starts the agent from the branch in
run.branch, or from the default branch. Each run uses the latest commit of that branch. To keep a schedule on one version, setrun.committo a commit SHA in quotes, for examplecommit: "50efd53". You cannot setbranchandcommittogether. See Keeping a trigger on a known-good version. - In the expression, a day of month and a day of week must both match.
0 9 1 * MONruns only on a 1st of the month that is a Monday. This is different from most cron programs. - The expression accepts numbers, names (
MON,JAN),*, ranges, steps (*/15) and lists. It does not accept a seconds field,@dailyor other shortcuts,L,Wor#. - The scheduler follows daylight saving time in
cron.timezone. A local time that the clocks skip does not run. A local time that occurs two times runs two times. - If the scheduler starts a time more than 60 seconds late, it skips that time. The only
missed_run_policyisskip. - When a run of the schedule has not started yet, Autoheal skips the next time with the reason "Previous attempt still pending".
limits.max_conandlimits.rate_per_minapply to schedules also. A time over a limit does not wait. Its firing shows Skipped with the reason, for example "At its concurrency limit".withcan read the time of the firing:${{ event.data.local_time }}(in the trigger's time zone),${{ event.data.scheduled_for }}(UTC) and, for cron,${{ event.data.timezone }}.event.typeisschedule.tick.- The schema has a
checkfield withrun.when, to run code first and start the agent only on a condition. Code checks are not available yet. Autoheal refuses a definition withcheck. - To post the digest to Slack, give the agent the
slack_send_messagetool:integration_tools: name == "slack_send_message". Then tell it in its instructions to send the digest to one channel by channel ID. The project needs a Slack Integration Connection. Each run of the schedule then posts a message, so test without the tool first.
From the CLI
autoheal agents push agents/stale-pr-digest -m "Add Stale PR Digest"
autoheal run stale-pr-digest "autohealai/astronomy-shop-template" --arg days=0 --wait
echo '{"type": "schedule.tick", "data": {}}' > tick.json
autoheal triggers dry-run -f weekly.yaml --event tick.json
autoheal triggers create -f weekly.yaml
autoheal triggers fire weekly-stale-pr-digest --event tick.json
autoheal triggers runs weekly-stale-pr-digest
autoheal triggers disable weekly-stale-pr-digest
autoheal triggers enable weekly-stale-pr-digest
autoheal triggers delete stale-pr-digest-once --yes
dry-run and fire need an event file for every trigger. For a schedule, the file only names the type schedule.tick. The schedule ignores its data. The trigger's id is its name in lowercase, with dashes for other characters. triggers runs lists each firing with its status: dispatched, skipped or failed, and the agent run that it started.
See Which agent to run and Limits in the Trigger reference.