OpenAI Agents SDK preview separates local profiles from portable checkpoints

OpenAI’s Agents SDK preview adds `LocalStorage` for reopening a conversation from a local profile and expands portable `SessionState` recovery, according to its [tracked alpha.6 changelog](https://github.com/openai/openai‑agents‑python/blob/v0.24.0‑alpha.6/CHANGELOG‑alpha.md). Those are different recovery choices: keeping a profile directory available and moving a serialized checkpoint require different artifacts and application setup. The alpha.6 prerelease was published November 3; its tracked changelog still labels that version “Unreleased.” ([Release record](https://github.com/openai/openai‑agents‑python/releases/tag/v0.24.0‑alpha.6)) This guide concerns the preview API at `v0.24.0‑alpha.6`. The [pinned repository README](https://github.com/openai/openai‑agents‑python/tree/v0.24.0‑alpha.6) directs users to GitHub release wheels and says the `openai‑agents` package on PyPI is the previous SDK, without the API shown here. The analysis below combines the pinned documentation’s storage and recovery contracts; we have not installed the preview or tested recovery. Its practical question is which conversation artifact an application can retain, and what must be supplied again before work continues.

The sessions guide describes three choices:

• A live Session: retain the open Session when the conversation only needs to continue within the current application process.
• A local profile: retain the profile directory and session.id. Reopen using the same directory and resume=saved_id, with current application configuration.
• A portable snapshot: obtain SessionState from await session.save_state(), keep it in trusted storage, and serialize with state.to_json() when needed. The guide loads that value with SessionState.from_json().

A local profile permits one native writer at a time. It cannot export portable state through save_state(), suspend() or fork(), and the guide says not to combine local storage or resume with portable state. Choosing a profile therefore does not leave a documented portable‑export route available later.

For a handoff to another process or host, list the retained conversation artifact separately from the resources the application must reconstruct. The guide explicitly says portable checkpoints do not copy workspace files or live processes; both restoration methods need current tools, context and provider configuration. A saved conversation is only one part of that handoff.

Portable restore requires the same pinned Codex revision as the SDK that saved the checkpoint, according to the restore guide. Recognizing the JSON format is insufficient. Keep the matching SDK wheel available; changing the checkpoint’s codex_revision field does not migrate its contents.

The application must also open each restore with a fresh Agent and isolated storage, match saved Python and manual tool definitions, accepted instructions and any applicable output type, and supply current callbacks, credentials and context. Current MCP declarations can narrow an old selection. Saved text does not choose credentials or grant permissions.

Instruction recovery needs its own policy decision. The guide’s state.instructions accessor uses trusted checkpoint storage as the instruction source. If the application instead requires independently configured current instructions, restore requires an exact match and rejects a mismatch. Editing saved native history to insert new instructions or credentials is not the documented solution.

Saved model settings are another compatibility check: portable restore retains them. The guide rejects non-None opening model or model_settings overrides, including an empty settings object. Its permitted idle‑update path comes after restoration; Sessions opened with NativeAgents cannot change the model or model settings. A recovery record should identify the configuration that will actually resume.

The [local recovery section](https://github.com/openai/openai‑agents‑python/blob/v0.24.0‑alpha.6/docs/sdk/sessions.md#recover‑after‑interruption) says reopening fails with `RuntimeError` when saved history includes a function call whose outcome is unknown, or an active child runtime that cannot be restored. No new model request starts in either case. One example in the guide is a crash after an external effect occurred but before its result was recorded. The prescribed first step is to preserve the profile and inspect the application’s records of external effects before starting another conversation. Repeating `resume` does not resolve the unknown outcome. The guide provides no public operation to repair that history, and checking external records does not itself repair it. That boundary changes the next operator’s decision. Conversation recovery and effect verification need separate entries: one records whether the SDK can reopen the conversation; the other records what the application can establish about work already performed. The [checkpoint warning](https://github.com/openai/openai‑agents‑python/blob/v0.24.0‑alpha.6/docs/sdk/sessions.md#protect‑saved‑data‑and‑effects) likewise says a checkpoint does not coordinate concurrent processes or guarantee durable execution. If an effect occurred but its result was never accepted, retrying may repeat it.

A useful handoff can combine those documented limits into five entries. This is an unexecuted planning record, not a recovery test or a guarantee:

1. Persistence choice and artifact: identify an open Session, a retained local directory plus conversation ID, or a trusted portable checkpoint. Record where it is kept and which application owns it.
2. Compatible runtime: for a portable checkpoint, retain the matching SDK wheel and pinned Codex revision. Record the saved model/settings that restoration will keep.
3. Current application bindings: identify the tool definitions, callbacks, credentials, context and instruction policy required by the intended restore. Keep secrets in the application’s normal credential store.
4. Capture state: distinguish an idle save_state() from a supported settled manual suspend(). Check the applicable capability and checkpoint readiness; the guide says readiness reserves nothing and saving checks again.
5. External‑effect evidence: identify the application records an operator can inspect after interruption. Record unknown outcomes as unknown, and retain the original conversation artifact rather than assuming a retry repaired it.

The same guide says restoring idle child histories does not automatically resume interrupted child work, and retained planning data does not start work or grant tools. That makes a successful restore an input to the application’s next decision about work, with the documented compatibility and effect checks still relevant.

Reporting is based on the pinned documentation, © 2025 OpenAI, MIT license. The guide’s separate NetworkPolicy/offline‑executor subsection is marked unreleased and is outside the behavior described here.

Archival photograph: OpenAI cofounder Sam Altman at TechCrunch Disrupt San Francisco on October 3, 2019. Photo source; CC BY 2.0. Cropped and resized; the photograph supplies company context.