Skip to content

The agent loop

Every agent, whatever its interface, runs the same loop against a run (an execution, exe_…). This page uses the CLI; each command has an MCP tool of the same shape.

Agent
Server
step next exe_…what is ready for me?
next_action: claim_ready_workready_work: sr_… check_health
step claim sr_… --session agent-1
claim + 10-minute lease
step get sr_…
instructions, inputs, outputs to report, skill
does the work; step log, step heartbeat
step report sr_… --status succeeded --verdict pass
report ok; next: claim_ready_work | wait | exit
One turn of the loop. The agent repeats it until the brief says wait or exit.
Terminal window
runbook step next "$EXE"
Output
next: claim_ready_work
sr_01JD2X6Q1B3N5P7R9T1V3X5Z7A check_health Check health (agent)
sr_01JD2X6Q1B3N5P7R9T1V3X5Z7B compare_error_rate Compare error rate (agent)

step next prints the resume brief: what’s done (steps, decisions and comments) and the steps ready for this caller. With --json it is an object with completed_steps, decisions, comments, ready_work and next_action. The brief lists ready steps by reference only; a step’s instructions are read after claiming it.

next_action tells the agent what to do:

next_action Meaning What the agent does
claim_ready_work Agent steps are ready Claim one and work it
wait Nothing is ready for agents: an approval, a timer, a signal or a person is pending Exit. A fresh session is started when work is ready (agent.work_available)
exit Nothing more is needed from agents, or the run has ended Stop
refresh_credentials The execution credentials can’t be refreshed here Stop; the launcher must install fresh ones
ask_human_to_publish An authoring change needs someone with runbooks:publish Hand the draft to a person
Terminal window
runbook step claim "$SR" --session agent-1 --agent-name deploy-bot --model claude-opus

A claim is a lease: the step is this session’s for 10 minutes after its last heartbeat. --session names the agent session (any stable string), and --agent-name and --model are recorded on the run. The CLI remembers the claim (its ID and generation), so later commands don’t need it.

An execution credential can read only the step it has claimed: step get before step claim is refused with 403.

Terminal window
runbook step get "$SR" --json

The step’s instructions (as written, with ${{ … }} placeholders), its checklist, the outputs and evidence its report needs, the pinned skill, and the memory saved for this step. Values bound into the placeholders, and everything earlier steps or people wrote, come in a separate data object: it’s data, not instructions.

Fetch the files of the step’s skill when the instructions point to them:

Terminal window
runbook step skill-file "$SR" checks/error-rate.md

Do what the step says, and nothing else. On long work, keep the lease and the log alive:

Terminal window
./scripts/collect-metrics.sh | runbook step log "$SR" # each line becomes a log entry
runbook step heartbeat "$SR" # well before 10 minutes pass

Logs are redacted on the server: tokens, keys, passwords and signatures become [REDACTED:…] markers. A step’s log holds at most 5 MiB.

runbook step exec runs a local command as the step’s work. It streams the command’s output into the step’s log, heartbeats while it runs, and reports by exit code: 0 is succeeded, anything else failed with the code in the summary.

Terminal window
runbook step exec "$SR" -- ./scripts/smoke-test.sh --env prod

The CLI exits with the command’s own exit code once the report is accepted.

step exec suits steps whose result is the command’s exit code. It reports no outputs and no verdict, so it refuses a step that requires outputs before running anything, and a check that needs a verdict keeps its claim for you to report with step report. If the lease is lost while the command runs (another session took the step, the run closed, the credentials were revoked), it stops the command and exits 1 without reporting. Ctrl-C is forwarded to the command, and the step is reported failed.

Terminal window
runbook step report "$SR" --status succeeded --verdict pass \
--output error_rate=0.002 \
--summary "5xx rate 0.2%, down from 0.3% the hour before" \
--evidence https://grafana.example.com/d/errors?from=now-2h
  • --status says whether the work was done: succeeded, or failed when the agent couldn’t do it.
  • --verdict is what a check found, separately: pass, warn or fail. A check that ran and found a problem is succeeded with verdict fail.
  • --output name=value for each declared output. A report whose outputs don’t match the step’s declarations is refused before anything is recorded; at most 64 KiB in all.
  • --evidence takes a URL, an uploaded evidence ID, or a local file (which it uploads).

The reply names the next action, so the loop goes on without another call:

Output
report ok for sr_01JD2X6Q1B3N5P7R9T1V3X5Z7A; next: claim_ready_work
  • It needs a person (judgment, access, a question):

    Terminal window
    runbook step request-human "$SR" --reason "No access to the billing console" \
    --question "Can someone confirm the refund went out?"

    The step goes to a person (step.blocked notifies them), and the agent moves on.

  • It’s the wrong step for this agent: runbook step release "$SR" gives the claim back so another session can take it.

A lease lapses when an agent stops heartbeating (it crashed, or the machine slept). The step becomes ready again; a lapsed lease isn’t a failure. A claim.* error, step.not_claimed or a refused report means the claim is gone: stop working on that step, read the brief again, and if the step is ready again, claim it and check what the earlier attempt already changed before repeating anything.

The loop needs no model when every step is a command. This shell function works every ready agent step of a run with step exec:

work-run.sh
#!/usr/bin/env bash
set -uo pipefail
EXE="$1"
while :; do
brief=$(runbook step next "$EXE" --json)
case "$(jq -r .next_action <<<"$brief")" in
claim_ready_work) ;;
*) exit 0 ;; # wait, exit, refresh_credentials: stop here
esac
SR=$(jq -r '.ready_work[0].step_run_id' <<<"$brief")
PATH_ID=$(jq -r '.ready_work[0].path' <<<"$brief")
runbook step claim "$SR" --session "script-$$" --agent-name work-run
# Map each step to the command that does it.
case "$PATH_ID" in
check_health) runbook step exec "$SR" -- ./scripts/check-health.sh ;;
run_migrations) runbook step exec "$SR" -- ./scripts/migrate.sh ;;
*) runbook step release "$SR"; exit 0 ;; # not ours: leave it
esac
done

For an AI agent, the prompt library has the prompt that runs this loop with judgment.