Skip to main content

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:

MARKDOWN
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:

YAML
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:

YAML
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
PartWhat it does
cron.expressionFive fields: minute, hour, day of month, month and day of week. 0 9 * * MON is 09:00 each Monday.
cron.timezoneThe time zone of the expression, as an IANA name such as UTC, Europe/London or Asia/Kolkata. It is necessary.
withThe agent's inputs. A schedule has no event, so the values are usually fixed text.
limits.max_conThe 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:

YAML
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, set run.commit to a commit SHA in quotes, for example commit: "50efd53". You cannot set branch and commit together. 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 * MON runs 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, @daily or other shortcuts, L, W or #.
  • 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_policy is skip.
  • When a run of the schedule has not started yet, Autoheal skips the next time with the reason "Previous attempt still pending".
  • limits.max_con and limits.rate_per_min apply to schedules also. A time over a limit does not wait. Its firing shows Skipped with the reason, for example "At its concurrency limit".
  • with can 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.type is schedule.tick.
  • The schema has a check field with run.when, to run code first and start the agent only on a condition. Code checks are not available yet. Autoheal refuses a definition with check.
  • To post the digest to Slack, give the agent the slack_send_message tool: 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​

BASH
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.