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.

By 0xScorPionSon

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

openai-agents PyPI 0.24.0 and 0.25.0 vs @openai/agents npm 0.22.0 infographic showing MCP v2 Streamable HTTP, sandbox clients, and pre-1.0 breaking changes

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-abi3 wheels built for Linux x86_64 glibc 2.39+, macOS 11+ Apple Silicon, and Windows x64) (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, RunState schema 1.22), and 0.25.0 release files on PyPI.
    • Optional Extras: openai-agents[voice], openai-agents[redis], and openai-agents[docker].
  • 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.6 while preserving saved guardrail checkpoints with omitted metadata; Realtime WebSocket manual-interrupt cancellation fix; and RunState schema 1.23 / 1.24 support.

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

  1. Strict Sandbox Write Policy (write_policy="strict"): New Python Environment instances now default to write_policy="strict" (requiring a compatible Linux or macOS executor), keeping only the working directory writable unless writable_roots is specified (GitHub Python Releases). Windows executors or legacy setups must explicitly set write_policy="legacy" if needed.
  2. 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, ElicitationRequest is now a union (FormRequest | UrlRequest) (GitHub Python Releases).
  3. 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.0 during migration (GitHub Python Releases).
  4. TypeScript Type Narrowing & Stream Validation (0.22.0): @openai/agents@0.22.0 rejects unfinished official Chat Completions streams, defaults reasoning effort to none for function tools/handoffs on gpt-6-sol and gpt-6-luna, and introduces breaking TypeScript types requiring narrowing on usage details, nullable MCP descriptions, and Realtime image content (GitHub JS Releases).
  5. Known Guardrail Edge Case (openai-agents==0.24.0): GitHub issue #5567 (Nov 6, 2026) documents a reproducible bug in non-streaming Runner.run with parallel input guardrails on Python 3.13.18 where an already-completed sibling input guardrail result can be omitted from exception.run_data.input_guardrail_results when 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

  1. Pin exact minor/patch versions in pyproject.toml (openai-agents==0.24.0) or package.json ("@openai/agents": "0.22.0") rather than floating ^ or >= ranges (Blaxel).
  2. Audit RunState checkpoint compatibility before upgrading if you persist paused human-in-the-loop approval states across deployments (1.22 in Python, 1.23/1.24 in TS).
  3. Update deprecated MCP & sandbox flags: Replace approval_mode="auto" / "approve" with "native" / "preapproved", and verify write_policy="strict" does not break custom temp paths.
  4. Never expose long-lived OPENAI_API_KEY to browser Realtime clients: Mint short-lived ephemeral client tokens on your backend before calling session.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

  1. PyPI — openai-agents Package Metadata (0.24.0 / 0.25.0) (Accessed November 21, 2026)
  2. GitHub Releases (openai/openai-agents-python) — Python SDK Releases & Breaking Changes (Updated November 18, 2026)
  3. npm — @openai/agents (0.22.0) Package Documentation (November 13, 2026)
  4. GitHub Releases (openai/openai-agents-js) — @openai/agents@0.22.0 Release Notes (November 13, 2026)
  5. Blaxel — OpenAI Agents SDK guide to tools, handoffs, and sandboxes (November 20, 2026)
  6. GitHub Issues (openai/openai-agents-python) — Issue #5567: Parallel input guardrail tripwire edge case in 0.24.0 (November 6, 2026)

More on Packages

Packages

OpenAI @openai/codex 0.171.0: GPT-6.2 Sol Default, TUI Workspace, and Sandbox Hardening

OpenAI released @openai/codex 0.171.0 on November 20, 2026, switching the default CLI model to GPT-6.2 Sol, enabling the TUI workspace with document and image previews by default, and adding remote app-server execution. Backed by 23.2 million weekly npm downloads and a Rust 1.99.1 core, the release also hardens Linux seccomp sandboxing and enterprise MCP sign-in.

8 min read

Packages

FastMCP 4.2.3: Breaking Changes, OAuth & OpenTelemetry Security Fixes, and Production Upgrade Guide

FastMCP 4.2.3 ships with opt-in parent_task_spans tracing and OpenAPI path validation fixes, capping a week of rapid 4.2.x updates that dropped Python 3.10 support and patched critical OAuth and OpenTelemetry ReDoS flaws. With 64.5 million monthly PyPI downloads, upgrading safely requires checking your Python runtime floor, OAuth consent behavior, and deprecated 4.1 skills APIs. Here is the exact changelog breakdown, ecosystem comparison against the official MCP Python SDK 2.3.0, and a step-by-step upgrade checklist.

9 min read

Packages

agent-framework v1.26.0 vs. Malicious 1.26.1–1.26.2: PyPI Compromise Telemetry and Safe Pinning Guide

Microsoft's agent-framework PyPI package (193,470 monthly downloads) suffered a brief supply-chain compromise on November 17, 2026, when unauthorized 1.26.1 and 1.26.2 wheels dropped a Python .pth startup stealer targeting OPENAI, HF_, AZURE, and GitHub Actions OIDC tokens. PyPI removed both releases, leaving v1.26.0 (November 12, 2026) as the latest clean version. Here is the exact telemetry, SHA-256 verification, and safe pinning checklist.

6 min read

Tell us what is not working

A thirty-minute call, no deck and no obligation. You will leave with a straight answer about whether this is worth building - including if that answer is no.

Start a project

Direct line

hello@codebumble.net
Dhaka, Bangladesh  :   local timeCalls in English or Bangla