Last updated · Santosh Kumar Radha

How to add human approval steps to an AI agent workflow

Add durable human approval to an AI agent: pause, wait for a person for minutes or days, then resume. Patterns and the AgentField code to do it.

To add a human approval step to an AI agent, put the gate in the workflow code right before the action with consequences, persist the run's state, notify a reviewer, and resume the same run when they decide; in AgentField that is one call, await app.pause(...), which moves the execution to waiting, survives restarts, and resumes on a signed webhook. Never rely on a prompt that tells the model to ask first: the model can skip it, and the code cannot.

At a glance

ToolHow you pauseHow you resumeWhere the waiting state lives
AgentFieldapp.pause(approval_request_id=...) inside a reasonerHMAC-signed webhook to /api/v1/webhooks/approval-responseControl plane database
LangGraphinterrupt() inside a nodeInvoke again with the thread ID and Command(resume=...)Your checkpointer
TemporalWorkflow waits on a condition or durable timerSend a SignalTemporal service history
OpenAI Agents SDKMark a tool needs_approval=Truestate.approve(...) or state.reject(...), then run againRun state you serialize with to_json()
MastraSuspend an agent or workflowResume with the user's inputMastra storage

The pattern, whatever you use

  1. Decide what needs approval in code. Refunds, outbound email, deletes, payments: anything external, irreversible or costly. Low model confidence is a good trigger too.
  2. Persist before you wait. Store the run, the exact proposed action and its arguments, so a restart does not lose them.
  3. Show the reviewer the real action. Recipient, amount, diff, not a summary of a summary.
  4. Resume with a structured decision. Approved, rejected, changes requested, or expired, plus feedback.
  5. Handle the timeout. Decide what happens when nobody answers: escalate, fall back, or stop.
  6. Record who decided. The decision belongs in the audit trail with the run.

The AgentField version

From the human-in-the-loop docs and the durable approvals guide:

python
from agentfield import Agent

app = Agent(node_id="contract-reviewer", version="1.0.0")

@app.reasoner()
async def review_contract(document: str) -> dict:
    analysis = await app.ai(
        system="Analyze this contract for risks.",
        user=document,
    )

    app.note("Analysis complete, requesting human approval", ["approval"])
    result = await app.pause(
        approval_request_id="review_contract_v1",
        approval_request_url="https://review.example.com/contracts/123",
        expires_in_hours=48,
    )

    if result.decision == "approved":
        return {"status": "approved", "analysis": analysis}
    elif result.decision == "request_changes":
        return {"status": "needs_changes", "feedback": result.feedback}
    else:
        return {"status": result.decision, "feedback": result.feedback}

app.run()

What happens underneath:

  • app.pause() tells the control plane to move the execution to waiting and persists the request ID, review URL, expiry and callback before the agent blocks.
  • Your review tool (a web page, Slack app, ticketing system) posts the decision to POST /api/v1/webhooks/approval-response. HMAC-SHA256 signatures are verified from X-Webhook-Signature, X-Hax-Signature or X-Hub-Signature-256.
  • The control plane resumes the same execution, and pause() returns an ApprovalResult with decision and feedback. Accepted decisions are approved, rejected, request_changes and expired; aliases such as approve or deny are normalized.
  • The default expiry is 72 hours; set expires_in_hours per request. One execution can pause several times, for example a draft review and then a final sign-off.
  • If the agent process restarts mid-wait, await app.wait_for_resume(approval_request_id="review_contract_v1") reconnects to the pending request.

TypeScript uses ApprovalClient.requestApproval() and waitForApproval(); Go uses client.RequestApproval() and client.WaitForApproval(), both polling with backoff (5 s initial, 60 s maximum in Go). The 20-line walkthrough shows the same flow end to end.

Honest limits: the documented flow expects an approval request on a review service you provide (the approval_request_url), which posts the decision back; plan for that page or tool. The docs describe the waiting state as persisted in PostgreSQL, so run production on PostgreSQL rather than the local SQLite default. And handle expired explicitly; it is the branch most teams forget.

When something else fits better

  • Your agent is already a LangGraph graph. interrupt() with a durable checkpointer is the native way, and it supports editing state before resuming. Note the documented gotcha: on resume the node runs again from its start, so code before interrupt() runs twice.
  • Approvals inside long business processes you already run on Temporal. Temporal's own recipe waits on a Signal for "hours, days or indefinitely" with durable timers, which is proven at scale.
  • Tool-level approval in a single OpenAI Agents SDK app. needs_approval=True pauses before the tool runs and surfaces pending calls in result.interruptions. It is the least code when approval is about one tool call, not a whole service.

For agents that must run around the clock and escalate, see agents that run 24/7. For who may approve what, see AI agent governance.

Questions people ask

How do I make an AI agent wait for human approval before it acts?

Put the gate in code right before the action, not in the prompt. In AgentField, await app.pause(approval_request_id=..., expires_in_hours=...) moves the execution to waiting, and it resumes when your review tool posts the decision to the control plane's signed webhook.

Can the approval wait for days?

Yes. AgentField's default expiry is 72 hours and you can set expires_in_hours per request. Because the waiting state is stored by the control plane rather than in the agent's memory, the agent can restart during the wait and reconnect with app.wait_for_resume().

What happens if nobody approves in time?

The approval resolves with the decision expired. Write that branch on purpose: escalate to another reviewer, take a safe default, or stop. A note with app.note(..., ["escalation"]) records what you did.

Can a reviewer ask for changes instead of approving or rejecting?

Yes. AgentField accepts request_changes as a decision with feedback, and the agent can revise and call app.pause() again in the same execution. Multiple pauses per execution are supported.

Do I have to build my own approval screen?

Plan on it for business users. The AgentField docs describe the reviewer working in a service you point to with approval_request_url, and anything that can send a signed POST to /api/v1/webhooks/approval-response can resolve the wait, including a Slack app, a ticketing system or an internal page.

Sources

Checked 2026-11-21 against the AgentField docs and each tool's own documentation on that date.