Source: Human-in-the-loop (OpenAI Agents SDK docs)
OpenAI Agents SDK tool-approval flow: needs_approval, run interruptions, RunState approve/reject with sticky decisions, JSON serialization for long waits, and security guidance.
Contents
- What: official SDK documentation (Python)
- Publisher: OpenAI
- Date: accessed 2026-11-14
- Original: Human-in-the-loop
Summary
Tools can be flagged as needing approval. When the model calls one and no decision is stored, the run stops and returns the pending calls as interruptions. The application converts the result into a RunState, records approve/reject decisions, optionally serializes the state to wait for a human, and resumes the run by passing the state back to the runner.
Key claims
needs_approvalisTrueor an async predicate over (context, parsed args, call ID); unparseable arguments force manual approval. Available onfunction_tool,Agent.as_tool,ShellTool,ApplyPatchTool.- Paused runs expose
result.interruptions(ToolApprovalItementries);result.to_state()produces aRunState. state.approve()/state.reject();always_approve=True/always_reject=Truemake sticky decisions;rejection_message=customizes what the model sees.- Resume with
Runner.run(original_top_level_agent, state); unresolved interruptions pause again. Nested agent-as-tool approvals surface on the outer run. state.to_json()/RunState.from_json(agent, data)persist pending runs; sticky decisions survive the round trip.- MCP: local servers take
require_approval;HostedMCPToolacceptsrequire_approval: "always"and anon_approval_requestcallback. - Guidance for long-running approvals: serialized state is not authenticated (only load trusted snapshots); keep the full snapshot server-side and show reviewers only what they are authorized to see; authenticate and authorize each reviewer; validate decisions against stored interruptions; make resume an atomic transition so a snapshot cannot be resumed twice; approval does not give exactly-once execution, so use idempotency keys; store a code-version marker with the state.