Agent capabilities
Loops: keep a goal moving
Give an Arc-managed agent an ongoing goal that Arc works through in repeated cycles, then read, steer, pause and stop it.
On this page
An Arc Loop is a persistent goal that one Arc-managed agent works through in repeated cycles in a Full Access room. Arc schedules each cycle, saves its result, and starts the next one after a delay until someone pauses or stops the loop or it reaches its cycle limit. Read this page before you create a loop, when you are the agent working a cycle, or when you need to change or stop one. Exact schemas are in the loop tool reference.
Choose a loop, a run or a task
| Use | When the work | Ends when |
|---|---|---|
| A task | is one tracked piece of work with an owner | its owner completes it |
| A run | has a finite objective, possibly across several seats | its Done-when is met and arc_complete_run succeeds |
| A loop | is open-ended improvement or monitoring on one seat | someone stops it, or it pauses at a limit |
A loop never completes on its own. When its goal is met, the worker says so and stops the loop, or the operator does.
Check what a loop needs
- Full Access. Creating, resuming, editing and restarting need a Full Access room. Pause and stop stay available after the room drops to Safe, within your room write permissions. If the room is Safe, ask the operator to switch it.
- A managed worker. The loop runs on an enabled Arc-managed seat: a local GGUF model, a self-hosted model server, or an API model. An external harness agent can create and control loops but cannot be the worker; it names a managed seat with
membership_idoragent_id, found witharc_list_seats. - A running daemon on an awake computer. A cycle that came due while the computer slept runs once when it wakes; missed intervals do not pile up.
- Bound the work. Loops take no spending limit. Set
max_cyclesand read reported token usage witharc_run_status.
Create a loop
The four loop tools form the progressive group loop. If they are not in your tool list, call arc_search_tools with the query loop.
arc_create_loop {
"title": "Improve onboarding",
"brief": "Verify and fix one onboarding step per cycle. Preserve unrelated work. Report when a clean setup check passes end to end.",
"interval_seconds": 60,
"max_cycles": 5
}Only brief is required (up to 20,000 characters). room_id defaults to your joined room and the worker defaults to your own managed seat. interval_seconds is the delay between cycles: default 30, range 1 to 86,400. An omitted max_cycles means unlimited cycles. With no prompt fields, the loop uses the operator's Loop cycle default. The first cycle is scheduled at once, and the result carries the loop's run_id.
Keep the cadence and limits the operator gave you. Never create a child or replacement loop to get around an existing loop's limits.
Check in on a timer
The Checks in every N minutes behaviour is a loop with no cycle limit. It runs its brief at once, then every interval_minutes (1 to 1,440, default 60); the brief is the preset's routine-check text unless you write your own. Unlike a goal loop, it keeps its timer through quiet cycles: cycles that leave no new evidence do not pause it. Add it from the agent's ⋯ menu → Add behaviour… → Checks in on a timer…, or with arc_set_behaviour, action add and preset_id checks_in. It is listed with the agent's other behaviours, where Pause, Resume and Stop control the loop; its goal and timing change only while it is paused. See Behaviours and coordination flows.
Use an editable prompt list
The loop editor lets the operator add complete plaintext prompts. arc_create_loop and arc_update_loop_instructions take the same list as cycle_prompts: 1 to 32 nonblank strings, each at most 20,000 characters, at most 200,000 characters in total. Text is preserved as written. shuffle_prompts defaults to false.
arc_create_loop {
"brief": "Improve onboarding and retain each check's evidence.",
"cycle_prompts": [
"Review one setup step and fix a verified defect.",
"Check one error message against the failed action it describes."
],
"shuffle_prompts": false,
"max_cycles": 6
}Each new cycle uses the next entry, then wraps around. Shuffle uses every entry once per pass in a shuffled order. Retries, waits and checkpoints keep the prompt already admitted for that cycle, even if the list is edited. An edited list applies to the next new cycle and begins a fresh pass; restarting the loop also begins a fresh pass.
cycle_instructions remains the first entry for single-prompt clients. Sending only it edits that first entry and keeps the others. If you send both fields, cycle_instructions must exactly match cycle_prompts[0]. Updating only shuffle_prompts keeps the list. Both prompt edits and Shuffle changes use expected_instructions_revision.
Work a cycle
Each cycle reaches the worker as a turn headed [Arc loop <run_id>, cycle <n>]. It contains the cycle instructions, the configured max_cycles, the goal and its boundaries, the last result, and up to three recent failed approaches. The system prompt also carries the Loop control prompt.
- Inspect current files and Arc state before acting. Do not blindly repeat an action whose result is uncertain.
- Do one bounded piece of work and leave evidence: a workspace change, an artifact, or a fitness verdict.
- Record a failed approach with
arc_remember, tagged with the loop'srun_id. - Call
finishwith a summary. Arc saves it as the loop's last result and schedules the next cycle.
Do not call arc_complete_run for a loop; Arc refuses it. Do not dispatch loop work with arc_run_seat: Arc admits only the loop's current scheduled cycle. wait ends your turn as waiting and keeps the current cycle open until the wait fires. A remind continuation runs inside the loop without starting a new cycle.
Read progress
arc_list_loops returns each loop's run_id, status (such as running, paused or stopped) and revision. Progress is in metadata.loop, including cycle, last_result, next_run_at, waiting_reason, resume_blocked_reason, failed_approaches, instructions_revision, cycle_prompts and shuffle_prompts. The response's defaults hold the current Loop cycle and Loop control text. For turns, events and tokens, call arc_run_status with the loop's run_id.
Know why a loop paused
Arc pauses a loop and sets waiting_reason when:
| Cause | What to do |
|---|---|
It reached max_cycles | Resume is refused. Raise max_cycles with a definition edit and resume, or restart. |
| Three finished cycles left no new evidence | Review the goal or approach before resuming. A workspace write, a fitness verdict, or an artifact other than a memory or session summary counts. A check-in on a timer does not pause for this. |
| A runtime or connection failure repeated five times | Check the model connection. Retryable failures back off from 30 seconds up to 15 minutes first. |
| A cycle was interrupted, or its dispatch result is uncertain | Inspect the last action's effects before resuming; Arc does not replay it. |
| A cycle's wait was cancelled | Resume when ready. |
| A cycle ended unfinished for another reason | Read last_result, adjust, then resume. |
Pause, resume or stop
arc_control_loop {"run_id": "<run_id>", "action": "pause"}The actions are pause, resume and stop. Pause keeps progress and limits and cancels the loop's running and queued work, including a cycle in progress, so record your result before you pause or stop from inside a cycle. Resume works only on a paused loop below its cycle limit, needs Full Access, and is refused while the seat is still running an action. Stop ends the loop for good; a stopped loop cannot resume, but you can edit or restart it.
Change the cycle instructions
Read instructions_revision from arc_list_loops, then:
arc_update_loop_instructions {
"run_id": "<run_id>",
"cycle_instructions": "Fix one failing onboarding check per cycle and record the check's output.",
"expected_instructions_revision": 2
}Replace 2 with the revision you read. New text applies to the next new cycle; a cycle already admitted keeps its selected prompt through retries and continuations. The edit never changes the goal, limits, progress or control rules, and it works on stopped loops without restarting them. A stale revision is refused: reload, merge, and retry.
The operator owns two global prompts in Settings > Arc instructions. Loop cycle is the default text for new loops and for a loop's Reset to default; existing loops keep their own. Loop control joins every cycle's system prompt from the next cycle on, including queued ones; a cycle underway keeps its wording. Read both in defaults. Change them only when the operator asks, through the built-in instructions routes with the ids arc-loop-cycle and arc-loop-control.
Edit or restart a loop over HTTP
Full definition edits and restarts have no MCP tool. Both need Full Access, the loop's current revision as expected_revision, and a paused or stopped loop.
{"expected_revision": 4, "max_cycles": 10, "interval_seconds": 120}Replace 4 with the revision you read and send the body to PATCH /v1/loops/<run_id>. It accepts title, brief, membership_id, interval_seconds, max_cycles, cycle_instructions, cycle_prompts and shuffle_prompts. Saving does not start work or reset counters, and a paused loop keeps its worker. POST /v1/loops/<run_id>/restart takes the same body and, once the old loop's work has settled, starts a new loop with a fresh cycle counter and prompt pass. restarted_from_run_id and restarted_as_run_id in metadata.loop link the two; each loop can be restarted once.
The MCP tools map to GET and POST /v1/rooms/{id}/loops (list and create, on the room routes page), POST /v1/loops/{id}/pause, /resume and /stop, and PATCH /v1/loops/{id}/instructions.