NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #703 most downloaded on PyPI
OpenAI Agents SDK
Last release 11 days ago
17 Sep 2026
Ships fairly regularly
a new release about every 1 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
2 years old
122 releases · first in 2025
One column per month.
This version adds WebSocket mode support for OpenAI's Responses API. This is a new opt-in feature, so the default behavior is unchanged. If you want t
This version adds WebSocket mode support for OpenAI's Responses API. This is a new opt-in feature, so the default behavior is unchanged. If you want to switch all Responses API calls to WebSocket mode, call set_default_openai_responses_transport("websocket") to enable it for all OpenAI Responses model agents.
You can also use either OpenAIProvider along with use_responses_websocket=True or responses_websocket_session() utility to enable a reusable WebSocket connection, as shown below:
import asyncio
from agents import Agent, responses_websocket_session
async def main():
agent = Agent(name="Assistant", instructions="Be concise.")
async with responses_websocket_session() as ws:
first = ws.run_streamed(agent, "Say hello in one short sentence.")
async for _event in first.stream_events():
pass
second = ws.run_streamed(
agent,
"Now say goodbye.",
previous_response_id=first.last_response_id,
)
async for _event in second.stream_events():
pass
asyncio.run(main())
References:
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.9.3...v0.10.0
fix: strip #2518 total_tokens from OpenAI tracing usage payloads by @seratch in https://github.com/openai/openai-agents-python/pull/2521
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.9.2...v0.9.3
To mitigate 400 errors caused by an inconsistent set of items when using reasoning models, this release introduces the reasoning_item_id_policy: 'omit
To mitigate 400 errors caused by an inconsistent set of items when using reasoning models, this release introduces the reasoning_item_id_policy: 'omit' option to RunConfig. This is a new, opt-in option, so the default behavior is unchanged.
run_config = RunConfig(reasoning_item_id_policy="omit")
result = await Runner.run(
agent,
"Tell me about recursion in programming.",
run_config=run_config,
)
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.9.1...v0.9.2
fix: materialize iterable input history in ItemHelpers.input_to_new_input_list by @seratch in https://github.com/openai/openai-agents-python/pull/2496
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.9.0...v0.9.1
Since Python 3.9 is EOLed three months ago, this SDK no longer support the version. Please upgrade to Python 3.10 or newer.
Since Python 3.9 is EOLed three months ago, this SDK no longer support the version. Please upgrade to Python 3.10 or newer.
Now you can pass the following options to customize function tool behavior:
Agent#as_tool() now returns FunctionToolAdditionally, the type hint for the value returned from the Agent#as_tool() method has been narrowed from Tool to FunctionTool. This change should not usually cause breaking issues, but if your code relies on the broader union type, you may need to make some adjustments on your side.
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.8.4...v0.9.0
This release includes the hosted shell runtime tool along with its native skills support. Developers now can pass a container-based shell runtime with
This release includes the hosted shell runtime tool along with its native skills support. Developers now can pass a container-based shell runtime with skills this way:
from agents import Agent, ShellTool
agent = Agent(
name="Shell Agent",
model="gpt-5.2",
instructions="Use the available shell tool to answer user requests.",
tools=[
ShellTool(
environment={
"type": "container_auto",
"network_policy": {"type": "disabled"},
"skills": [
{
"type": "skill_reference",
"skill_id": "skill_698bbe879adc81918725cbc69dcae7960bc5613dadaed377",
"version": "1",
}
],
}
)
],
)
Refer to examples/tools/container_shell_inline_skill.py and examples/tools/container_shell_skill_reference.py for more details.
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.8.3...v0.8.4
Support model_version param for turn detection in realtime agents sdk by @jhills20 in https://github.com/openai/openai-agents-python/pull/2450
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.8.2...v0.8.3
feat: support Annotated[T, Field(...)] in function schema by @haasonsaas in https://github.com/openai/openai-agents-python/pull/2435
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.8.1...v0.8.2
feat: add run-context thread reuse for codex_tool by @seratch in https://github.com/openai/openai-agents-python/pull/2425
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.8.0...v0.8.1
The human-in-the-loop (HITL) flow enables your agents to pause execution until a person approves or rejects sensitive tool calls. Tools declare when t
The human-in-the-loop (HITL) flow enables your agents to pause execution until a person approves or rejects sensitive tool calls. Tools declare when they need approval, run results surface pending approvals as interruptions, and RunState lets you serialize and resume runs after decisions are made.
import asyncio
from agents import Agent, Runner, RunState, function_tool
@function_tool
async def get_weather(city: str) -> str:
return f"The weather in {city} is sunny"
# This function requires approval
@function_tool(needs_approval=True)
async def get_temperature(city: str) -> str:
return f"The temperature in {city} is 20° Celsius"
agent = Agent(
name="Weather Assistant",
instructions="You are a helpful weather assistant. Answer questions about weather and temperature using the available tools.",
tools=[get_weather, get_temperature],
)
async def main():
result = await Runner.run(agent, "What is the weather and temperature in Oakland?")
has_interruptions = len(result.interruptions) > 0
while has_interruptions:
state = result.to_state()
# Process each interruption
for interruption in result.interruptions:
print("\nTool call details:")
print(f" Agent: {interruption.agent.name}")
print(f" Tool: {interruption.name}")
print(f" Arguments: {interruption.arguments}")
confirmed = await confirm("\nDo you approve this tool call?")
if confirmed:
print(f"✓ Approved: {interruption.name}")
state.approve(interruption)
else:
print(f"✗ Rejected: {interruption.name}")
state.reject(interruption)
# Resume execution with the updated state
print("\nResuming agent execution...")
result = await Runner.run(agent, state)
has_interruptions = len(result.interruptions) > 0
print(result.final_output)
Refer to the document page and examples for more details.
In this version, two runtime behavior changes may require migration work:
asyncio.to_thread(...) instead of running on the event loop thread. If your tool logic depends on thread-local state or thread-affine resources, migrate to an async tool implementation or make thread affinity explicit in your tool code.mcp_config={"failure_error_function": None}. Server-level failure_error_function values override the agent-level setting, so set failure_error_function=None on each local MCP server that has an explicit handler.Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.7.0...v0.8.0
The nested handoffs behavior were enabled by default in v0.6.0. Now, it is now disabled by default. To enable it again, you need to set the nest_hando
The nested handoffs behavior were enabled by default in v0.6.0. Now, it is now disabled by default. To enable it again, you need to set the nest_handoff_history option to True.
from agents import Agent, MCPServerManager, RunConfig, Runner
agent = Agent(name="My agent", instructions="Be creative")
result = await Runner.run(
agent,
input="Hey, can you tell me something interesting about Japan?",
run_config=RunConfig(nest_handoff_history=True),
)
Starting with this version, there is a new, convenient way to manage multiple MCP server instances. See https://github.com/openai/openai-agents-python/pull/2350 and examples/mcp/manager_example.
from contextlib import asynccontextmanager
from fastapi import FastAPI
from agents import Agent, Runner
from agents.mcp import MCPServerManager, MCPServerStreamableHttp
@asynccontextmanager
async def lifespan(app: FastAPI):
async with MCPServerManager(
servers=[
MCPServerStreamableHttp({"url": 'http://localhost:8001/mcp'}),
MCPServerStreamableHttp({"url": 'http://localhost:8002/mcp'}),
],
connect_in_parallel=True,
) as manager:
app.state.mcp_manager = manager
yield
app = FastAPI(lifespan=lifespan)
@app.post("/agent")
async def run_agent(req) -> dict[str, object]:
agent = Agent(
name="Test Agent",
instructions="Use the MCP tools when needed.",
mcp_servers= app.state.mcp_manager.active_servers,
)
result = await Runner.run(starting_agent=agent, input=build_query(req))
return {"output": result.final_output}
session_input_callback used to be required to be provided. Now, it is optional and the default behavior is to append the new input to the session history.Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.9...v0.7.0
feat: #2333 support input-based responses compaction with store-aware auto mode by @seratch in https://github.com/openai/openai-agents-python/pull/233
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.8...v0.6.9
Enhance exception handling in MCP server initialization and cleanup by @habema in https://github.com/openai/openai-agents-python/pull/2268
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.7...v0.6.8
feat: add experimental Codex extension and tool by @seratch in https://github.com/openai/openai-agents-python/pull/2320
Starting with this version, we have added a new experimental Codex extension (agents.extensions.experimental.codex). This extension allows you to use Codex as a tool within your agents. Since this module is still experimental, its behavior and implementation details may change in future releases.
If you run an agent with codex_tool() on a host where Codex is installed, the agent will use Codex as a tool to answer the question. The tool simply runs the Codex CLI as a subprocess, so all existing Codex configuration, skills, and capabilities are available without any additional setup.
See the example code and https://github.com/openai/openai-agents-python/pull/2320 for more details.
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.6...v0.6.7
fix: bump litellm to resolve pydantic deprecation warnings by @seratch in https://github.com/openai/openai-agents-python/pull/2292
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.5...v0.6.6
Add per-run tracing API key support by @rm-openai in https://github.com/openai/openai-agents-python/pull/2260
for loop by @aniketmaurya in https://github.com/openai/openai-agents-python/pull/2209Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.4...v0.6.5
feat: Add on_stream to agents as tools by @seratch in https://github.com/openai/openai-agents-python/pull/2169
examples/basic/stream_items.py by @habema in https://github.com/openai/openai-agents-python/pull/2174Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.3...v0.6.4
feat: preserve logprobs from chat completions API in ModelResponse by @JRMeyer in https://github.com/openai/openai-agents-python/pull/2134
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.2...v0.6.3
fix: allow static tool filtering without agent and run_context in MCPServer by @sevakva in https://github.com/openai/openai-agents-python/pull/2108
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.1...v0.6.2
fix: invalid model setting when passing prompt to Agent by @seratch in https://github.com/openai/openai-agents-python/pull/1852
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.0...v0.6.1
Handoff behavior has a breaking change in this version. Specifically, the message history is now collapsed into a single message when handing off to a…
Handoff behavior has a breaking change in this version. Specifically, the message history is now collapsed into a single message when handing off to a new agent. We have verified and evaluated this behavior and think it works better, but recommend testing with your agents before upgrading to v0.6.0 in production.
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.5.1...v0.6.0
Key update is support for new tools from the GPT-5.1 launch: shell and apply_patch.
Key update is support for new tools from the GPT-5.1 launch: shell and apply_patch.
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.5.0...v0.5.1
This version doesn’t introduce any visible breaking changes, but it includes new features and a few significant updates under the hood:
This version doesn’t introduce any visible breaking changes, but it includes new features and a few significant updates under the hood:
RealtimeRunner to handle SIP protocol connectionsRunner#run_sync for Python 3.14 compatibilityFull Changelog: https://github.com/openai/openai-agents-python/compare/v0.4.2...v0.5.0
fix: #1764 enable developers to pass custom reasoning effort for LiteLLM providers by @seratch in https://github.com/openai/openai-agents-python/pull/
make format before committing) by @filintod in https://github.com/openai/openai-agents-python/pull/1979Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.4.1...v0.4.2
Add breaking change notes in docs by @seratch in https://github.com/openai/openai-agents-python/pull/1894
_fix_tool_message_ordering for all Anthropic models by @habema in https://github.com/openai/openai-agents-python/pull/1936Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.4.0...v0.4.1
In this version, openai package v1.x versions are no longer supported. Please use openai v2.x along with this SDK.
In this version, openai package v1.x versions are no longer supported. Please use openai v2.x along with this SDK.
_remove_not_given() for litellm model by @HareeshBahuleyan in https://github.com/openai/openai-agents-python/pull/1893AdvancedSQLiteSession and refactor session docs by @habema in https://github.com/openai/openai-agents-python/pull/1791Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.3.3...v0.4.0
Feat: Add AdvancedSQLiteSession with conversation branching & usage tracking by @habema in https://github.com/openai/openai-agents-python/pull/1662
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.3.2...v0.3.3
fix #1750 better error message when passing AgentHooks to Runner by @seratch in https://github.com/openai/openai-agents-python/pull/1752
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.3.1...v0.3.2
Update all translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/1720
user_agent_override contextmanager by @jiwon-oai in https://github.com/openai/openai-agents-python/pull/1768Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.3.0...v0.3.1
New realtime updates based on the GA Realtime API
make old_version_tests by @habema in https://github.com/openai/openai-agents-python/pull/1710Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.11...v0.3.0
fix: Fix #1640 openai package breaking changes by @seratch in https://github.com/openai/openai-agents-python/pull/1641
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.10...v0.2.11
Performance: only create the OpenAIRealtimeServerEvent TypeAdapter once by @michieldwitte in https://github.com/openai/openai-agents-python/pull/1548
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.9...v0.2.10
Fix #1494 by adding a link to Responses API documentation by @seratch in https://github.com/openai/openai-agents-python/pull/1502
tool_use_behavior and simplify description of stop_on_first_tool behavior by @Abishai-kashif in https://github.com/openai/openai-agents-python/pull/1510Full Changelog: https://github.com/openai/openai-agents-python/compare/0.2.8...v0.2.9
Fix: Clarify random_number function docstring for inclusive range by @Abbas-Asad in https://github.com/openai/openai-agents-python/pull/1475
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.7...0.2.8
Added runtime validation for Agent constructor arguments by @DanielHashmi in https://github.com/openai/openai-agents-python/pull/998
is_enabled parameter in handoff() documentation by @Hafiz-Muhammad-Umar12 in https://github.com/openai/openai-agents-python/pull/1472Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.6...v0.2.7
feat: support agent output guardrails in realtime by @jhills20 in https://github.com/openai/openai-agents-python/pull/1381
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.5...v0.2.6
Fix tag errors in sessions document page by @seratch in https://github.com/openai/openai-agents-python/pull/1307
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.4...v0.2.5
Add automation script to generate mkdocstrings files by @seratch in https://github.com/openai/openai-agents-python/pull/1048
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.3...v0.2.4
[realtime] Add direct access to model layer from session by @rm-openai in https://github.com/openai/openai-agents-python/pull/1172
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.2...v0.2.3
Add a new GH Actions job to automatically update translated document pagse by @seratch in https://github.com/openai/openai-agents-python/pull/598
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.1...v0.2.2
Realtime agents are now available. Note that this is in Beta and may have bugs, please report them!
structuredContent in MCP tool results.Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.2.0...v0.2.1
Please note that this version includes a small breaking change (breaks Agent into AgentBase + Agent), hence the minor version bump. See https://openai…
Please note that this version includes a small breaking change (breaks Agent into AgentBase + Agent), hence the minor version bump. See https://openai.github.io/openai-agents-python/release/ for the breaking change changelog.
Key changes include:
Sessions, a way to manage conversation sessions.Field annotations in tool arguments (for tools decorated with @function_schema) by @georg-wolflein in https://github.com/openai/openai-agents-python/pull/1124Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.1.0...v0.2.0
Please note that this version includes a small breaking change to MCP servers, hence the minor version bump. See https://openai.github.io/openai-agent…
Please note that this version includes a small breaking change to MCP servers, hence the minor version bump. See https://openai.github.io/openai-agents-python/release/ for the breaking change changelog.
store=False by @niv-hertz in https://github.com/openai/openai-agents-python/pull/920__init__.py by @Lightblues in https://github.com/openai/openai-agents-python/pull/897parallel_tool_calls Attribute in ModelSettings by @Rehan-Ul-Haq in https://github.com/openai/openai-agents-python/pull/763on_trace_end docstring by @shirazkk in https://github.com/openai/openai-agents-python/pull/958Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.19...v0.1.0
Make Runner an abstract base class by @pakrym-oai in https://github.com/openai/openai-agents-python/pull/720
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.18...v0.0.19
Added support for dynamic prompt templates via the OpenAI Prompts feature
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.17...v0.0.18
fix Gemini token validation issue with LiteLLM by @handrew in https://github.com/openai/openai-agents-python/pull/735
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.16...v0.0.17
Biggest change is support for new hosted tools - remote MCP, code interpreter, image generator and local shell.
Biggest change is support for new hosted tools - remote MCP, code interpreter, image generator and local shell.
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.15...v0.0.16
Main big change is support for Streamable HTTP in MCP servers.
Main big change is support for Streamable HTTP in MCP servers.
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.14...v0.0.15
Add usage to context in streaming by @rm-openai in https://github.com/openai/openai-agents-python/pull/595
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.13...v0.0.14
Adding extra_headers parameters to ModelSettings by @jonnyk20 in https://github.com/openai/openai-agents-python/pull/550
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.12...v0.0.13
Use any model via litellm: Agent(model="litellm/ / ") e.g. Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620")
Agent(model="litellm/<provider>/<model_name>") e.g. Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620")Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.11...v0.0.12
Examples and tests for previous_response_id by @rm-openai in https://github.com/openai/openai-agents-python/pull/512
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.10...v0.0.11
You can use previous_response_id from the OpenAI API: https://platform.openai.com/docs/api-reference/responses/create#responses-create-previous_respon
previous_response_id from the OpenAI API: https://platform.openai.com/docs/api-reference/responses/create#responses-create-previous_response_idcomputer-use example to support simultaneous key presses by @KanchiShimono in https://github.com/openai/openai-agents-python/pull/452extra_query and extra_body by @DanieleMorotti in https://github.com/openai/openai-agents-python/pull/500Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.9...v0.0.10
add links and mcp + voice examples by @jhills20 in https://github.com/openai/openai-agents-python/pull/438
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.8...v0.0.9
MCP example for SSE by @rm-openai in https://github.com/openai/openai-agents-python/pull/354
tracing.md by @alizenhom in https://github.com/openai/openai-agents-python/pull/371SpeechSpanData by @tcdent in https://github.com/openai/openai-agents-python/pull/386Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.7...v0.0.8
Reset tool use behavior when tool_choice is set
tool_choice is setfetch_ordered_spans and fetch_traces for stronger tests by @alexmojaki in https://github.com/openai/openai-agents-python/pull/288Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.6...v0.0.7
add examples section to docs by @jhills20 in https://github.com/openai/openai-agents-python/pull/242
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.5...v0.0.6
Fix breaking changes from openai 1.66.2 by @rm-openai in https://github.com/openai/openai-agents-python/pull/232
inline-snapshot by @alexmojaki in https://github.com/openai/openai-agents-python/pull/25Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.4...v0.0.5
Fix: Multi-agent design patterns link by @arnavsharma93 in https://github.com/openai/openai-agents-python/pull/29
spans and traces correctly by @the-praxs in https://github.com/openai/openai-agents-python/pull/55Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.3...v0.0.4
Updating screenshot to CDN link by @dmitry-openai in https://github.com/openai/openai-agents-python/pull/1
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.0.2...v0.0.3
Your coding agent can read these notes before it upgrades. Set up the MCP server →