Agent Harness Tutorial · Architecture
The harness: one block between the user and the model
A customer never talks to the model directly. Everything in between is the agent harness, and the concerns are what's inside it.
The demo is the model. The system is the harness. The harness decides what the model sees, which tools may touch the transaction systems, what it remembers, when a person must approve, what it must not do, what gets recorded, and how a change ships safely.
Click the dark block to open it: that is the end-to-end map, with every concern in the order one message meets it.
Sign-in, and one call to get a claim
Two things in the picture above deserve a closer look: how Rohan proves who he is (Microsoft Entra ID), and how that proof travels all the way to the claims system, so the harness can never fetch more than Rohan himself may see.
| Step | Why it is done this way |
|---|---|
| PKCE, state and a nonce on sign-in | Stops a stolen code or a forged callback from signing someone in |
| Access token only in the page's memory | It travels in the URL fragment, which browsers never send to a server, so it is in no access log |
| Refresh token encrypted in agent_state.sessions | It never reaches the browser; the cookie only names the login. Unused for 12 hours, it is deleted |
| Customer id from the token, never from the message | "I am PH-2002" in a message changes nothing |
| On-behalf-of token for the claims system | The claims system sees Rohan, not a powerful service account, and checks again on its side |
| Rows filtered by the holder in the token | "Not yours" looks exactly like "doesn't exist" (flow 14) |
More: the front door, how the token is checked, the claims system checking again, flow 14: someone else's claim.
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
How it is done: the real code
Cut from the live repositories each time the site is built, so it always matches what runs.
claims_fnol_app/signin_flow.py:8The sign-in routes (from the module's own description) GET /signin to Entra's /authorize: state, PKCE (S256) and a nonce,
sealed into a 10-minute cookie only /signin/* is sent
GET /signin/callback the state checked, the code redeemed with the verifier,
the tokens checked (`EntraLogin.signed_in`), the
refresh token stored encrypted, and the browser sent on
POST /signin/refresh a fresh access token from the stored refresh token
POST /signin/logout the stored login deleted, the cookie cleared, and onagent_harness/identity/entra.py:104Checking Rohan's token on every messagedef 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,
)agent_harness/identity/entra.py:179The on-behalf-of exchange: a token for the claims system, still Rohan's async def for_far_end(self, identity: Identity) -> str:
if not identity.token:
raise InvalidSession("no session to exchange")
now = float(self._clock())
cached = self._cache.get(identity.token)
if cached is not None and cached[1] - 30 > now:
return cached[0]
body = await self._post(identity.token)
token = body.get("access_token")
if not isinstance(token, str) or not token:
raise EntraMalformed("on-behalf-of answered 200 with no access_token")
self._cache = {k: v for k, v in self._cache.items() if v[1] > now}
self._cache[identity.token] = (token, now + float(body.get("expires_in", 60)))
return tokenagent_harness/identity/entra.py:194The form sent to Entra def form(self, assertion: str) -> dict[str, str]:
"""What is posted: public so a test can read it without a server."""
fields = {
"grant_type": OBO_GRANT,
"requested_token_use": "on_behalf_of",
"assertion": assertion,
"scope": self._scope,
"client_id": self._client_id,
}
if self._assertion is not None:
fields["client_assertion_type"] = ASSERTION_TYPE
fields["client_assertion"] = self._assertion()
else:
fields["client_secret"] = str(self._secret)
return fieldsclaims_system/server.py:222The claims system checking the token again@dataclass(frozen=True)
class _Gate:
"""Who is asking, and whether money may move: this system's checks."""
store: Store
authorise: Authorise
approvals: ApprovalRecordReader | None
clock: Callable[[], float]
limits: Settings
async def record(self, meta: Mapping[str, object]) -> ApprovalRecord | None:
named = meta.get(APPROVAL_META)
if self.approvals is None or not isinstance(named, str):
return None
return await self.approvals.approval(named)
async def holder(
self, operation: str, arguments: dict[str, Any], ctx: Context | None
) -> str | None:
meta = _meta(ctx)
call = Call(operation, SCOPES.get(operation, READ_SCOPE), _bearer(ctx, meta), meta)
try:
caller = await self.authorise(call)
except CallRefused as exc:
raise NotAuthorised(f"{operation} refused: {exc}") from None
if caller.holder is not None or not _workflow(caller):
return caller.holder
return _on_approval(await self.record(meta), operation, arguments)
async def payable(self, claim_id: str, who: str, ctx: Context | None) -> None:
"""The far end's own check on money moving (AHC-0057)."""
claim = await self.store.get_claim(who, claim_id)
if not claim.get("found"):
return # answered as unknown by the store, never as refused