Principle:Openai Openai agents python Approval Processing

Overview

After an agent run is interrupted for tool approval, the pending tool calls must be individually reviewed and either approved or rejected. The RunState object provides methods for inspecting pending approvals and recording decisions, which are stored in the RunContextWrapper's approval tracking system.

Core Theory

Retrieving Pending Approvals

When a run is interrupted, the RunState contains a _current_step field of type NextStepInterruption. This object holds a list of ToolApprovalItem instances, each representing a single pending tool call that requires a human decision.

The get_interruptions() method provides safe access to these items. It checks whether the current step is an interruption and returns the list of pending ToolApprovalItem objects. If there are no interruptions (the current step is None or is not a NextStepInterruption), it returns an empty list.

Approving a Tool Call

The approve() method marks a specific ToolApprovalItem as approved. This records the approval in the RunContextWrapper._approvals dictionary, which maps tool names to approval records.

The method accepts an optional always_approve parameter. When set to True, all future calls to the same tool are automatically approved without requiring further human intervention. This is useful when a user trusts a particular tool and wants to grant blanket approval for the remainder of the run.

Rejecting a Tool Call

The reject() method marks a specific ToolApprovalItem as rejected. When the run resumes, the rejected tool call is not executed. Instead, an error message is sent back to the LLM, informing it that the tool call was denied. The model can then decide how to proceed, potentially choosing an alternative approach or asking the user for different instructions.

Similar to approve(), the reject() method accepts an optional always_reject parameter that automatically rejects all future calls to the same tool.

Approval State Storage

Approval decisions are persisted in the RunContextWrapper._approvals dictionary. This dictionary maps tool names (strings) to approval records that track:

• Which specific call IDs have been approved
• Which specific call IDs have been rejected
• Whether the tool has a blanket always_approve or always_reject flag

This design allows the approval state to accumulate across multiple interruption-resume cycles within the same run, providing a consistent and queryable record of all decisions made.

Independent Processing of Multiple Interruptions

A single run turn may produce multiple tool calls that each require approval. Each ToolApprovalItem in the interruptions list can be processed independently: some may be approved while others are rejected. This granularity ensures that a human reviewer has full control over each individual operation.

Error Handling

Both approve() and reject() raise a UserError if the RunState has no associated context (i.e., _context is None). This guards against calling these methods on an improperly initialized or deserialized state.

Key Source References

• src/agents/run_state.py lines 208-227: get_interruptions(), approve(), and reject() methods

Related Concepts

• Implementation:Openai_Openai_agents_python_RunState_Approve_Reject
• Tool Approval Definition for configuring which tools require approval
• RunState Serialization for capturing run state at interruption
• Execution Resumption for resuming the run after decisions are recorded