Principle:Openai Openai agents python Tool Approval Definition

Overview

The OpenAI Agents Python SDK provides a human-in-the-loop (HITL) mechanism for tool execution through the needs_approval parameter. This parameter can be configured on any tool to require explicit human approval before the tool is executed, enabling safe oversight of sensitive or destructive operations.

Core Theory

Human-in-the-Loop for Dangerous Operations

Autonomous agents can invoke tools that perform irreversible or sensitive actions such as deleting files, executing shell commands, modifying databases, or sending messages. Without oversight, these operations carry significant risk. The needs_approval parameter introduces a deliberate pause point in the agent execution loop, giving a human operator the opportunity to review and approve or reject each tool invocation before it proceeds.

The needs_approval Parameter

The needs_approval field is available on all tool types in the SDK. It accepts two forms:

• Boolean mode: When set to True, every invocation of the tool requires approval. When set to False (the default), the tool executes immediately without interruption.
• Dynamic callable mode: A function that receives the run context, tool parameters, and call ID, and returns a boolean indicating whether this specific call needs approval. This allows fine-grained, context-sensitive decisions.

For FunctionTool, the callable signature is:

Callable[[RunContextWrapper[Any], dict[str, Any], str], Awaitable[bool]]

The three arguments are:

1. RunContextWrapper providing the current run context
2. A dictionary of the tool's input parameters for this specific call
3. The call ID string identifying this particular tool invocation

Interruption Mechanism

When a tool call requires approval, the agent run does not raise an exception. Instead, the run completes its current turn and returns a RunResult with a populated interruptions list. Each entry in this list is a ToolApprovalItem object representing a pending tool call that awaits a human decision. The caller can then inspect these items, decide to approve or reject each one, and resume the run.

Built-in Tool Support

Two built-in tools have native approval support:

• ShellTool: Executes shell commands via a user-provided executor function. Its needs_approval field accepts either a bool or a ShellApprovalFunction callable.
• ApplyPatchTool: Applies file mutations via unified diffs. Its needs_approval field accepts either a bool or an ApplyPatchApprovalFunction callable.

Both tools also support an optional on_approval callback.

The on_approval Callback

The on_approval field (available on ShellTool and ApplyPatchTool) provides a mechanism for automatic approval handling. When set, this callback is invoked immediately when an approval is needed, and it can programmatically approve or reject the tool call without requiring manual intervention. This is useful for:

• Auto-approving known-safe command patterns
• Auto-rejecting known-dangerous patterns
• Logging approval requests for audit purposes
• Delegating approval decisions to an external system

Design Rationale

The approval system is designed around several principles:

• Non-blocking architecture: Runs are interrupted cleanly rather than blocking on user input, enabling asynchronous workflows where a human may not be immediately available.
• Granularity: Approval can be configured per-tool and per-call, not just globally, allowing precise control over which operations require oversight.
• Composability: The approval mechanism integrates with the SDK's state serialization system (RunState), enabling persistence of interrupted runs across process boundaries.

Key Source References

• src/agents/tool.py lines 253-264: FunctionTool.needs_approval field definition
• src/agents/tool.py lines 679-699: ShellTool dataclass with approval fields

Related Concepts

• Implementation:Openai_Openai_agents_python_Tool_Approval_Config
• RunState Serialization for capturing interrupted run state
• Approval Processing for approving and rejecting pending tool calls
• Execution Resumption for resuming runs after approval decisions