Skip to main content

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:

StateMeaning
metThe answer shows every item. The loop may end.
not_metAt least one item is missing. The reason names it.
unknownNo answer yet, or the judge could not read it.
pendingA person must approve the goal change.

4. Pick the judge​

The project setting check_mode picks who reads the answer:

ModeWho judgesModel calls
checkThe check reads the answer text against the itemsnone
check+modelA model of another family than the workerone per check
check+sessionA model in a new session that does not read the worker chatone 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-kindWhen it comesTimes in the window
stallRuns stop on the same call that changed nothing2
stop_refusedThe same typed line of Done when fails in a run2
judge_not_reachedThe same line that no command can check fails, and the finding names the vendor of the judge2
cost_over_runA run costs more than max_cost_millicents1
iterations_over_runA run takes more iterations than max_iterations1

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_improvement applies the proposed document. The version list of the project holds both versions, and proxium_rollback_routing_document with the version of the finding brings the routes back in one call.
  • proxium_refuse_improvement closes 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.