cleandataengineering.aiAgent Harness, drawn simply
You are here: End to end › DBOS › Payout flow

Agent Harness Tutorial · End to end · Zoom level 2

The payout flow

The real flow, from a test on Azure: Rohan asks to release ₹25,001 on claim CLM-010004. The automatic limit is ₹25,000, so a person must approve it.

RohanHarnessDBOS workflowAsha's deskClaims system"release the payment for CLM-010004"request_payout starts approval.waitassess: read the claim, ₹25,001 > ₹25,000state WAITING"Nothing has been paid yet. A handler will review it." (202)Asha clicks Approve: a ballotcarry out: re-read the claim (still the same?)issue_payout, with the original keychecks the approval row, then paysDONE (200 to Asha)next message: "has it been paid?""Yes, it was paid."· · · minutes or hours later · · ·
Read top to bottom. Each lane is one party; each arrow is one message. The gap in the middle is the wait.

₹25,000 or less is approved automatically by the rule policy:automatic-limit and paid in the same turn. Only bigger payouts wait.

Nothing is paid until the decision is written down. Every state change upserts the approvals row first. The claims system then checks that row itself before paying: approved, not expired, same arguments, and decided by someone other than the customer.

If the claim changed while waiting, the workflow marks the approval STALE and starts a fresh one, so Asha never approves something she didn't see.

An approval is valid for 24 hours. Asha's desk refreshes every 5 seconds.

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

Goes inThe model's request_payout call for one claim
What happensA durable DBOS workflow assesses the payout, records it, waits for a person's ballot if it is over the limit, then pays under an elevated identity that the claims system checks again
Comes outAn approval record that ends done, refused, expired, stale or failed
CALL STACK · START TO FINISHGOES IN → COMES OUT1Open the source: claims_fnol/approvals/payout.py:116payout_tool(...).handle(arguments)claims_fnol/approvals/payout.py:116in: claim id from the model (a local tool)out: a result, or PayoutRequested raised2Open the source: agent_harness/approvals/dbos.py:274DBOSApprovals.request(*, action, args, identity, idempotenc…agent_harness/approvals/dbos.py:274in: action, claim id, identity, keyout: the Approval once assessed3Open the source: agent_harness/approvals/dbos.py:92_wait(ask)agent_harness/approvals/dbos.py:92in: an Ask, started by box.start (state/dbos.py:172)out: the final Approval (DBOS workflow)4Open the source: claims_fnol/approvals/payout.py:175PayoutWork.assess(ask)claims_fnol/approvals/payout.py:175in: the Ask, via box.step('approval.assess')out: Assessment: amount and why it needs a person5Open the source: agent_harness/approvals/dbos.py:238_record(approval)agent_harness/approvals/dbos.py:238in: each new approval stateout: step 'approval.record' writes our record6Open the source: agent_harness/approvals/dbos.py:155_Run._wait()agent_harness/approvals/dbos.py:155in: the waiting approval and its deadlineout: returns once decided or expired7Open the source: agent_harness/state/dbos.py:117next_ballot(topic, within_s)agent_harness/state/dbos.py:117in: TOPIC 'approval.decision'out: a Ballot from DBOS.recv_async, or None8Open the source: agent_harness/reviewer/approvals.py:139decide(request, approval_id, decision, who)agent_harness/reviewer/approvals.py:139in: POST /ops/approvals/{id}/decideout: Decided, or 404 / 4099Open the source: agent_harness/approvals/dbos.py:321DBOSApprovalDesk.decide(approval_id, *, granted, by, ...)agent_harness/approvals/dbos.py:321in: granted flag and the handlerout: the record after the workflow acted10Open the source: agent_harness/state/dbos.py:134deliver(workflow_id, topic, decision, *, wait_s)agent_harness/state/dbos.py:134in: a Decision in a Ballotout: the workflow's Answer (refused or record)11Open the source: agent_harness/approvals/dbos.py:196_Run._act()agent_harness/approvals/dbos.py:196in: the decided approvalout: settled Approval; step 'approval.carry_out'12Open the source: claims_fnol/approvals/payout.py:198PayoutWork.carry_out(approval)claims_fnol/approvals/payout.py:198in: granted approval, worker identityout: CarriedOut: ok, declined or stale13Open the source: agent_harness/approvals/workflow.py:163carry_out(approval, base, tools, *, policy, …agent_harness/approvals/workflow.py:163in: approval and the worker's identityout: ToolResult of tools.call('issue_payout')14Open the source: claims_system/server.py:187covers(approval, *, holder, claim, key, …claims_system/server.py:187in: the approval record, via _Gate.payableout: None, or why it does not cover this payout
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.

claims_fnol/approvals/payout.py:116request_payout: start the approval, or pay within the limit
    async def handle(arguments: dict[str, object]) -> ToolResult:
        claim_id = arguments.get("id")
        if not isinstance(claim_id, str) or not claim_id:
            return _error(REQUEST_PAYOUT, "a claim reference is required")
        approval = await approvals.request(
            action=PAYOUT_ACTION,
            args={"claim_id": claim_id},
            identity=identity,
            idempotency_key=idempotency_key,
            conversation_id=conversation_id,
        )
        if approval.state is ApprovalState.WAITING:
            raise PayoutRequested(approval)
        if approval.state is ApprovalState.DONE:
            # Named by its row, as every claims-system answer is: this answer is
            # the latest word on the claim's status (AOAS `consistency`, F-21).
            done = {
                "id": claim_id,
                "status": "paid",
                "approval_id": approval.id,
                "claim_id": claim_id,
                "amount": str(approval.args.get("amount", "")),
            }
            return ToolResult(name=PAYOUT_ACTION, text=approval.result or "", structured=done)
        if approval.declined:
            raise ActionDeclined(DECLINED_REPLY.format(claim_id=claim_id), approval.result or "")
        return _error(REQUEST_PAYOUT, approval.result or f"the payout is {approval.state.value}")