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

Agent Harness Tutorial · End to end · Zoom level 1

Front door

Before the harness thinks about what Rohan said, it makes sure of who he is and whether this exact message was already handled. None of this uses the model.

Goes inAn HTTP request with a token and an idempotency key
What happensSix quick checks, each able to stop the message
Comes outA trusted identity and a fresh ledger row, or an early answer
Read the requestat most 8 KiB, valid JSON1Check the tokensigned by Entra? for us? not expired?2Open: Load the conversationLoad the conversationnewest checkpoint, if it is hiszoom in ›3Kill switchis the agent switched on?4Open: Write a ledger rowWrite a ledger rowseen this message before?zoom in ›5Anything waiting?a payout or a person already on it?6stop: 413 too bigstop: 401 not signed instop: 404 not yoursstop: "paused" replystop: the stored answer, or 409stop: "a colleague has this"Open: On to the routerOn to the routerzoom in ›
Grey boxes are checks. Each arrow to the right is a way to stop early, with what Rohan gets back.

Who is asking comes only from the token. The browser sends an Entra ID token with every message. The harness checks its signature, that it was issued for this app, and that it has not expired. Rohan's customer id (PH-1001) is read from the token. If the message itself says "I am PH-2002", nobody listens.

A message sent twice is handled once. The browser makes up a fresh id for each message and sends it again if it has to retry. The harness writes a row called PH-1001:<that id> into the ledger before doing anything. A second copy finds the row and gets the first answer back, or a 409 if the first is still running. See doing a write exactly once.

Someone else's conversation looks like no conversation. If Rohan sends a conversation id that belongs to another customer, he gets 404, not 403, so he cannot even learn that it exists.

Want every detail? The long version is in the Series: sign-in, the token, and who may do what.

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

Goes inan HTTP POST /chat with a bearer token and JSON text
What happensThe edge checks the token, loads the conversation, asks the kill switch, takes the delivery claim, runs the gates and then calls the router.
Comes outa routing decision inside the turn, then a JSON reply
CALL STACK · START TO FINISHGOES IN → COMES OUT1Open the source: agent_harness/serve/__init__.py:203chat(request)agent_harness/serve/__init__.py:203in: HTTP request with Bearer tokenout: a Response (200/202/4xx/5xx)2Open the source: agent_harness/serve/__init__.py:147decode(request, verify=state.verify)agent_harness/serve/__init__.py:147in: raw body bytes and headersout: an Inbound, or BadRequest 400/401/403/4133Open the source: agent_harness/serve/__init__.py:121_customer(request, verify)agent_harness/serve/__init__.py:121in: the authorization headerout: the customer's Identity4Open the source: agent_harness/adapters/identity.py:128verify(token) # Entra adapter closureagent_harness/adapters/identity.py:128in: the bearer token stringout: a Principal5Open the source: agent_harness/identity/entra.py:104verify_entra(token, issuer=, role_scopes=, holde…agent_harness/identity/entra.py:104in: token, issuer, role map, customer claim nameout: Principal with sub, customer id, scopes6Open the source: agent_harness/identity/__init__.py:213Principal.as_customer()agent_harness/identity/__init__.py:213in: a verified Principalout: Identity, or NotACustomer (403)7Open the source: agent_harness/serve/__init__.py:234_conversation_for(state.store, inbound)agent_harness/serve/__init__.py:234in: store and the conversation id from the bodyout: Conversation, None, or _NotYours (404)8Open the source: agent_harness/state/__init__.py:235Conversation.decode(previous)agent_harness/state/__init__.py:235in: checkpoint bytes from store.latest()out: a Conversation9Open the source: agent_harness/serve/__init__.py:252_run_turn(agent, inbound, conversation, span, gone=)agent_harness/serve/__init__.py:252in: agent, inbound, conversation, disconnect probeout: JSONResponse with status from REPLY_STATUS10Open the source: agent_harness/entrypoint/switch.py:94Switched.handle(text, identity=, conversation=, ...)agent_harness/entrypoint/switch.py:94in: the turn's argumentsout: (TurnResult, Conversation), or paused Refused11Open the source: claims_fnol/entrypoint/__init__.py:141Agent.handle(text, identity=, conversation=, delive…claims_fnol/entrypoint/__init__.py:141in: text, identity, conversation, delivery idout: (TurnResult, Conversation)12Open the source: agent_harness/entrypoint/persist.py:58delivered(customer_id, conversation, run_id, del…agent_harness/entrypoint/persist.py:58in: customer id and the Idempotency-Keyout: a conversation and run id derived from the message13Open the source: agent_harness/requests/__init__.py:156req.once(self.deliveries, named, scope=Scope.DEL…agent_harness/requests/__init__.py:156in: ledger and the name 'customer:delivery'out: a Claim (or AlreadyAnswered / StillRunning)14Open the source: claims_fnol/entrypoint/__init__.py:178Agent._turn(text, identity, conversation, ru…claims_fnol/entrypoint/__init__.py:178in: the claimed turnout: (TurnResult, Conversation), persisted15Open the source: claims_fnol/entrypoint/__init__.py:234Agent._gates(conversation, identity, run…claims_fnol/entrypoint/__init__.py:234in: conversation with pending escalation/approval idsout: (held result or None, conversation)16Open the source: claims_fnol/router/__init__.py:249router.route(text, rules=self.rules)claims_fnol/router/__init__.py:249in: the customer's text and router rulesout: a Route: Direct, Agentic, Refuse or Escalate
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.
CLASS DIAGRAMOpen the source: agent_harness/serve/__init__.py:107«dataclass»Inboundtext: stridentity: Identityconversation_id: ConversationId | Nonedelivery_id: str | NoneOpen the source: agent_harness/identity/__init__.py:188«pydantic»Principalsubject: strcustomer_id: str | Nonescopes: frozenset[str]session: strtoken: strmay(scope) -> boolas_customer() -> IdentityOpen the source: agent_harness/entrypoint/__init__.py:28«protocol»TurnAgentstore: CheckpointStoreescalations: Escalations | Noneopening(identity) -> strhandle(text, *, identity, conversatio…Open the source: agent_harness/entrypoint/switch.py:71«dataclass»Switchedagent: TurnAgentsettings: Settingsreply: strhistory_chars: intenabled() -> boolhandle(...) -> tuple[TurnResult, Conv…_paused(...) -> tuple[TurnResult, Con…Open the source: claims_fnol/entrypoint/__init__.py:77«dataclass»Agentllm: LLMClienttools: ToolClientstore: CheckpointStoredeliveries: req.Requests | Nonerules: router.Ruleshandle(...) -> tuple[TurnResult, Conv…_turn(...)_gates(conversation, identity, run_id)_dispatch(decision, ...)_persist(run_id, conversation)Open the source: agent_harness/contracts/protocols.py:146«protocol»Requestsclaim(name, *, scope, ttl_s) -> Claimsettle(name, outcome) -> Noneabandon(name) -> NoneOpen the source: agent_harness/state/__init__.py:98«pydantic»Conversationconversation_id: ConversationIdcustomer_id: strmessages: tuple[Message, ...]pending_approval_id: str | Nonepending_escalation_id: str | Nonedecode(raw) -> Conversationwith_messages(*added)returned()recording(result)implementsimplementswrapscreatesusesreturns
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/identity/entra.py:104Checking the token: signature, issuer, audience, expiry
def verify_entra(
    token: str,
    *,
    issuer: Issuer,
    now: int | None = None,
    role_scopes: RoleScopes | None = None,
    holder_claim: str = CLAIM_CUSTOMER,
) -> Principal:
    """`identity.verify` for Entra's claims: the same signature check, issuer,
    audience and expiry (`decode`), the session named by `uti`, and an app role
    granting the scopes `role_scopes` gives it.

    `holder_claim` is where the customer id is read from. Entra writes a
    directory extension attribute as `extn.<name>` (claims-fnol-azure A2), not
    `customer_id`, so the overlay names it, and the far end reads the same name."""
    claims = decode(token, issuer=issuer, now=now, require=("uti",))
    party = claims.get("azp")
    return Principal(
        subject=str(claims["sub"]),
        customer_id=holder_of(claims.get(holder_claim)),
        scopes=frozenset(entra_scopes(claims, role_scopes)),
        session=str(claims["uti"]),
        party=party if isinstance(party, str) else None,
        token=token,
    )

Tech choices (what we chose, Azure and open-source options): L16 · Identity & authz