Loops: a goal, a check and a state
A loop is one conversation that works toward a goal. The agent sends the goal as a stop condition. proxium counts the calls of the conversation. A stop check reads the answer against the goal. proxium starts no worker: the agent takes every turn, and the check only reports the state.
1. Name the conversation
Send the header x-proxium-conversation with one stable id on every call of the task:
curl https://api.proxium.tech/v1/chat/completions \
-H "x-proxium-conversation: refactor-runner-week-42" \
-H "Content-Type: application/json" \
-d '{"model": "openai/gpt-5", "messages": [{"role": "user", "content": "Continue the refactor."}]}'
Without the header each call is a different conversation, and the counters of the loop do not add up.
2. State the goal
Set the stop condition of the conversation in one of four ways: the console, the API (PUT /memory/goal), the MCP tool proxium_set_stop_condition, or the header x-proxium-goal on a
call. The header holds one line, and each sentence of
it is an item. An agent that cannot call a tool, such as the worker of a desk loop, sets its
goal this way. Write the items that the work must show, one per line or one per sentence:
The runner starts no worker.
The check writes the goal state.
docs/LOOP.md names the stop modes.
A person approves a goal change
By default a person approves every change of the goal of a running agent. The change waits
with the state pending and does not replace the condition until that person approves it.
A project can allow an automatic change with the setting goal_approval = auto.
3. Read the state
proxium_read_goal_state (or GET /memory/goal?conversation=…) returns the condition, the
items that the check reads from it, the counters of the conversation and the state:
| State | Meaning |
|---|---|
met | The answer shows every item. The loop may end. |
not_met | At least one item is missing. The reason names it. |
unknown | No answer yet, or the judge could not read it. |
pending | A person must approve the goal change. |
4. Pick the judge
The project setting check_mode picks who reads the answer:
| Mode | Who judges | Model calls |
|---|---|---|
check | The check reads the answer text against the items | none |
check+model | A model of another family than the worker | one per check |
check+session | A model in a new session that does not read the worker chat | one per check |
A mode that names a judge needs a vendor of another family than the worker. Without that
vendor the check answers unknown with the reason no judge hop answered.
5. The ceilings
A loop setting holds the ceilings of one conversation: max_iterations, max_cost_millicents
and stall_limit, for the project, the app, the key or one conversation. Over a ceiling with
cap_mode = refuse, the call answers 429 with the code loop_capped. With cap_mode =
alert the call passes and proxium raises an alert.
Read and set the settings with the MCP tools proxium_read_loop and proxium_set_loop, or on
the Loops screen of the console.
The loop is on by default
The loop is on when a project sets nothing: proxium counts every conversation, and no ceiling
fires, because every ceiling of that project is 0. A project that does not want the loop writes
one row with enabled = false, and every app and key of the project inherits it. The header
x-proxium-loop: off turns the loop off for one call.
6. For an agent
Install the skill proxium-loop:
curl -fsSL https://proxium.tech/skills/install.sh | sh
The skill tells the agent the four steps of the loop. The steps are: name the conversation, state the goal, read the state before it stops, and save the open items. See Memory for agents.
7. The findings of a loop that climbs nothing
A loop can spend its runs and reach nothing. The job axon_loop_climb reads the runs of the last
7 days on the server. It writes a finding when the same cause comes again (#579). It runs every
6 hours, and it names one lease for the whole fleet. It reads the window that ended at the start
of the day in UTC. A finding is a row of axon_loop_findings: it names the project, the
sub-kind, the window, and the runs that it counted. The server sends the event of the loop as the
trigger of the job. The timer runs it if the event is lost.
A finding has one of these sub-kinds:
| Sub-kind | When it comes | Times in the window |
|---|---|---|
stall | Runs stop on the same call that changed nothing | 2 |
stop_refused | The same typed line of Done when fails in a run | 2 |
judge_not_reached | The same line that no command can check fails, and the finding names the vendor of the judge | 2 |
cost_over_run | A run costs more than max_cost_millicents | 1 |
iterations_over_run | A run takes more iterations than max_iterations | 1 |
One occurrence writes no finding. A line of Done when carries its type in its first word. The
words test, suite, deploy, land, release, rollout, prod, doc, reference,
readme, check, verify, lint and ci also give the type. A line of type judge needs a
person or a different judge, because no command can check it.
A finding of a stall or of a line is a decision. The job proposes a routing document. It moves the
first hop of the first chain of two hops or more to the end of that chain. The finding keeps the
version of the document that it built the change from. Approve the change, and the routes go up by
one version. The call refuses a document that moved since (stale), and the finding waits for a
new window.
Two MCP tools answer, and the Improve screen carries the same two buttons:
proxium_approve_improvementapplies the proposed document. The version list of the project holds both versions, andproxium_rollback_routing_documentwith the version of the finding brings the routes back in one call.proxium_refuse_improvementcloses the finding with no change of the routes, when the repeated step is the work that the loop must do. The window of the finding does not raise it again.
A project with the loop off (enabled = false) gets no finding. A project that sets nothing
inherits the setting of its app, its key or its account.