Agent Harness Tutorial · End to end · Zoom level 2
When the loop stops
A loop that can go round forever will, one day. So every turn has hard limits, and each limit has its own name, written to the trace, so we can count how often each one fires.
The good ending is goal_reached: the model answered in words and the checks passed. The other endings are refused (a check blocked it), awaiting_approval (a person must decide), and declined (the claims system said no).
Going round in circles is caught by a signature: the tool name plus its arguments, sorted. The third identical call ends the turn with "I am going round in circles...".
The money limit is checked only when the model wants more tools, so a turn that is about to answer is never cut off at the last step.
Want every detail? The long version is in the Series: budgets and limits.
Code view: input, process, output, the call stack, the classes
How it is done: the real code
Cut from the live repositories each time the site is built, so it always matches what runs.
agent_harness/config/__init__.py:13Every budget in one frozen objectclass Budgets(BaseModel):
"""Ceilings that can actually stop a call.
Two positions, deliberately. `max_output_tokens` is a per-call backstop at
P3; `max_steps` and `max_cost_usd` are per-task and enforced at P4, because
only the loop can see that fourteen calls are one runaway task rather than
fourteen tasks. AAC-0093 and AAC-0008 are different obligations for exactly
this reason.
"""
model_config = ConfigDict(frozen=True)
max_steps: int = 12
max_cost_usd: float = 0.50
max_output_tokens: int = 4096
max_tool_result_chars: int = 8000
"""Tool results are bounded before they enter context — AAC-0105."""
max_turn_seconds: int = 60
"""Wall clock for one turn (AHC-0096), checked before each step."""
max_tool_calls_per_step: int = 8
"""How many tool calls one step may plan (AHC-0097). A step budget counts
steps, so without this one step asking for fifty look-ups — or fifty
writes — spends one of the twelve and does fifty things."""
max_tool_calls_per_turn: int = 24
"""How many tool calls one turn may plan across all its steps (AHC-0097).
Reaching either bound stops the turn before the step's calls run, as
`tool_call_budget_exhausted` — never a silent cut to the first N (AHC-0059)."""
max_retries_per_unit: int = 4
"""AHC-0024: retries across the whole turn, every call's together (F-087)."""agent_harness/contracts/kinds.py:34Every way a turn can end, each with a nameclass TerminationReason(StrEnum):
"""Why the loop stopped. Never absent — AAC-0055 requires hard termination
under every condition, and an unexplained stop is indistinguishable from a
hang.
"""
GOAL_REACHED = "goal_reached"
STEP_BUDGET_EXHAUSTED = "step_budget_exhausted"
COST_CEILING_REACHED = "cost_ceiling_reached"
DEADLINE_REACHED = "deadline_reached"
"""Wall-clock ran out (AHC-0096). Its own value since generation run 1: it
was reported as a step stop, and the two call for different fixes."""
OUTPUT_LENGTH_REACHED = "output_length_reached"
"""The model stopped because its output budget ran out (AHC-0025), so what
it wrote is incomplete. Its own value since generation run 2: sending a
clipped answer as if it were whole is the failure it names."""
TOOL_CALL_BUDGET_EXHAUSTED = "tool_call_budget_exhausted"
"""A step planned more tool calls than one step may, or the turn's calls
would pass what one turn may (AHC-0097). The step's calls do not run: a
plan cut to its first N would be a partial result nobody marked (AHC-0025)."""
CALLER_GONE = "caller_gone"
"""The caller left — the connection closed — before the turn finished
(AHC-0096). Checked where the deadline is, so no further model or tool call
starts for a reply nobody will read. Not a give-up: nobody is waiting, so
nobody is paged."""
OSCILLATION_DETECTED = "oscillation_detected"
AWAITING_APPROVAL = "awaiting_approval"
AWAITING_HUMAN = "awaiting_human"
"""A person owns the conversation now.
Distinct from `AWAITING_APPROVAL`: an approval is a decision about one action
the agent proposed, and the agent resumes afterwards. This is the whole
conversation changing hands. Both are "not finished", which is why both
answer 202 rather than 200 — but a dashboard that could not tell them apartTech choices (what we chose, Azure and open-source options): L13 · Cost accounting