Principle:Openai Openai agents python RunState Serialization

Overview

When an agent run is interrupted (for example, because a tool call requires human approval), the OpenAI Agents Python SDK captures the complete execution state as a RunState object. This snapshot can be serialized, persisted to storage, transmitted over a network, and later used to resume execution from exactly where it stopped.

Core Theory

State Capture at Interruption

An agent run proceeds through a loop of model invocations and tool calls. When the loop encounters a tool that requires approval, it does not block or raise an exception. Instead, it completes the current processing step, packages the run's state into a RunResult, and returns control to the caller. The caller then invokes to_state() on the RunResult to obtain a RunState snapshot.

What RunState Captures

The RunState dataclass preserves all information necessary to resume execution:

• Current agent: The agent that was active when the interruption occurred
• Original input: The user's initial input to the run (string or list of input items)
• Generated items: All RunItem objects produced during execution so far, used to reconstruct model input upon resumption
• Session items: The full, unfiltered history of run items for session persistence
• Model responses: All model responses received during the run
• Turn counter: The current turn number, ensuring the turn budget is preserved across resume cycles
• Approval state: The approval/rejection decisions stored in the RunContextWrapper._approvals dictionary
• Interruption step: The NextStepInterruption object containing the pending ToolApprovalItem entries
• Max turns: The configured maximum turn limit
• Guardrail results: Input, output, tool input, and tool output guardrail results
• Conversation tracking: conversation_id, previous_response_id, and auto_previous_response_id for server-managed conversation state
• Tool use tracker: A snapshot of which tools each agent has invoked, serialized as a dictionary mapping agent names to lists of tool names
• Processed response: The last ProcessedResponse needed for resuming from the exact interruption point

The to_state() Method

The RunResult.to_state() method is the primary entry point for state capture. It constructs a new RunState instance and populates it with all the data from the current result, including internal bookkeeping fields that are not part of the public result API. This method is defined in src/agents/result.py (lines 268-313).

The method delegates to an internal _populate_state_from_result() helper that copies over:

• The current turn count
• The last processed response
• The count of items already persisted in the current turn
• The tool use tracker snapshot
• Conversation tracking identifiers

Enabling Asynchronous HITL Workflows

The serialization capability of RunState enables workflows where the approval decision does not need to happen immediately or within the same process:

1. An agent run encounters a tool requiring approval and returns a RunResult with interruptions.
2. The application calls to_state() and serializes the state (e.g., to a database or message queue).
3. A human reviewer, possibly using a different application or service, retrieves the serialized state, reviews the pending tool calls, and records approval or rejection decisions.
4. The application deserializes the state, applies the decisions, and passes the RunState back to Runner.run() to resume.

This architecture supports use cases such as web-based approval dashboards, mobile notification workflows, and multi-user review processes.

RunState as Input to Runner.run()

The Runner.run() method accepts RunState as its input parameter, alongside str and list[TResponseInputItem]. This polymorphic design means resumption uses the same API entry point as initial execution, simplifying the programming model.

Key Source References

• src/agents/result.py lines 268-313: RunResult.to_state() method
• src/agents/run_state.py lines 112-207: RunState dataclass and constructor

Related Concepts

• Implementation:Openai_Openai_agents_python_RunResult_To_State
• Tool Approval Definition for configuring tools to require approval
• Approval Processing for approving/rejecting pending tool calls on a RunState
• Execution Resumption for passing RunState back to Runner.run()