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

Agent Harness Tutorial · End to end · Zoom level 2

Hand-off to a person

Sometimes the right answer is a person. The router hands off at once for injuries or when Rohan asks for a human; the after-loop rules hand off when a conversation is going badly. Either way, a DBOS workflow holds the hand-off until someone picks it up.

Open: A reasonA reasoninjury, "a person please",10+ turns...zoom in ›escalation.waitQUEUED, ref E-…A handlerresolves itRESOLVEDno one in 30 minutesEXPIREDRohan writes again while QUEUED → "a colleague has this"Rohan writes again after EXPIRED → "nobody has picked up E-…, so I am back with you"
A conversation can be handed off at most twice.

While a hand-off is queued, the front door answers every new message with "a colleague has this" and the model is not called. That stops the agent and a person both answering at once.

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

Goes inA message the router decides must go to a person
What happensAn escalation record is written by a durable DBOS workflow that waits for a colleague's resolution or its own expiry, and the next turn checks it before doing anything else
Comes outAn Escalated reply now; the conversation handed back once resolved
CALL STACK · START TO FINISHGOES IN → COMES OUT1Open the source: claims_fnol/router/__init__.py:249route(text, *, rules)claims_fnol/router/__init__.py:249in: the customer's messageout: Escalate(reason, rule_id, tier=1)2Open the source: claims_fnol/entrypoint/__init__.py:261Agent._dispatch(decision, conversation, identity, run_id, gone)claims_fnol/entrypoint/__init__.py:261in: the Escalate decisionout: Escalated; recording() keeps its ticket id3Open the source: agent_harness/entrypoint/handoff.py:156HandoffDesk.raise_requested(decision, conversation, identit…agent_harness/entrypoint/handoff.py:156in: decision and conversation factsout: Escalated, or Completed if capped4Open the source: agent_harness/escalation/dbos.py:135DBOSEscalations.raise_for(*, conversation_id, run_id, .…agent_harness/escalation/dbos.py:135in: ids, reason, rule, facts.as_handoff()out: the recorded Escalation5Open the source: agent_harness/escalation/dbos.py:61_wait(raised)agent_harness/escalation/dbos.py:61in: a Raise, started by box.startout: the closed Escalation (DBOS workflow)6Open the source: agent_harness/escalation/dbos.py:45_publish(escalation)agent_harness/escalation/dbos.py:45in: the escalation as it standsout: step 'escalation.record', then the event7Open the source: agent_harness/state/dbos.py:117next_ballot(topic, within_s)agent_harness/state/dbos.py:117in: time left before expires_atout: a Ballot, or None (lapse on timeout)8Open the source: agent_harness/reviewer/__init__.py:152close(request, escalation_id, resolution, who)agent_harness/reviewer/__init__.py:152in: POST /ops/escalations/{id}/resolveout: Closed, or 404 / 4099Open the source: agent_harness/escalation/dbos.py:198DBOSEscalationDesk.resolve(escalation_id, *, outcome, by, .…agent_harness/escalation/dbos.py:198in: outcome, handler, noteout: the closed Escalation10Open the source: agent_harness/state/dbos.py:134deliver(workflow_id, topic, decision, *, wait_s)agent_harness/state/dbos.py:134in: a Resolution in a Ballotout: the workflow's Answer11Open the source: agent_harness/escalation/dbos.py:105_resolved(escalation, decision, now)agent_harness/escalation/dbos.py:105in: the accepted Resolutionout: Escalation with state RESOLVED12Open the source: claims_fnol/entrypoint/__init__.py:234Agent._gates(conversation, identity, run_id)claims_fnol/entrypoint/__init__.py:234in: pending_escalation_id on the next turnout: a held result, or None to proceed13Open the source: agent_harness/entrypoint/handoff.py:113HandoffDesk.hold(conversation)agent_harness/entrypoint/handoff.py:113in: the conversationout: waiting reply, lapse reply, or None14Open the source: agent_harness/state/__init__.py:178Conversation.returned()agent_harness/state/__init__.py:178in: a conversation whose case is closedout: pending_escalation_id cleared
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.

@DBOS.workflow(name=WORKFLOW)
async def _wait(raised: Raise) -> Escalation:
    now = int(await box.now())
    escalation = Escalation(
        id=raised.id,
        conversation_id=raised.conversation_id,
        run_id=raised.run_id,
        customer_id=raised.customer_id,
        tier=raised.tier,
        context=raised.context,
        rule_id=raised.rule_id,
        rules_version=raised.rules_version,
        reason=raised.reason,
        state=EscalationState.QUEUED,
        created_at=now,
        expires_at=now + raised.ttl_s,
    )
    await _publish(escalation)
    accepted: box.Ballot | None = None
    while escalation.open:
        moment = await box.now()
        if moment >= escalation.expires_at:
            # The lapse, as a timer rather than as somebody remembering to sweep.
            escalation = escalation.model_copy(
                update={"state": EscalationState.EXPIRED, "resolved_at": int(moment)}
            )
            break
        ballot = await box.next_ballot(TOPIC, escalation.expires_at - moment)
        if ballot is None:
            continue
        why = _judge(escalation, ballot.decision, int(await box.now()))
        if why is not None:
            await box.reply(ballot, box.Answer(refused=why))
            continue