cleandataengineering.aiAgent Harness, drawn simply
You are here: End to end › Core loop › When it stops

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.

12 tripsstep_budget_exhausted60 secondsdeadline_reached$0.50cost_ceiling_reached4,096 tokens outoutput_length_reached8 calls a trip, 24 a turntool_call_budget_exhaustedsame call 3 timesoscillation_detectedRohan leftcaller_gone4 retries a turnmodel_unavailableMost of these end with: "... let me pass you to a colleague."
The big text in each box is the limit; the small text is the reason recorded when it 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

Goes inthe run state at each step
What happensEvery limit is checked at a fixed point in the step, and every stop goes through one of four constructors in ends.py, which set the termination reason on both the trace and the span.
Comes outEnded: a typed result and the reason it stopped
CALL STACK · START TO FINISHGOES IN → COMES OUT1Open the source: agent_harness/loop/__init__.py:95run(...) # for step in range(budgets.max_steps)agent_harness/loop/__init__.py:95in: max_stepsout: STEP_BUDGET_EXHAUSTED once the range runs out2Open the source: agent_harness/loop/__init__.py:203_Run.step(step)agent_harness/loop/__init__.py:203in: step numberout: Ended or None3Open the source: agent_harness/loop/__init__.py:233_Run._out_of_time()agent_harness/loop/__init__.py:233in: now - started vs max_turn_secondsout: DEADLINE_REACHED or None4Open the source: agent_harness/loop/__init__.py:241_Run._caller_gone()agent_harness/loop/__init__.py:241in: the gone() probeout: True -> CALLER_GONE with CALLER_LEFT5Open the source: agent_harness/cost/__init__.py:121Meter.exceeded # property, checked in stepagent_harness/cost/__init__.py:121in: spend vs ceilingout: True -> COST_CEILING_REACHED6Open the source: agent_harness/loop/__init__.py:332_Run._plan(calls, step)agent_harness/loop/__init__.py:332in: the planned callsout: a plan, or a stop7Open the source: agent_harness/loop/plan.py:82over_fan_out(len(calls), len(trace.tool_calls), bud…agent_harness/loop/plan.py:82in: calls asked now and so farout: 'per_step'/'per_turn' -> TOOL_CALL_BUDGET_EXHAUSTED8Open the source: agent_harness/loop/plan.py:72signature(call.name, call.arguments)agent_harness/loop/plan.py:72in: one tool callout: (name, sorted JSON arguments)9Open the source: agent_harness/loop/plan.py:77circling(trace.signature_counts(), made, threshold)agent_harness/loop/plan.py:77in: signature counts and threshold 3out: True -> OSCILLATION_DETECTED, IN_CIRCLES10Open the source: agent_harness/loop/__init__.py:404_Run._stop(reason, message, rule_id, why)agent_harness/loop/__init__.py:404in: a TerminationReason and the replyout: Ended via stopped()11Open the source: agent_harness/loop/ends.py:77stopped(span, trace, reason, message, rule_id, why)agent_harness/loop/ends.py:77in: reason, messageout: Refused if REFUSED, else Completed(termination)12Open the source: agent_harness/loop/ends.py:71completed(span, trace, text)agent_harness/loop/ends.py:71in: the model's final textout: Completed, GOAL_REACHED13Open the source: agent_harness/loop/ends.py:130failed(span, trace, customer_message, detail, terminati…agent_harness/loop/ends.py:130in: a model/tool/transcript failureout: Failed (model_unavailable or unrecoverable)14Open the source: agent_harness/loop/ends.py:104handed_on(span, trace, raised)agent_harness/loop/ends.py:104in: ApprovalRequested or ActionDeclinedout: NeedsApproval, or Failed DECLINED
Read top to bottom: each box is one function call, indented under the function that called it; the dark box is where it starts. Click a box to open its source file.
Dashed boxes are protocols (the ports) or enums; grey boxes are data models; white boxes are classes with behaviour. A dashed arrow means "implements". Click a class to open its source.

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 object
class 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 name
class 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 apart

Tech choices (what we chose, Azure and open-source options): L13 · Cost accounting