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.
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.
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?
| Option | From | Verdict | Who owns the loop | Any model | Can tests reach every step | Lock-in | Observability | Best for |
|---|---|---|---|---|---|---|---|---|
| Plain Python (hand-written) | ours | chosen | us | yes | yes | none | our OTel spans | assured, transactional agents |
| Pydantic AI Agent | open source | model layer; A1–A3 | framework; we can step it | yes | yes if we step the loop | low: open source, any cloud | OTel built in | typed, testable Python agents |
| LangGraph | open source | workflow-shaped only | framework runs our graph | yes | yes, node by node | medium: graph model, LangSmith | full only with LangSmith | workflow agents with approvals |
| Claude Agent SDK | vendor | internal agents only | the SDK | Claude only | partly: the loop is hidden | high: Claude-only | partial traces | coding, ops, research agents |
| Anthropic tool runner (thin helper) | vendor | small Claude agents | us, with hooks | Claude only | yes: the steps are ours | medium: Claude-only | our OTel spans | small Claude-only agents |
| Microsoft Agent Framework | open source | .NET teams only | framework | yes | trajectory checks re-proved | medium: framework model | OTel, Azure-native | .NET or Azure-first teams |
| Foundry Agent Service (prompt agent) | Azure | rejected | Azure | Foundry models | no: loop and retries hidden | high: Azure-only service | Foundry tracing | low-code agents, not assured ones |
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/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: intTech choices (what we chose, Azure and open-source options): L4 · Control loop · PS · Performance & scalability