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
| Tool | How you pause | How you resume | Where the waiting state lives |
|---|---|---|---|
| AgentField | app.pause(approval_request_id=...) inside a reasoner | HMAC-signed webhook to /api/v1/webhooks/approval-response | Control plane database |
| LangGraph | interrupt() inside a node | Invoke again with the thread ID and Command(resume=...) | Your checkpointer |
| Temporal | Workflow waits on a condition or durable timer | Send a Signal | Temporal service history |
| OpenAI Agents SDK | Mark a tool needs_approval=True | state.approve(...) or state.reject(...), then run again | Run state you serialize with to_json() |
| Mastra | Suspend an agent or workflow | Resume with the user's input | Mastra storage |
The pattern, whatever you use
- Decide what needs approval in code. Refunds, outbound email, deletes, payments: anything external, irreversible or costly. Low model confidence is a good trigger too.
- Persist before you wait. Store the run, the exact proposed action and its arguments, so a restart does not lose them.
- Show the reviewer the real action. Recipient, amount, diff, not a summary of a summary.
- Resume with a structured decision. Approved, rejected, changes requested, or expired, plus feedback.
- Handle the timeout. Decide what happens when nobody answers: escalate, fall back, or stop.
- 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:
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 towaitingand 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 fromX-Webhook-Signature,X-Hax-SignatureorX-Hub-Signature-256. - The control plane resumes the same execution, and
pause()returns anApprovalResultwithdecisionandfeedback. Accepted decisions areapproved,rejected,request_changesandexpired; aliases such asapproveordenyare normalized. - The default expiry is 72 hours; set
expires_in_hoursper 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 beforeinterrupt()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=Truepauses before the tool runs and surfaces pending calls inresult.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
- AgentField docs, checked 2026-11-21: human-in-the-loop, durable approvals, deferred execution
- LangGraph interrupts, Temporal human-in-the-loop recipe, Temporal message passing, OpenAI Agents SDK human-in-the-loop, Mastra repo, checked 2026-11-21
Checked 2026-11-21 against the AgentField docs and each tool's own documentation on that date.