Skip to content
ARC / Documentation
Agent index ↗Back to Arc ↗Buy Arc — $499

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

UseWhen the workEnds when
A taskis one tracked piece of work with an ownerits owner completes it
A runhas a finite objective, possibly across several seatsits Done-when is met and arc_complete_run succeeds
A loopis open-ended improvement or monitoring on one seatsomeone 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_id or agent_id, found with arc_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_cycles and read reported token usage with arc_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.

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

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

  1. Inspect current files and Arc state before acting. Do not blindly repeat an action whose result is uncertain.
  2. Do one bounded piece of work and leave evidence: a workspace change, an artifact, or a fitness verdict.
  3. Record a failed approach with arc_remember, tagged with the loop's run_id.
  4. Call finish with 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:

CauseWhat to do
It reached max_cyclesResume is refused. Raise max_cycles with a definition edit and resume, or restart.
Three finished cycles left no new evidenceReview 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 timesCheck the model connection. Retryable failures back off from 30 seconds up to 15 minutes first.
A cycle was interrupted, or its dispatch result is uncertainInspect the last action's effects before resuming; Arc does not replay it.
A cycle's wait was cancelledResume when ready.
A cycle ended unfinished for another reasonRead last_result, adjust, then resume.

Pause, resume or stop

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

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

json
{"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.