OpenAI Agents SDK 0.20: MCP v2 Migration Guide

Direct answer

OpenAI Agents SDK 0.20.0 is a meaningful upgrade for Python teams building production agents, but it is not a drop-in patch for every application. The release makes GPT-5.6 Luna the default model, adds local MCP support for both MCP Python SDK v1 and v2, improves resumable state with RunState.add_input(), and tightens sandbox credential handling. The migration risk is concentrated in applications that customize local HTTP MCP authentication or client factories: those integrations may need the new httpx2 types, or they should pin mcp<2 while they migrate.

It explains what changed, how to upgrade safely, how to use the related Programmatic Tool Calling feature, and where a production rollout can go wrong.

Key takeaways

• openai-agents 0.20.0 was released to PyPI on August 11, 2026 and requires Python 3.10 or newer.
• The implicit SDK default is now gpt-5.6-luna; explicit agent models, run-level overrides, and OPENAI_DEFAULT_MODEL still win.
• Local stdio, SSE, and Streamable HTTP MCP connections support MCP SDK v1 and v2, but custom HTTP integrations need a dependency review.
• RunState.add_input() lets a paused workflow stage durable user input before resuming.
• Sandbox mount validation now asks applications to explicitly acknowledge credential exposure instead of silently widening authority.
• Programmatic Tool Calling is a separate Responses API capability: generated JavaScript can coordinate eligible tools in an isolated V8 runtime, but it cannot access the network, filesystem, Node.js APIs, or subprocesses.

What changed in OpenAI Agents SDK 0.20.0?

The release is a minor version in the SDK's 0.Y.Z scheme, but it includes a potentially breaking MCP dependency migration. The most important changes are operational rather than cosmetic.

The SDK's own changelog describes 0.20.0 as potentially breaking for applications that customize local MCP HTTP transports. That is the upgrade boundary to investigate first; ordinary function tools and basic stdio MCP servers are less likely to require code changes, but they still deserve a test run.

A practical architecture for the upgrade

Treat the SDK upgrade as a dependency and behavior change, not just a version bump.

For teams already using portable skills and MCP packages, the SDK update complements the cross-client approach described in the Agent Plugins 1.0 guide. It does not remove the need to define narrow tools, approval boundaries, and server-specific authentication policy.

Upgrade and pin the dependency

Use a fresh virtual environment or a lockfile-controlled environment. Do not begin by changing the production interpreter in place.

1python3.12 -m venv .venv
2source .venv/bin/activate
3python -m pip install --upgrade pip
4python -m pip install 'openai-agents==0.20.0'
5python -m pip show openai-agents mcp httpx

For a project using uv:

1uv add 'openai-agents==0.20.0'
2uv lock
3uv run python -c 'import agents; print("Agents SDK import OK")'

Capture the resolved dependency graph in CI. The version you test is the version you deploy; a floating mcp dependency can turn a passing local test into a different production environment later.

Default model behavior: avoid accidental changes

Version 0.20.0 changes the implicit default to gpt-5.6-luna. This affects code that creates an Agent without a model and code that relies on the SDK's default through Runner. Explicit configuration still takes precedence.

1import os
2from agents import Agent, Runner
3
4agent = Agent(
5    name="Release assistant",
6    instructions="Summarize the release and list migration risks.",
7    model="gpt-5.6-luna",
8)
9
10result = Runner.run_sync(agent, "Review the 0.20.0 upgrade plan.")
11print(result.final_output)

If your application intentionally used the previous implicit model, make that choice explicit during migration and compare both versions in an evaluation set. Check structured-output validity, tool-call frequency, refusal behavior, latency, token usage, and user-visible wording. A model-default change can be a product change even when the Python API remains compatible.

The SDK's official tools catalog also documents the Responses-only tool features used below. Teams routing through a compatible provider should verify that the provider actually supports the Responses features rather than assuming an OpenAI-compatible URL is enough.

MCP v2 migration: what to inspect

The SDK now supports MCP Python SDK v1 and v2 for local stdio, SSE, and Streamable HTTP transports. The compatibility layer can probe the installed protocol and fall back for older servers. That is helpful for ordinary clients, but custom integrations can still break at the HTTP boundary.

Audit these areas:

1. Custom authentication objects. If you pass an httpx.Auth implementation into a custom MCP transport, check whether it belongs to the HTTP major version selected by the MCP dependency.
2. Custom httpx.AsyncClient factories. Rebuild factories against the installed httpx2 types when MCP v2 is selected, or pin mcp<2 temporarily.
3. Streamable HTTP options. Review options that are explicitly v1-only, including ignore_initialized_notification_failure on the relevant server configuration.
4. Lifecycle assumptions. Test startup, reconnect, shutdown, and two simultaneous runs. The release includes lifecycle serialization and bounded timeouts, which can expose code that depended on an old race.
5. Tool schemas and non-text outputs. Recheck images, resources, audio, and free-form object schemas if your MCP server returns more than text.

A minimal test should connect to the same server using stdio and Streamable HTTP where applicable, call one read-only tool, force an authentication failure, and then close the connection cleanly. Never begin the migration with a write-capable production MCP server.

For broader MCP architecture and migration context, use the verified live MCP developer coverage on this site. The OpenAI SDK change is a client-library concern; it does not change the protocol's authorization model or make an untrusted server safe.

Durable input with RunState.add_input()

Long-running agents often stop for approval, a missing file, or a human answer. The new RunState.add_input() API lets an application stage durable input before making the next model call. The input can pass through guardrails, survive serialization, and appear as one durable occurrence when the run resumes.

The safe pattern is to persist the SDK's run state, add the user's answer exactly once after an approval boundary, and resume through the documented runner/session API. The exact state-management method depends on the SDK version and your session implementation, so verify the current API reference before copying it into production. The important design rule is that approval text is input, not authority. Your application must still enforce the permission check at the side-effecting tool boundary. A model seeing “approved” in conversation should not be enough to deploy, delete, send, or publish.

This is especially relevant if your system uses the Microsoft Agent Framework guide as a comparison point: the surface APIs differ, but both ecosystems reward explicit state, tool permissions, and human review rather than prompt-only control.

Programmatic Tool Calling: useful, but bounded

Programmatic Tool Calling lets a supported Responses model generate JavaScript that calls eligible tools, combines their outputs, and returns a smaller result to the model. It can reduce round trips for predictable workflows such as filtering many inventory records, joining several lookups, or calculating a result from tool outputs.

1from pydantic import BaseModel
2from agents import Agent, ModelSettings, ProgrammaticToolCallingTool, Runner
3from agents.decorators import tool
4
5class InventoryOutput(BaseModel):
6    sku: str
7    available_units: int
8
9@tool(allowed_callers=["programmatic"])
10def get_inventory(sku: str) -> InventoryOutput:
11    return InventoryOutput(sku=sku, available_units=42)
12
13agent = Agent(
14    name="Inventory planner",
15    model="gpt-5.6",
16    model_settings=ModelSettings(tool_choice="programmatic_tool_calling"),
17    tools=[get_inventory, ProgrammaticToolCallingTool()],
18)
19
20result = Runner.run_sync(agent, "Check desk-lamp inventory and summarize it.")
21print(result.final_output)

The generated program runs in a fresh hosted V8 environment. It has no Node.js APIs, filesystem, network, subprocess, or persistent JavaScript state. It can interact only with tools explicitly enabled for programmatic use. Use direct tool calling instead when a single call is enough, each result needs fresh model judgment, or the operation requires approval, citations, or native artifacts.

Security matters here. allowed_callers=["programmatic"] is an allowlist for invocation mode, not an authorization system for the underlying business action. Your function should still authenticate the end user, validate the arguments, apply rate limits, and enforce tenant boundaries. Keep programmatically callable tools read-only or narrowly scoped until you have tested replay, timeout, and abuse behavior.

The platform guide's Programmatic Tool Calling documentation is the authoritative reference for runtime constraints, retention, eligibility, and client-owned tool continuation.

Security and privacy checklist

Before production rollout:

• Pin openai-agents, mcp, and the HTTP client versions in a lockfile.
• Treat MCP servers as privileged integrations; use least-privilege tokens and read-only tools by default.
• Review sandbox mount paths and explicitly acknowledge credential exposure only where required.
• Do not serialize API keys or authority-bearing approval tokens into RunState.
• Verify redacted errors do not leak prompts, headers, command arguments, or tracebacks.
• Decide whether hosted program execution, MCP services, and third-party tools satisfy your data-retention requirements.
• Add a kill switch and a rollback path before changing the default model.

For voice and realtime systems, compare transcription settings against the production Realtime guide and run an end-to-end audio test; a successful text-agent test says nothing about your WebSocket or audio pipeline.

Common errors and debugging

MCP HTTP type errors. Inspect the installed mcp and httpx versions. If a custom auth or client factory was written for the v1 stack, migrate it to the v2-owned types or pin mcp<2 while you schedule the change.

Unexpected model behavior. Search for agents that omit model= and compare them with the previous baseline. Set OPENAI_DEFAULT_MODEL or an explicit model deliberately; do not let a package upgrade silently change an evaluated workflow.

Programmatic tool rejection. Confirm that the model is a supported Responses model, that only one ProgrammaticToolCallingTool is configured, and that at least one tool permits programmatic callers.

Resume runs lose context. Test serialization and restoration with the exact session backend used in production. Confirm that staged input is added once and that a retry cannot duplicate a side effect.

Sandbox startup fails. Read the validation message and review each mount's credential exposure. The new checks are designed to prevent accidental authority leaks, so bypassing the warning is the wrong fix.

Should you upgrade now?

Upgrade now in a staging environment if you need MCP v2 compatibility, durable human-in-the-loop input, or the reliability and sandbox hardening in 0.20.0. Pin the version and run a representative evaluation before allowing the new default model into production.

Delay the production rollout if your application has custom MCP HTTP clients, undocumented provider assumptions, or side-effecting tools without idempotency. In that case, first pin the current working dependency set, build an MCP migration test, and make the model selection explicit. The safest upgrade is boring: reproducible dependencies, read-only canaries, observable runs, and a rollback that does not depend on the agent behaving correctly.

FAQ

Is OpenAI Agents SDK 0.20.0 a breaking release?

It is a minor release in the project's 0.Y.Z scheme, but the maintainers call out a potentially breaking MCP dependency migration for applications with customized local HTTP transports. Basic integrations may upgrade cleanly, but custom authentication and client factories require review.

What is the new default model?

The implicit SDK default is gpt-5.6-luna. An explicit agent model, run-level override, or OPENAI_DEFAULT_MODEL takes precedence.

Does Programmatic Tool Calling run arbitrary code on my server?

No. The generated JavaScript runs in a fresh hosted V8 environment with no direct network, filesystem, Node.js, or subprocess access. It can call only tools that your request explicitly makes eligible.

Do I need MCP v2 to use the Agents SDK?

No. The SDK retains MCP v1 compatibility while adding support for MCP v2. If your custom HTTP integration is not ready, pinning mcp<2 is a documented temporary option while you migrate.

Is an approval message enough to authorize an agent action?

No. Approval text is data. The application and the tool must enforce identity, authorization, scope, idempotency, and any human-approval requirement at the side-effect boundary.

Conclusion

OpenAI Agents SDK 0.20.0 is best understood as a production-infrastructure release: it changes the default model, modernizes local MCP connectivity, improves resumable state, and tightens sandbox boundaries. Programmatic Tool Calling adds a powerful way to coordinate bounded tool workflows, but its isolation does not replace application authorization.

The migration path is straightforward when you make behavior explicit: pin dependencies, pin the model when reproducibility matters, test custom MCP transports, keep side effects behind real permission checks, and canary the upgrade with traces and rollback. That discipline matters more than the version number—and it is what turns a promising agent SDK into a dependable system.

Sources

• OpenAI Agents SDK 0.20.0 release notes
• OpenAI Agents SDK release changelog
• OpenAI Agents SDK tools documentation
• OpenAI Programmatic Tool Calling guide
• openai-agents 0.20.0 on PyPI
• Vercel AI SDK OpenAI provider documentation

Visual: original Mermaid architecture diagram by Essa Mamdani, based on the cited official SDK and platform documentation.

Visual: Integration request flow

This original architecture diagram shows how the components described in this article fit together. It is a practical reference for deciding where authentication, validation, retries, and observability belong.

Visual reading: keep the client, policy boundary, external service, and result validation separate. This prevents an AI-generated tool call from becoming an unchecked side effect.