Packages
openai-agents 0.24.0–0.25.0 vs. @openai/agents 0.22.0: Breaking Changes, MCP v2, and Sandbox Trade-Offs
OpenAI's Agents SDK ships as two fast-moving pre-1.0 packages: openai-agents on PyPI (0.24.0 stable / 0.25.0 release files) and @openai/agents on npm (0.22.0, MIT). Because minor releases introduce breaking RunState schemas, MCP approval-mode renames, and strict sandbox write policies, pinning exact versions is essential. Here is the side-by-side changelog, dependency footprint, and safe upgrade guide.
6 min read
openai-agents 0.24.0–0.25.0 vs. @openai/agents 0.22.0: Breaking Changes, MCP v2, and Sandbox Trade-Offs
Executive Summary
OpenAI's open-source Agents SDK is distributed as two parallel, pre-1.0 packages: openai-agents on PyPI (Python 3.10+, MIT license) and @openai/agents on npm (JavaScript/TypeScript, MIT license) (PyPI, npm). As of November 20–21, 2026, PyPI lists 0.24.0 (October 15, 2026) and 0.25.0 release files alongside active 0.24.0-alpha.6 / 0.24.0-alpha.7 GitHub release-engineering runs (updated November 18, 2026), while npm's latest TypeScript release is @openai/agents@0.22.0 (November 13, 2026) (GitHub Python Releases, GitHub JS Releases).
Both packages wrap LLMs in an orchestration loop combining function tools, handoffs, input/output guardrails, sessions, tracing, and isolated sandboxes (Blaxel). However, because both SDKs remain pre-1.0, minor releases routinely introduce breaking API and state-schema changes—including RunState schema bumps (1.22–1.24), MCP approval-mode renames, write_policy="strict" sandbox defaults, and Zod 4.6.6 type narrowing. The primary engineering takeaway is clear: pin exact minor/patch versions in production, run ScriptedModel or unit-level tests on every upgrade, and isolate agent-generated code execution inside a container sandbox.
Confidence assessment: High confidence on version numbers, release dates, MIT license, Python 3.10+ floor, Zod 4.6.6, RunState schemas, and breaking-change diffs (sourced directly from PyPI, npm, GitHub Releases/CHANGELOGs, and Blaxel's November 20, 2026 guide). Note that exact PyPI/npm weekly download counts were not exposed in the fetched snippets and are therefore omitted rather than estimated.
Adoption Telemetry & Version Changelog
Rather than shipping as a single monolithic library, OpenAI maintains separate Python and TypeScript monorepos that track closely on wire semantics and model defaults:
- Python (
openai-agents):- Minimum Runtime: Python 3.10 or newer (
cp310-abi3wheels built for Linuxx86_64glibc 2.39+, macOS11+Apple Silicon, and Windowsx64) (PyPI, GitHub Python Releases). - Key Releases:
0.23.0(Oct 1, 2026: MCP listing page limits, Docker removal protection, encrypted session scan budget),0.24.0(Oct 15, 2026: MCP annotations on converted tools, run-wide tool exception formatting, batched conversation session writes),0.24.0-alpha.6/alpha.7(Nov 2026: MCP v2 Streamable HTTP concurrent requests,RunStateschema1.22), and0.25.0release files on PyPI. - Optional Extras:
openai-agents[voice],openai-agents[redis], andopenai-agents[docker].
- Minimum Runtime: Python 3.10 or newer (
- JavaScript/TypeScript (
@openai/agents):- Modular Packages:
@openai/agents(meta-package),@openai/agents-core@0.22.0,@openai/agents-openai@0.22.0, and@openai/agents-realtime@0.22.0(released November 13, 2026) (npm, GitHub JS Releases). - Key Milestones: Zod updated to
4.6.6while preserving saved guardrail checkpoints with omitted metadata; Realtime WebSocket manual-interrupt cancellation fix; andRunStateschema1.23/1.24support.
- Modular Packages:
Security Patches, Breaking Changes & Internals
While no CVE advisories are tied to these releases in the fetched sources, recent changelogs introduce critical security-posture defaults and breaking API diffs that teams must handle before upgrading:
1. Breaking Changes in Recent openai-agents & @openai/agents Releases
- Strict Sandbox Write Policy (
write_policy="strict"): New PythonEnvironmentinstances now default towrite_policy="strict"(requiring a compatible Linux or macOS executor), keeping only the working directory writable unlesswritable_rootsis specified (GitHub Python Releases). Windows executors or legacy setups must explicitly setwrite_policy="legacy"if needed. - MCP Approval-Mode Renames & Elicitation Unions: In Python
0.24.0-alpha.6+,approval_mode="auto"was renamed to"native"and"approve"to"preapproved"—old values are rejected. Additionally,ElicitationRequestis now a union (FormRequest | UrlRequest) (GitHub Python Releases). - Runloop Removal & Sandbox Migration: Teams running Runloop sandboxes must migrate to another supported sandbox provider (such as Modal or Docker) or remain pinned on
0.24.0during migration (GitHub Python Releases). - TypeScript Type Narrowing & Stream Validation (
0.22.0):@openai/agents@0.22.0rejects unfinished official Chat Completions streams, defaults reasoning effort tononefor function tools/handoffs ongpt-6-solandgpt-6-luna, and introduces breaking TypeScript types requiring narrowing on usage details, nullable MCP descriptions, and Realtime image content (GitHub JS Releases). - Known Guardrail Edge Case (
openai-agents==0.24.0): GitHub issue#5567(Nov 6, 2026) documents a reproducible bug in non-streamingRunner.runwith parallel input guardrails on Python3.13.18where an already-completed sibling input guardrail result can be omitted fromexception.run_data.input_guardrail_resultswhen a tripwire fires (GitHub Issue #5567).
Safe Configuration & Code Example (Pinned Sandbox Agent)
When an agent writes or executes code, Blaxel and PyPI recommend isolating execution inside a SandboxAgent (DockerSandboxClient on Windows or UnixLocalSandboxClient/hosted sandbox on Linux/macOS) and keeping browser RealtimeSession API keys short-lived via server-minted ephemeral tokens:
# Safe pattern for openai-agents==0.24.0+ (Python 3.10+)
# Explicitly pin model_settings and isolate code execution in DockerSandboxClient
from agents import Agent, ModelSettings
from agents.sandbox import SandboxAgent, DockerSandboxClient
sandbox_agent = SandboxAgent(
name="IsolatedWorker",
instructions="Inspect repository files and run read-only checks.",
model="gpt-4.1",
model_settings=ModelSettings(reasoning_effort="low"),
sandbox_client=DockerSandboxClient(),
)
Ecosystem Comparison & Upgrade Checklist
| Attribute | openai-agents (Python / PyPI) |
@openai/agents (TypeScript / npm) |
|---|---|---|
| Latest Verified Version | 0.24.0 (Oct 15, 2026); 0.25.0 files on PyPI |
0.22.0 (Nov 13, 2026) |
| License & Maturity | MIT • Pre-1.0 (minor breaking changes) | MIT • Pre-1.0 (minor breaking changes) |
| Runtime / Schema Floor | Python 3.10+ (cp310-abi3 wheels) |
Node.js / TypeScript + Zod 4.6.6 |
| MCP Support | MCP annotations + MCP v2 Streamable HTTP (alpha.6+) |
MCP discovery annotations + nullable descriptions |
| Sandbox Options | UnixLocalSandboxClient, DockerSandboxClient, Modal |
UnixLocalSandboxClient, DockerSandboxClient, hosted |
| State Schema | RunState schema 1.22 (nested approvals) |
RunState schema 1.23 / 1.24 |
| Voice / Realtime | openai-agents[voice] (gpt-realtime-2.1) |
@openai/agents/realtime (WebRTC browser audio) |
(Performance benchmark note: No cross-language latency or memory benchmarks comparing openai-agents against @openai/agents are published in the fetched releases; runtime latency is typically dominated by upstream LLM and sandbox cold-start times.)
Safe Upgrade & Pinning Checklist
- Pin exact minor/patch versions in
pyproject.toml(openai-agents==0.24.0) orpackage.json("@openai/agents": "0.22.0") rather than floating^or>=ranges (Blaxel). - Audit
RunStatecheckpoint compatibility before upgrading if you persist paused human-in-the-loop approval states across deployments (1.22in Python,1.23/1.24in TS). - Update deprecated MCP & sandbox flags: Replace
approval_mode="auto"/"approve"with"native"/"preapproved", and verifywrite_policy="strict"does not break custom temp paths. - Never expose long-lived
OPENAI_API_KEYto browser Realtime clients: Mint short-lived ephemeral client tokens on your backend before callingsession.connect(...)(npm).
Frequently Asked Questions (FAQ)
1. Is the OpenAI Agents SDK production-ready (1.0)?
No, both openai-agents (PyPI) and @openai/agents (npm) are still pre-1.0 as of November 2026, and minor versions can introduce breaking API or type changes (Blaxel). Teams should pin exact versions and test upgrades with mock/scripted models.
2. What is the difference between openai-agents and @openai/agents?
openai-agents targets Python 3.10+ backends (with Redis sessions, Docker/Modal sandboxes, and cp310-abi3 native wheels), while @openai/agents targets TypeScript/JavaScript stacks (including browser WebRTC RealtimeSession and Zod 4.6.6 validation) (PyPI, npm).
3. Does the OpenAI Agents SDK support Model Context Protocol (MCP)?
Yes. Both SDKs support MCP tools and discovery annotations, and recent Python 0.24.0-alpha builds add MCP v2 Streamable HTTP concurrent request support (GitHub Python Releases).
4. Can I run UnixLocalSandboxClient on Windows?
No. Both PyPI and npm documentation specify that UnixLocalSandboxClient is supported on macOS and Linux; on Windows, use DockerSandboxClient (openai-agents[docker]) or a hosted sandbox client (PyPI, npm).
5. What happened to Runloop support in openai-agents?
Recent openai-agents-python release notes advise migrating Runloop workloads to another supported sandbox provider (such as Modal) or remaining pinned on 0.24.0 while completing data and snapshot migration (GitHub Python Releases).
Sources
- PyPI — openai-agents Package Metadata (
0.24.0/0.25.0) (Accessed November 21, 2026) - GitHub Releases (
openai/openai-agents-python) — Python SDK Releases & Breaking Changes (Updated November 18, 2026) - npm — @openai/agents (
0.22.0) Package Documentation (November 13, 2026) - GitHub Releases (
openai/openai-agents-js) — @openai/agents@0.22.0 Release Notes (November 13, 2026) - Blaxel — OpenAI Agents SDK guide to tools, handoffs, and sandboxes (November 20, 2026)
- GitHub Issues (
openai/openai-agents-python) — Issue #5567: Parallel input guardrail tripwire edge case in0.24.0(November 6, 2026)