Run an AI agent on a schedule, or when something happens

On a schedule

Start from an agent you already have (see build your own AI agent). Say when, in words:

{
  "worker": "todo-triager",
  "project": "tally",
  "name": "weekly-todo-triage",
  "brief": "Triage the TODO and FIXME comments in this repository. If there are none, say so in one line.",
  "schedule": { "kind": "cron", "cron": "0 9 * * 1", "timezone": "Europe/Berlin" }
}

To test it we used {"kind": "interval", "interval_seconds": 60} instead, the shortest Swarm allows. Runs started every minute; the one we read cost $0.019. By then the repository's TODO and FIXME had been fixed, and the run said so in one line:

There are no TODO or FIXME comments in this repository.

Handy cron lines: 0 8 * * * every morning at 8, 30 18 * * 1-5 weekdays at 18:30, 0 6 1 * * the first of the month. Every run shows in swarm_list_runs with its status and cost.

When something happens: a webhook

For "whenever CI fails" or "when a form comes in", a workflow with a trigger starts one of your agents with what happened. We pointed it at our coding agent:

{
  "name": "fix-failed-ci",
  "project": "tally",
  "on": {
    "event": { "source": "webhook", "id": "id" },
    "start": { "worker": "tally-maintainer",
               "brief": "CI reported a failure: {{event.text}}. Find the cause in this repository and fix it. Done when ./test.sh prints ok." }
  },
  "steps": []
}

"id": "id" names the field that identifies each event, so the same event never runs twice; {{event.text}} is filled from the event's text field. Saving returns a signing key, once. Your sender signs the exact body with HMAC-SHA256 and posts it to the workflow on Swarm's own address (no public listener is opened; reach it over your private network or a tunnel):

BODY='{"id":"ci-run-4521","text":"test.sh failed on main at the latest commit: FAIL: counts for a.txt"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$SWARM_TRIGGER_KEY" | awk '{print $NF}')
curl -s -X POST "$SWARM_API_URL/v3/workflows/$WORKFLOW_ID/events" \
  -H 'Content-Type: application/json' -H "X-Swarm-Trigger-Signature: sha256=$SIG" -d "$BODY"

To test it we broke a test on purpose (expecting 15 characters where there are 14), committed it, and sent that event. Swarm answered {"ok":true} and started the coding agent at once. Its report, excerpted:

### Cause of Failure
The latest commit on main ("test: expect 15 chars (deliberately wrong)") changed the expected
character count in test.sh for $tmp/a.txt from 14 to 15. [...] The CLI correctly output 14.

### Solution
- Reverted the regex pattern in test.sh back to expect 14 characters.
- CLI behavior did not change, so no changes to README.md or tally.sh were required.

One commit, one file, on its own branch, waiting for review: $0.11. Add a reviewer step and a deliver step, and fixes like this can merge themselves once they pass.

Other ways to start an agent

• Watch a feed: "source": "pull" with an HTTPS url and every_seconds (30 or more) starts the agent for each new item. The first poll only records what is there.
• From your own code: the SDK's workers.trigger with a token that can start that one worker and nothing else.
• Alerts: failed runs raise a signal you can send to your phone, Slack or email.