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

Agent Harness Tutorial · End to end · Zoom level 1

Router

The router is the first thing that reads Rohan's words. It is not a model; it is a list of rules. Its job is to send each message down the cheapest path that is still safe, so the expensive, slow, unpredictable model is used only when it is really needed.

Goes inThe message text
What happensRules check for a hand-off, then a refusal, then a simple read with one reference
Comes outOne of four paths: Escalate, Refuse, Direct or Agentic
Rohan's wordsOpen: RouterRouterregular-expression rulesabout 0 ms, no modelhow it decides ›Open: EscalateEscalatehand to a personzoom in ›e.g. injury, "a human please"Refusepolite no + what I can doe.g. "will it be approved?"Open: DirectDirectone read + a templatezoom in ›e.g. status of CLM-019002Open: AgenticAgenticthe loop with the modelzoom in ›e.g. everything else~350 ms~160 ms100–600 ms1.5–7 s
Left to right, the paths get slower and more flexible. Only the Agentic path uses the model.

Why rules first? A rule is instant, free and gives the same answer every time, so it can be tested completely. If the rules aren't sure, the message goes to the loop, which can cope with anything. The rule is: when in doubt, use the loop; never guess on the cheap path.

Rohan saysPathWhy
"What's the status of claim CLM-019002?"DirectOne read-only question, one claim number
"What is the status of my claim?"AgenticNo claim number, so it needs to look up his claims first
"Please release the payment for claim CLM-010004."AgenticIt is a write; writes never take the Direct path
"Will my claim be approved?"Refuse (R-COVERAGE)The assistant may never promise cover
"My passenger was injured"Escalate (injury-reported)A person must handle injuries

Want every detail? The long version is in the Series: the router, line by line.

Compared: What decides the route, and which model answers?

Rules (regex rout…ourschosenLocal classifier …open sourceplannedSmall LLM (gpt-5-…vendorplannedModelSelector (go…oursplannedAzure Model routerAzurerejectedfastText / Azure …vendorrejected
Dark: what we chose. Crossed and dashed: rejected or not for us. From the Series.
OptionFromVerdictDecidesWhenNetwork callSame input, same answerStatus
Rules (regex router)ourschosenroute: refuse, hand off, direct, loopevery turn, before any modelnoneyesruns today (layer 1)
Local classifier (Model2Vec + sklearn)open sourceplannedthe intent when rules are unsureevery message, about 1 msnone: a versioned fileyesTier 6; needs ~500 labels
Small LLM (gpt-5-nano labels)vendorplannedroute when classifier unsurerarelyone small callnot guaranteedTier 6
ModelSelector (golden set)oursplannedwhich model each job usesoffline, before each releaseoffline onlyyes: same cases, same verdictplanned: a CI job
Azure Model routerAzurerejectedwhich model answers a promptrun time, every callevery callnot guaranteednot used: model is Groq
fastText / Azure CLUvendorrejectedthe intentevery messageCLU: yesyesarchived; CLU retiring 2029
DecisionRules route every message today; a local classifier, then a small LLM only when unsure, are planned for Tier 6. Model choice is made offline by the ModelSelector on the golden set; Azure Model router is not used because its choice is not reproducible.

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

Goes inthe customer's message text
What happensFixed regex rules check for a handoff first, then a refusal, then exactly one intent with one reference; whatever is left goes to the loop.
Comes outone Route, then dispatch to the matching handler
CALL STACK · START TO FINISHGOES IN → COMES OUT1Open the source: claims_fnol/entrypoint/__init__.py:178Agent._turn(text, identity, conversation, run_id, gone)claims_fnol/entrypoint/__init__.py:178in: the customer's textout: the turn's result2Open the source: claims_fnol/router/__init__.py:249route(text, rules=self.rules)claims_fnol/router/__init__.py:249in: text and versioned Rulesout: a Route, recorded on the agent.route span3Open the source: agent_harness/telemetry/__init__.py:314tel.span('agent.route', ...)agent_harness/telemetry/__init__.py:314in: span name, route kind 'pending'out: an open span4Open the source: claims_fnol/router/__init__.py:260_decide(text, rules)claims_fnol/router/__init__.py:260in: text and rulesout: the first Route that matches5Open the source: agent_harness/contracts/results.py:66Escalate(reason=, rule_id=, tier=1)agent_harness/contracts/results.py:66in: an escalate pattern matched (injury, human)out: an Escalate route6Open the source: agent_harness/contracts/results.py:52Refuse(reason=, alternative=ALTERNATIVE, rule_id=)agent_harness/contracts/results.py:52in: a refuse pattern matched (R-COVERAGE etc.)out: a Refuse route7Open the source: claims_fnol/router/__init__.py:282intents_of(text, rules)claims_fnol/router/__init__.py:282in: text and the intent patternsout: every matching Intent, in rule order8Open the source: claims_fnol/contracts/reading.py:29references(text)claims_fnol/contracts/reading.py:29in: textout: the set of CLM-/POL- ids named9Open the source: agent_harness/contracts/results.py:34Direct(intent=, handler=DIRECT_HANDLERS[intent], ar…agent_harness/contracts/results.py:34in: one read-only intent and one matching idout: a Direct route10Open the source: agent_harness/contracts/results.py:43Agentic(goal=text.strip(), candidate_intents=matche…agent_harness/contracts/results.py:43in: zero, several or a write intentout: an Agentic route11Open the source: claims_fnol/router/__init__.py:288_reason_of(decision)claims_fnol/router/__init__.py:288in: the chosen Routeout: a reason string for the span12Open the source: claims_fnol/router/concerns.py:25router.concerns(text)claims_fnol/router/concerns.py:25in: textout: the concerns raised, written to facts13Open the source: claims_fnol/entrypoint/consent.py:40consent.granting(identity, conversation, text, rules)claims_fnol/entrypoint/consent.py:40in: identity, conversation, textout: identity with any consent the text grants14Open the source: claims_fnol/entrypoint/__init__.py:261Agent._dispatch(decision, conversation, identity, run_id, g…claims_fnol/entrypoint/__init__.py:261in: the Routeout: (result, landed, tried, looked)15Open the source: claims_fnol/router/__init__.py:300refusal_text(decision) # case Refuseclaims_fnol/router/__init__.py:300in: a Refuse routeout: the reply: reason plus what can be done16Open the source: agent_harness/entrypoint/handoff.py:156HandoffDesk.raise_requested(...) # case Escalateagent_harness/entrypoint/handoff.py:156in: Escalate, conversation, identity, run idout: an Escalated result (ticket)17Open the source: claims_fnol/entrypoint/direct.py:176direct.answer(...) / agent_loop.run(...) # Direct / Ag…claims_fnol/entrypoint/direct.py:176in: the Direct or Agentic routeout: a TurnResult (loop also returns a 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/contracts/results.py:34The four routes, as types
class Direct(_Frozen):
    """Unambiguous — a deterministic handler answers without the model."""

    kind: Literal["direct"] = "direct"
    intent: IntentName
    handler: str
    args: dict[str, object] = Field(default_factory=dict)


class Agentic(_Frozen):
    """Ambiguous, multi-intent, or unmodelled. The loop is the fallback, not
    the default: when the classifier is unsure, it routes here."""

    kind: Literal["agentic"] = "agentic"
    goal: str
    candidate_intents: tuple[IntentName, ...] = ()


class Refuse(_Frozen):
    """Out of scope. The refusal list in the functional spec is normative —
    "never promise what the system cannot deliver" is only testable against an
    explicit list of things it must not say."""

    kind: Literal["refuse"] = "refuse"
    reason: str
    alternative: str | None = None
    rule_id: str = ""
    """Which rule refused, not just why in prose — the AOAS `refuses` id. Same
    argument as `Escalate.rule_id`: *"which rule refuses most often, and is it
    right to"* cannot be asked of a sentence."""


class Escalate(_Frozen):
    """A human takes over. Triggered by P-ESCALATE, or asked for outright."""

Look inside