Escalation Ladders: When Payment Agents Must Hand Off to Humans
Design escalation ladders for autonomous payment agents — thresholds, guardrails and pausable approvals that force a human handoff, carry full context, and resume safely.
Published on • November 16, 2026
AI Assistant

Give an agent a payment API and it will eventually try to move the wrong amount of money, at the wrong time, for the wrong reason — confidently. The question that separates a demo from a production payment system is not “will it make a mistake?” but “what happens the moment the numbers look wrong?”
Most teams answer with a binary switch: full autonomy or full stop. Wrong shape. Real payment operations are a ladder: cheap deterministic checks first, then model-assisted pattern checks, then stop and ask a human, then escalate to a specialist who can reverse or dispute. Each rung narrows the blast radius and increases the context handed upward.
In this post, you will learn how to design and implement an escalation ladder for a payment agent using the OpenAI Agents SDK (Python) — specifically its human-in-the-loop approval flow, guardrails, and handoffs. You will build deterministic thresholds, wire them into needs_approval rules, serialize a paused run with RunState, carry full context into a human review UI, resume after approval, and get idempotency right so a resumed run never double-charges.
Prerequisites
- Python 3.10+ and
pip install openai-agents pydantic, plus anOPENAI_API_KEY. - A Stripe test-mode account if you want a real processor; a stub function works for everything below.
- Working async Python and passing familiarity with the OpenAI Agents SDK — this assumes you know what an
AgentandRunnerare.
Why a Ladder, Not a Switch
A single “ask a human” flag fails both ways: set the threshold low and reviewers rubber-stamp an expensive no-op; set it high and the agent acts alone until the incident. A ladder fixes this by staging cost — each rung is cheaper than the one above it, and produces evidence for the next.
| Rung | Trigger | Cost | Outcome |
|---|---|---|---|
| 0 | Under soft ceiling, known pattern | none | auto-approve in code |
| 1 | Over soft ceiling, velocity, prior declines | one function call | policy reason recorded |
| 2 | Unusual narrative or low confidence | small model call | guardrail tripwire |
| 3 | Any flagged money movement | human | needs_approval interruption |
| 4 | Rejected or investigation-worthy | human + specialist | handoff to dispute agent |
The critical design rule: rungs 0 and 1 are pure code. Never ask a model whether $49.99 is under your $100 ceiling. Deterministic checks are free, auditable, and instant — spend the model’s budget only where judgment is actually required.
Step 1: Deterministic Thresholds
Start with a policy module that has zero model dependencies. It returns None (keep climbing) or the rung and reason a rule fired:
# escalation/policy.py
from dataclasses import dataclass
SOFT_CEILING_CENTS = 100_000 # $100 — auto-approve band
HARD_CEILING_CENTS = 500_000 # $500 — human must see it
VELOCITY_WINDOW_MINUTES = 30
VELOCITY_MAX_ATTEMPTS = 5
@dataclass(frozen=True)
class PaymentIntent:
amount_cents: int
currency: str
customer_id: str
merchant_risk_band: str
prior_declines: int
def first_rung(intent: PaymentIntent, recent_attempts: int) -> tuple[int, str] | None:
"""Return (rung, reason) when a deterministic rule fires, else None."""
if intent.amount_cents > HARD_CEILING_CENTS:
return 3, f"amount {intent.amount_cents} exceeds hard ceiling"
if intent.prior_declines >= 2:
return 3, f"customer has {intent.prior_declines} prior declines"
if recent_attempts >= VELOCITY_MAX_ATTEMPTS:
return 3, f"{recent_attempts} attempts in {VELOCITY_WINDOW_MINUTES}m"
if intent.amount_cents > SOFT_CEILING_CENTS:
return 1, f"amount {intent.amount_cents} exceeds soft ceiling"
return None
Why this shape: a (rung, reason) pair lets the reason travel all the way into the review UI. Auditors do not want “the agent decided”; they want “amount 750000 exceeds hard ceiling”. Keep the file dependency-free so it unit-tests without an API key.
Step 2: Guardrails for the Judgment Rungs
Rungs 1–2 are where the model earns its keep, and the SDK’s guardrails are the right primitive: an input guardrail runs a function over the agent’s input and trips an exception when tripwire_triggered is true. Pick blocking mode (run_in_parallel=False) over the parallel default — lose a few milliseconds rather than start an expensive run that will be cancelled.
# escalation/guardrails.py
from pydantic import BaseModel
from agents import (
Agent, GuardrailFunctionOutput, InputGuardrailTripwireTriggered,
RunContextWrapper, Runner, TResponseInputItem,
)
from agents.decorators import input_guardrail
class PatternVerdict(BaseModel):
unusual: bool
confidence: float
reasoning: str
pattern_agent = Agent(
name="Pattern check",
instructions=(
"Flag unusual payment requests: new payee, round amounts near a "
"limit, geographic mismatch, urgency language. Report confidence 0-1."
),
output_type=PatternVerdict,
)
@input_guardrail
async def unusual_pattern_guardrail(
ctx: RunContextWrapper, agent: Agent, input: str | list[TResponseInputItem]
) -> GuardrailFunctionOutput:
result = await Runner.run(pattern_agent, input, context=ctx.context)
verdict: PatternVerdict = result.final_output
return GuardrailFunctionOutput(
output_info=verdict,
tripwire_triggered=verdict.unusual or verdict.confidence < 0.55,
)
Attach it with input_guardrails=[unusual_pattern_guardrail] and catch InputGuardrailTripwireTriggered to route the request up the ladder instead of back to the user. output_info is the evidence the reviewer will read, and low confidence counts as a trigger — “I’m 40% sure” is already a handoff.
One workflow boundary from the docs matters: input guardrails run on the first agent, output guardrails on the final one, and tool guardrails on every guarded tool invocation — where a per-call block on money movement belongs.
Step 3: Pausing the Run for Human Approval
The core mechanism is needs_approval on a tool: True always requires approval, or an async callable that decides per call — it receives the run context, parsed parameters, and tool call ID, so the ladder evaluates at call time on real arguments.
# escalation/payment_agent.py
from agents import Agent, Runner
from agents.decorators import tool
from escalation.policy import PaymentIntent, first_rung
async def needs_human(ctx, params, call_id) -> bool:
"""Rung 3: any payment the ladder flags must stop here."""
intent = PaymentIntent(**params["intent"])
rung = first_rung(intent, recent_attempts=params.get("recent_attempts", 0))
return rung is not None and rung[0] >= 3
@tool(needs_approval=needs_human)
async def charge_card(intent: dict, recent_attempts: int = 0) -> str:
# In production: stripe.PaymentIntent.create(..., idempotency_key=...)
return f"ch_pending_{intent['amount_cents']}"
payment_agent = Agent(
name="Payment agent",
instructions=(
"Call charge_card only after the user confirms the amount and payee. "
"If approval is requested, wait."
),
tools=[charge_card],
input_guardrails=[unusual_pattern_guardrail],
)
Two details worth internalizing. Callable approval rules fail closed: malformed, missing, or non-object arguments are never evaluated — the call requires manual approval, which is exactly right for money. And the interruption surface is run-wide, so a tool reached via handoff or nested Agent.as_tool() pauses the outer run: no specialist can dodge the ladder.
async def run_with_ladder(prompt: str):
result = await Runner.run(payment_agent, prompt)
if result.interruptions:
return result.to_state() # persist and hand off to the review queue
return result.final_output
Carrying Context into the Review UI
A paused run is worthless if the reviewer sees only charge_card. result.to_state() produces a RunState holding pending tool calls, arguments, approval decisions, usage, and your application context. The SDK’s guidance for browser or mobile approval interfaces is worth following literally:
- Keep the complete snapshot in server-side storage —
RunState.from_json()authenticates neither the snapshot nor the submitter. - Send the reviewer only what they are authorized to see, plus opaque decision IDs.
- Treat tool names and arguments as untrusted display content and escape them when rendering HTML — an invoice memo must not become XSS in your review console.
- On arrival: authenticate the reviewer, authorize them against the stored run, validate submitted IDs against pending items you own (
state.get_interruptions()), thenstate.approve(...)/state.reject(...)those server-owned items — under an atomic claim, so two reviewers cannot resume the same snapshot twice.
Assemble the review packet once (include the run’s trace URL):
def build_review_packet(state, rung_reasons: list[str]) -> dict:
items = state.get_interruptions()
return {
"decision_ids": [i.call_id for i in items],
"actions": [
{"tool": i.name, "arguments": i.arguments, "agent": i.agent_name}
for i in items
],
"ladder_reasons": rung_reasons, # from policy.first_rung + guardrail output_info
"model_evidence": [i.arguments for i in items],
}
Resuming After Approval
Resuming is deliberately boring: reload the state, decide, run again with the original top-level agent.
async def resolve(state_json: str, decisions: dict[str, bool]) -> str:
state = await RunState.from_json(payment_agent, json.loads(state_json))
for interruption in state.get_interruptions():
if decisions[interruption.call_id]:
state.approve(interruption, always_approve=False)
else:
state.reject(
interruption,
rejection_message="Payment rejected by reviewer: " + reasons[interruption.call_id],
)
result = await Runner.run(payment_agent, state)
return result.final_output
Use the per-call rejection_message instead of the SDK’s generic text — the model, and eventually the customer, needs to know why. RunConfig.tool_error_formatter sets run-wide wording; a per-call override wins. Streaming runs drain stream_events() first, then follow the same to_state() / resume path, and not every approval must be resolved in one pass. Avoid always_approve=True unless you have read the sticky-decision scope rules: approvals persist across runs, and for shell/file tools they are shared by tool type and name, not by agent.
The Rule Approval Cannot Save You From
The docs are blunt: approval permits a tool call to execute; it does not guarantee exactly-once execution. If the process dies after Stripe charged the card but before you stored the updated run state, resuming from the older snapshot runs the tool again — your agent just double-charged a customer during a review.
The fix is destination-enforced idempotency:
import uuid
@tool(needs_approval=needs_human)
async def charge_card(intent: dict, run_id: str) -> str:
return await stripe_client.create_payment_intent(
amount=intent["amount_cents"],
currency=intent["currency"],
idempotency_key=f"{run_id}:{intent['amount_cents']}:{intent['payee_id']}",
)
Generate the run_id once per logical action, reuse the same key across retries, and respect the processor’s retention window. If destination-enforced idempotency is unavailable, reconcile with the processor before retrying — a missing lookup result is not proof a retry is safe. Unknown outcome means record it as unknown and stop automatic replay. This is the rung below the ladder: the floor that catches you when the process itself fails.
Putting It All Together
A single request now travels a full ladder:
first_rung()runs in pure code — over the hard ceiling? reason recorded, straight to rung 3.- Otherwise the blocking input guardrail pattern-checks before the agent spends a token;
unusualor low confidence trips the wire. - The agent calls
charge_card;needs_humanre-evaluates the ladder on the actual arguments and fails closed on anything malformed. - The run pauses,
to_state()serializes it, and a review packet (actions, ladder reasons, model evidence, trace URL) lands in the queue. - A reviewer authenticates and approves; the server resumes the original agent from its own snapshot under an atomic claim, carrying the same idempotency key.
Output looks like:
{
"decision_ids": ["call_9f2"],
"actions": [{"tool": "charge_card", "arguments": {"amount_cents": 750000}, "agent": "Payment agent"}],
"ladder_reasons": ["amount 750000 exceeds hard ceiling"],
"trace": "https://ui.opencode.dev/project/.../trace/payment-run-314"
}
Reviewer approves → one idempotent Stripe call, agent continues.
Conclusion and Next Steps
You built a five-rung escalation ladder: deterministic thresholds, a guardrail for judgment calls, a callable needs_approval gate on the money tool, a context-rich review packet backed by server-owned RunState, a resume path with human-readable rejection reasons, and destination-enforced idempotency underneath. Swap in a refund or a wire transfer and the ladder still holds.
Homework for the next iteration:
- Add tiered reviewers: rung 3 to on-call, rung 4 to a risk owner — different
needs_approvalcallables, different queues. - Turn ladder reasons into metrics. If 80% of approvals are soft-ceiling hits, your ceiling is miscalibrated.
- Write a chaos test: kill the process between tool execution and state persistence, then prove the idempotency key holds.
- Add an output guardrail so the final customer-facing summary cannot promise what the reviewer rejected.
Escalation is not a failure of autonomy. It is what makes autonomy survivable.