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

Agent Harness Tutorial · End to end · Zoom level 2

Reading the answer

The model's reply arrives as loose parts: some text, some requests to call tools. One function, the "typed boundary", turns those parts into our own strict types. After this point no code ever handles raw model output.

Model responsetext parts + tool-call partsThe typed boundaryturn parts into our own typesOpen: Tool requestsTool requestswants_tools = truezoom in ›plan, check, runOpen: Words onlyWords onlya candidate answerzoom in ›check it, then leaveBrokenbad JSON, or nothingend the turnOpen: Cut offCut offstop reason = lengthzoom in ›never sent on
Only the first two carry on. Broken and cut-off answers end the turn rather than risk sending nonsense.

Tool requests. Each one becomes ToolCall(id, name, arguments). The arguments must be a JSON object; anything else is "broken". Whether the arguments fit the tool is checked later, at the tool gate, so the model can be told what was wrong and try again.

Words only. This is a candidate answer, not the answer. If Rohan asked two things and the reply covers only one, the model is sent back once with "Also raised and not yet dealt with: ...". Then the post-model check reads it.

Broken. Malformed output is not retried, because asking again at temperature 0 tends to give the same broken output. The turn ends with "I am having trouble answering right now."

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

Goes inPydantic AI's parsed provider response
What happensfrom_response turns the provider's parts into tool calls and text, refusing unreadable arguments or an empty answer, and the loop then branches on stop reason and whether tools were asked for.
Comes outa step outcome: stop, answer, or act
CALL STACK · START TO FINISHGOES IN → COMES OUT1Open the source: agent_harness/llm/pydantic_ai.py:232PydanticAIClient.complete(request)agent_harness/llm/pydantic_ai.py:232in: a ModelRequestout: a ModelResponse2Open the source: agent_harness/llm/pydantic_ai.py:179failure_of(exc) # UnexpectedModelBehavioragent_harness/llm/pydantic_ai.py:179in: a provider-side parse errorout: ModelMalformed3Open the source: agent_harness/llm/pydantic_ai.py:133from_response(raw)agent_harness/llm/pydantic_ai.py:133in: pa.ModelResponse partsout: ModelResponse or ModelMalformed4ToolCallPart.args_as_dict(raise_if_invalid=True)library: pydantic_ai.messagesin: a tool call's raw argumentsout: a dict, or ValueError -> ModelMalformed5Open the source: agent_harness/contracts/model.py:22ToolCall(id=, name=, arguments=)agent_harness/contracts/model.py:22in: tool_call_id, tool_name, argsout: a typed ToolCall6Open the source: agent_harness/contracts/model.py:158ModelMalformed(reason, raw=)agent_harness/contracts/model.py:158in: no text and no tool callout: a typed failure, never retried7Open the source: agent_harness/contracts/model.py:92ModelResponse(text=, tool_calls=, usage=, model=, stop_…agent_harness/contracts/model.py:92in: text, calls, usage, finish_reasonout: a typed ModelResponse8Open the source: agent_harness/loop/__init__.py:244_Run._ask # except ModelMalformedagent_harness/loop/__init__.py:244in: ModelMalformedout: trace.malformed += 1; failed(TROUBLE)9Open the source: agent_harness/loop/ends.py:130failed(span, trace, TROUBLE, exc.reason)agent_harness/loop/ends.py:130in: the reasonout: Failed (unrecoverable_error)10Open the source: agent_harness/loop/__init__.py:203_Run.step # stop_reason == 'length'agent_harness/loop/__init__.py:203in: a clipped responseout: _stop(OUTPUT_LENGTH_REACHED, PASS_ON)11Open the source: agent_harness/contracts/model.py:106ModelResponse.wants_tools # propertyagent_harness/contracts/model.py:106in: tool_callsout: True if any tool call12Open the source: agent_harness/loop/__init__.py:303_Run._answer(response) # no toolsagent_harness/loop/__init__.py:303in: final textout: completed / refused, or sent back once13Open the source: agent_harness/loop/__init__.py:332_Run._plan(response.tool_calls, step) # toolsagent_harness/loop/__init__.py:332in: the ToolCallsout: keyed plan, or a stop
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.

def from_response(response: pa.ModelResponse) -> ModelResponse:
    """The typed boundary (AHC-0001), on Pydantic AI's parsed response. The same
    two outcomes as `_from_wire`: a response, or `ModelMalformed` for tool
    arguments that are not a JSON object and for a paid-for answer with neither
    text nor a call (F-031)."""
    calls: list[ToolCall] = []
    for part in response.parts:
        if not isinstance(part, pa.ToolCallPart):
            continue
        try:
            arguments = part.args_as_dict(raise_if_invalid=True)
        except (ValueError, AssertionError) as exc:
            raise ModelMalformed(
                f"tool call {part.tool_name!r} has unreadable arguments: {exc}",
                raw=str(part.args),
            ) from exc
        calls.append(ToolCall(id=part.tool_call_id, name=part.tool_name, arguments=arguments))
    text = "".join(p.content for p in response.parts if isinstance(p, pa.TextPart))
    usage = response.usage
    if not text.strip() and not calls:
        raise ModelMalformed(
            "the model returned neither text nor a tool call after "
            f"{usage.output_tokens} output tokens"
            + (
                " — the output budget was spent before an answer began"
                if response.finish_reason == "length"
                else ""
            ),
            raw=text,
        )
    # The provider's own word for why it stopped, where it gave one, so the loop
    # reads `length` and `tool_calls` as it does from the other client.
    details = response.provider_details or {}
    return ModelResponse(

Tech choices (what we chose, Azure and open-source options): L6 · I/O contracts