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

Agent Harness Tutorial · End to end · Zoom level 1

The core loop

The loop is the heart of the harness. It is surprisingly small: about 400 lines of plain Python, no framework. On each trip it asks the model one question. If the model wants tools, the harness runs them and goes round again. If the model answers in words, the loop ends.

Goes inRohan's message and the earlier conversation
What happensUp to 12 trips of: build context, check, ask the model, run any tools it asks for
Comes outA candidate reply, or a clear reason why we stopped
Go clockwise from the top left. The ring repeats once for every round of tool calls. Grey boxes are checks; the dark box is the model.

Why a loop? Rohan asks "what is the status of my claim?" without a number. The model can't answer yet. On trip 1 it asks for the tool list_claims. The harness runs it and puts the result into the context. On trip 2 the model has what it needs and answers in words. Two trips, two model calls, one tool call.

The model only ever asks. It never runs a tool itself. It writes "please call list_claims", and the harness decides whether that is allowed, runs it, and hands back the result. That one fact is what makes every check possible.

Before the first trip, the harness fetches the list of tools Rohan is allowed to use. If the claims system can't be reached, the turn ends right there with "I cannot reach the system", and no money is spent on the model.

The real numbers for "what is the status of my claim?"2 trips · 2 model calls (652 then 1,535 tokens in) · 1 tool call (list_claims, 51 ms) · 7,076 ms · $0.00058 · 38 spans in the trace.

Want every detail? The long version is in the Series: the agent loop, step by step.

Compared: Who owns the control loop?

Plain Python (…ourschosenPydantic AI Ag…open sourcemodel layer; A1–A3LangGraphopen sourceworkflow-shaped onlyClaude Agent S…vendorinternal agents onlyAnthropic tool…vendorsmall Claude agentsMicrosoft Agen…open source.NET teams onlyFoundry Agent …Azurerejected
Dark: what we chose. Crossed and dashed: rejected or not for us. From the Series.
OptionFromVerdictWho owns the loopAny modelCan tests reach every stepLock-inObservabilityBest for
Plain Python (hand-written)ourschosenusyesyesnoneour OTel spansassured, transactional agents
Pydantic AI Agentopen sourcemodel layer; A1–A3framework; we can step ityesyes if we step the looplow: open source, any cloudOTel built intyped, testable Python agents
LangGraphopen sourceworkflow-shaped onlyframework runs our graphyesyes, node by nodemedium: graph model, LangSmithfull only with LangSmithworkflow agents with approvals
Claude Agent SDKvendorinternal agents onlythe SDKClaude onlypartly: the loop is hiddenhigh: Claude-onlypartial tracescoding, ops, research agents
Anthropic tool runner (thin helper)vendorsmall Claude agentsus, with hooksClaude onlyyes: the steps are oursmedium: Claude-onlyour OTel spanssmall Claude-only agents
Microsoft Agent Frameworkopen source.NET teams onlyframeworkyestrajectory checks re-provedmedium: framework modelOTel, Azure-native.NET or Azure-first teams
Foundry Agent Service (prompt agent)AzurerejectedAzureFoundry modelsno: loop and retries hiddenhigh: Azure-only serviceFoundry tracinglow-code agents, not assured ones
DecisionWe write the loop ourselves and use Pydantic AI only as the model layer, so budgets and checks sit at exact, testable positions. We would use LangGraph for workflow-shaped agents, Agent Framework for a .NET team, and full Pydantic AI for simple A1–A3 agents.

Code view: input, process, output, the call stack, the classes

Goes inan Agentic goal, identity, model client, tools and budgets
What happensThe loop opens the tool list, then on each step asks the model, adds up the cost, and either answers or plans and runs tools, until something ends it.
Comes outEnded: a TurnResult plus the Trace
CALL STACK · START TO FINISHGOES IN → COMES OUT1Open the source: agent_harness/loop/__init__.py:95run(goal, *, identity, llm, tools, system_prompt, budgets, ...)agent_harness/loop/__init__.py:95in: goal text, history, budgets, meterout: Ended = (TurnResult, Trace)2Open the source: agent_harness/resilience/__init__.py:89unit_retries(budgets.max_retries_per_unit)agent_harness/resilience/__init__.py:89in: the turn's retry allowanceout: a scope that shares one retry budget3Open the source: claims_fnol/entrypoint/reference.py:35Created.list_tools(identity) # -> GatedTools.list_toolsclaims_fnol/entrypoint/reference.py:35in: the customer's identityout: ToolRegistry (or ToolUnavailable -> failed)4Open the source: agent_harness/loop/freshness.py:310freshness.resumed(resumed, this)agent_harness/loop/freshness.py:310in: rows read on earlier turnsout: those rows read again into context5Open the source: agent_harness/loop/__init__.py:203_Run.step(step) # for step in range(max_steps)agent_harness/loop/__init__.py:203in: the step numberout: Ended, or None to take another step6Open the source: agent_harness/loop/__init__.py:233_Run._out_of_time()agent_harness/loop/__init__.py:233in: the clock and the disconnect probeout: Ended (deadline / caller gone) or None7Open the source: agent_harness/loop/__init__.py:244_Run._ask(step_span)agent_harness/loop/__init__.py:244in: messages, registry, budgetsout: ModelResponse, or Ended on failure8Open the source: agent_harness/loop/__init__.py:293_Run._account(response)agent_harness/loop/__init__.py:293in: response.usageout: trace.usage and spend_usd updated9Open the source: agent_harness/loop/__init__.py:303_Run._answer(response) # if not wants_toolsagent_harness/loop/__init__.py:303in: a final text responseout: completed / refused Ended, or None (sent back)10Open the source: agent_harness/loop/__init__.py:332_Run._plan(response.tool_calls, step)agent_harness/loop/__init__.py:332in: the model's tool callsout: list of (ToolCall, IdempotencyKey) or Ended11Open the source: agent_harness/loop/__init__.py:354_Run._act(planned)agent_harness/loop/__init__.py:354in: planned calls with keysout: None (results in context) or handed_on Ended12Open the source: agent_harness/loop/dispatch.py:31dispatch(tools, allowed, identity, local_tools, reg…agent_harness/loop/dispatch.py:31in: the allowed callsout: a list of ToolResult in order13Open the source: agent_harness/context/__init__.py:51ctx.tool_message(result, tool_call_id=call.id)agent_harness/context/__init__.py:51in: one ToolResultout: a fenced tool Message added to messages14Open the source: agent_harness/loop/ends.py:77stopped(run_span, trace, STEP_BUDGET_EXHAUSTED, PASS_ON)agent_harness/loop/ends.py:77in: no step ended the runout: Completed with a hand-on reply, plus Trace
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/loop/__init__.py:163The loop itself: one trip per step, at most 12
        for step in range(budgets.max_steps):
            ended = await this.step(step)
            if ended is not None:
                return ended
        return stopped(run_span, trace, TerminationReason.STEP_BUDGET_EXHAUSTED, PASS_ON)


@dataclass
class _Run:
    """One run's state, and the phases of a step as methods: each readable on its
    own, the state they share named once here rather than threaded through locals."""

    span: Span
    trace: Trace
    identity: Identity
    llm: LLMClient
    tools: ToolClient
    registry: ToolRegistry
    local_tools: dict[str, LocalTool]
    run_id: RunId
    system_prompt: str
    budgets: Budgets
    meter: Meter | None
    oscillation_threshold: int
    now: Callable[[], int]
    """The run's clock, injected like every other one here: a module that read
    the wall clock itself would be untestable about time, which is the whole
    subject of `fresh` (AHC L9, F-021)."""
    fresh: freshness.Freshness
    fan_out: int

Tech choices (what we chose, Azure and open-source options): L4 · Control loop · PS · Performance & scalability

Look inside