◆ AI Agent Frameworks

OpenAI Agents SDK

v0.21.1 open-source

A lightweight, powerful framework for multi-agent workflows

source ↗ website ↗ rss ↗ last repo push Aug 20, 2026

from agents import Runner
from agents.run import RunState

# After an interrupted run returns a RunState:
state: RunState = ...
state.add_input("The approval code is XYZ-42.")

result = await Runner.run(starting_agent=agent, input=state)
from agents.decorators import tool

@tool
def get_weather(city: str) -> str:
    """Return current weather for the given city."""
    return fetch_weather_api(city)
from agents.decorators import tool

@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"Sunny in {city}"

from agents import Agent, Runner
agent = Agent(name="WeatherBot", instructions="Answer weather questions.", tools=[get_weather])
print(Runner.run_sync(agent, "What is the weather in Tokyo?").final_output)
from pathlib import Path
from agents.sandbox import Manifest, SandboxPathGrant
from agents.sandbox.entries import Dir, LocalDir

TRUSTED_DOCS_ROOT = Path("/opt/my-app/docs")

manifest = Manifest(
    extra_path_grants=(
        SandboxPathGrant(path=str(TRUSTED_DOCS_ROOT), read_only=True),
    ),
    entries={
        "fixtures": LocalDir(src=Path("fixtures"), description="Local test fixtures."),
        "docs": LocalDir(src=TRUSTED_DOCS_ROOT, description="Trusted local documents."),
        "output": Dir(description="Generated artifacts."),
    },
)
agent = Agent(
    name="Assistant",
    mcp_servers=[my_mcp_server],
    mcp_config={"include_server_in_tool_names": True},
)
OPENAI_DEFAULT_MODEL=gpt-4.1 python my_agent.py
result = Runner.run_sync(
    agent,
    input,
    error_handlers={"model_refusal": lambda data: data.error.refusal},
)
# Given a tool item from an agent run result
for item in result.tool_items:
    print(item.tool_name)  # e.g. 'search_web'
    print(item.call_id)    # e.g. 'call_abc123'
from agents import flush_traces

await flush_traces()
from agents.tools import WebSearchTool

search_tool = WebSearchTool(external_web_access=True)
session_id = mcp_server.session_id
model = LiteLLMModel(..., should_replay_reasoning_content=True)
resources = await mcp_server.list_resources()
content = await mcp_server.read_resource(resources[0].uri)
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())
run_config = RunConfig(reasoning_item_id_policy="omit")
result = await Runner.run(
    agent,
    "Tell me about recursion in programming.",
    run_config=run_config,
)
from agents import function_tool, ToolTimeoutBehavior

@function_tool(timeout_seconds=5.0, timeout_behavior="error_as_result")
def slow_lookup(query: str) -> str:
    ...  # long-running external call
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",
                    }
                ],
            }
        )
    ],
)
from typing import Annotated
from pydantic import Field
from agents import function_tool

@function_tool
def search(query: Annotated[str, Field(description="The search query", min_length=1)]) -> str:
    return f"Results for: {query}"
from agents import function_tool, ToolContext

@function_tool
def my_tool(ctx: ToolContext, input: str) -> str:
    agent = ctx.agent  # the agent invoking this tool
    return f"Called by agent: {agent.name}, input: {input}"
@function_tool(needs_approval=True)
async def delete_record(record_id: str) -> str:
    # Only runs after a human approves
    return f"Record {record_id} deleted"

result = await Runner.run(agent, "Delete record 42")
for interruption in result.interruptions:
    state = result.to_state()
    if await confirm(f"Approve {interruption.name}({interruption.arguments})?"):
        state.approve(interruption)
    else:
        state.reject(interruption)
result = await Runner.run(agent, state)
agent = Agent(
    name="My Agent",
    instructions="...",
    tools=[...],
    mcp_config={"failure_error_function": None},
)
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=req.query)
    return {"output": result.final_output}
from agents import Agent, 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),
)
from agents import Agent, Runner
from agents.extensions.experimental.codex import codex_tool

agent = Agent(
    name="codex-agent",
    tools=[codex_tool()],
)

result = Runner.run_sync(agent, "Refactor this function to use async/await")
print(result.final_output)
@function_tool(guardrails=[my_input_guardrail])
async def lookup_user(user_id: str) -> str:
    ...
async def on_agent_start(ctx: AgentHookContext, agent: Agent) -> None:
    print(f'Turn input: {ctx.turn_input}')
tool = child_agent.as_tool(
    tool_name="research",
    tool_description="Research a topic",
    failure_error_function=lambda ctx, exc: f"Research failed: {exc}"
)
tool = child_agent.as_tool(
    tool_name="summarizer",
    tool_description="Summarize a document",
    on_stream=lambda event: print(event)
)
from agents import Agent, ModelSettings

agent = Agent(
    name='my-agent',
    model='gpt-4o',
    model_settings=ModelSettings(prompt_cache_retention=300),
)
import httpx
from agents.mcp import MCPServerStreamableHttp

server = MCPServerStreamableHttp(
    url="https://my-mcp-server.example.com/mcp",
    httpx_client_factory=lambda: httpx.AsyncClient(timeout=30.0, headers={"Authorization": "Bearer <token>"}),
)
class MyHooks(RunHooks):
    async def on_tool_start(self, context: ToolContext, agent: Agent, tool: Tool) -> None:
        print(f"Tool '{tool.name}' called with args: {context.tool_call_arguments}")
from typing import Annotated
from agents import function_tool

@function_tool
def search(query: Annotated[str, "The search query, max 200 chars"]) -> str:
    ...
from typing import Annotated
from agents import function_tool

@function_tool
def search(query: Annotated[str, 'The search query to look up'], max_results: Annotated[int, 'Maximum number of results to return'] = 10) -> list[str]:
    ...
from agents import Agent, ModelSettings

agent = Agent(
    name='analyzer',
    model='gpt-4o',
    model_settings=ModelSettings(logprobs=True)
)
async for event in runner.stream():
    if event.type == 'tool_call_item':
        print('Tool invoked:', event.item)
    elif event.type == 'tool_call_output_item':
        print('Tool output:', event.item)
from pydantic import Field
from openai_agents import function_schema

@function_schema
def search_cve(cve_id: str = Field(..., description="CVE identifier, e.g. CVE-2024-1234"),
              severity: str = Field("high", description="Minimum severity filter")) -> str:
    ...
handoff = Handoff(agent=escalation_agent, is_enabled=lambda ctx: ctx.metadata.get('allow_escalation', False))
from agents import Agent, run_demo_loop

agent = Agent(name='Assistant', instructions='You are a helpful assistant.')

import asyncio
asyncio.run(run_demo_loop(agent))
from agents import Agent, RunContextWrapper, function_tool

@function_tool
def my_tool(ctx: RunContextWrapper, query: str) -> str:
    call_id = ctx.tool_call_id
    # use call_id for logging or stateful tracking
    return f'Handled call {call_id}: {query}'
from agents import FunctionTool

def lookup_order(order_id: str) -> str:
    return f"Order {order_id}: shipped"

tool = FunctionTool(
    name="lookup_order",
    description="Look up an order by ID",
    params_json_schema={"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]},
    on_invoke_tool=lookup_order,
    is_enabled=False  # disable until user is authenticated
)
from agents import ModelSettings

settings = ModelSettings(
    model="gpt-4o",
    extra_headers={"X-Custom-Header": "my-value", "X-Team-ID": "team-42"}
)
from agents import ModelSettings

settings = ModelSettings(model="gpt-4o", temperature=0.7)
print(settings.to_json_dict())
from agents import Agent

agent = Agent(
    name="claude-agent",
    model="litellm/anthropic/claude-3-5-sonnet-20240620",
    instructions="You are a helpful assistant.",
)
from agents import ModelSettings

settings = ModelSettings(
    extra_query={'my-param': 'value'},
    extra_body={'custom_field': True}
)
from agents import Agent, ModelSettings

agent = Agent(
    name="analyst",
    model="o3",
    model_settings=ModelSettings(
        store=True,
        reasoning={"effort": "high"},
        metadata={"session": "pentest-42", "owner": "red-team"}
    )
)
@function_tool(strict_mode=True)
def lookup_order(order_id: str) -> str:
    return fetch_order(order_id)
from agents import Agent

agent = Agent(
    name="Order Assistant",
    tools=[lookup_order],
    tool_use_behavior="stop_on_first_tool",
)

Summary

OpenAI Agents SDK is an open-source agent framework that facilitates building multi-agent workflows supporting various LLMs. It is a library imported into other code, intended for developers building orchestration logic, and its documentation positions it alongside general agent frameworks. The SDK allows for configuring agents with instructions, tools, and guardrails, offering features like sandbox and voice agents, along with built-in tracing for debugging runs. The project remains actively developed, supporting both Python and JavaScript/TypeScript versions.

A lightweight, powerful framework for multi-agent workflows

What OpenAI Agents SDK answers

Does it support using models other than OpenAI's?

it supports over a hundred LLMs in addition to the OpenAI APIs

What kind of actions can agents perform?

agents can use tools, which include functions, MCP, or hosted tools

What mechanisms exist for ensuring output quality?

configurable safety checks are available for input and output validation

What can I do if a task requires human intervention?

there are built-in mechanisms for involving humans across agent runs

How is conversation memory maintained across multiple runs?

the framework manages conversation history automatically across agent runs

Does the system provide visibility into execution flow?

it includes built-in tracking of agent runs, allowing viewing and debugging of workflows

Command line

composed command

option surface across analysed releases

options at that release added, per release removed, per release

option	found in	since	description

Values are placeholders taken from each option’s declared default. Nothing is executed here — the output shown is a recording of a run that already happened.

Release history

v0.21.1 Aug 16, 2026 · issue -003

OpenAI Agents SDK v0.21.1 adds model call timeouts, run-scoped sandbox working directories, Docker networking controls, and Modal resource options.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.21.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.21.1
```
- ›Adds model call timeouts to the core runner, letting callers bound how long a single model invocation can block.
- ›Adds run-scoped sandbox working directories so each run gets an isolated filesystem context inside the sandbox.
- ›Allows Docker sandboxes to disable networking, enabling air-gapped sandbox execution for sensitive workloads.
- ›Adds Modal sandbox resource options, exposing resource configuration (CPU, memory, GPU, etc.) for Modal-backed sandboxes.
v0.21.1 Aug 16, 2026 · issue 002

v0.21.1 adds model call timeouts, run-scoped sandbox working directories, Docker network isolation, and Modal resource options.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.21.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.21.1
```
- ›Adds run-scoped sandbox working directories so each agent run gets an isolated filesystem workspace inside a sandbox.
- ›Allows Docker sandboxes to disable networking, enabling air-gapped container execution for sensitive workloads.
- ›Adds Modal sandbox resource options, giving practitioners control over compute resources allocated to Modal-backed sandboxes.
- ›Adds model call timeouts to cap how long a single LLM call can block an agent run.
v0.21.0 Aug 15, 2026 · issue -004

Adds provider-neutral testing utilities across agents.testing, agents.realtime.testing, and agents.voice.testing, plus OpenAI Python v3 compatibility.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.21.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.21.0
```
- ›Adds agents.testing, agents.realtime.testing, and agents.voice.testing modules with scripted/deterministic test utilities for Agent, Sandbox, Realtime, and Voice workflows — no live provider requests required.
- ›Updates OpenAI provider compatibility to openai>=3.0.0,<4, including HTTPX2-aware request, response, transport, and exception handling.
- ›Adds configurable retry backoff ceiling for MCP connections.
- ›Adds managed_secrets support for referencing existing Runloop secrets in Sandbox sessions.
v0.21.0 Aug 15, 2026 · issue 002

Adds provider-neutral testing modules for Agent, Realtime, and Voice workflows plus OpenAI Python v3 / HTTPX2 compatibility.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.21.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.21.0
```
- ›Adds agents.testing, agents.realtime.testing, and agents.voice.testing modules with scripted model utilities for deterministic Agent, Sandbox, Realtime, and Voice workflow tests without live provider requests.
- ›Updates OpenAI provider compatibility to openai>=3.0.0,<4, adding HTTPX2-aware request, response, transport, and exception handling.
- ›Adds configurable retry backoff ceiling for MCP connections.
- ›Adds managed_secrets support for referencing existing Runloop secrets in Sandbox agents.
v0.20.0 Aug 11, 2026 · issue -008

OpenAI Agents SDK v0.20.0 switches the default model to gpt-5.6-luna, adds RunState.add_input() for durable pending input, MCP SDK v2 support, and GA realtime transcription settings.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.20.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.20.0
```
- ›Adds RunState.add_input() to stage durable user input before a resumed model call, with guardrail, persistence, and serialization support.
- ›Adds explicit mount credential-exposure acknowledgements to sandbox mount validation, with redacted error contracts that do not serialize credential authority.
- ›Supports MCP Python SDK v2 alongside v1 across stdio, SSE, and Streamable HTTP transports for local MCP connections.
- ›Supports GA transcription settings for gpt-live-transcribe, gpt-transcribe, and gpt-realtime-whisper in realtime input transcription.
- ›Passes run context to custom session implementations.
+3 moreshow less
- ›Preserves raw usage payloads from provider responses.
- ›Allows applications to approve unsafe replays explicitly.
- ›Changes the implicit default model to gpt-5.6-luna; explicit models, run-level overrides, and the OPENAI_DEFAULT_MODEL environment variable continue to take precedence.
└──▷ BREAKING ON UPGRADE
- !The implicit default model is now gpt-5.6-luna instead of the previous default; applications that relied on the old implicit default will use a different model on upgrade.
- !Applications using custom MCP HTTP authentication or client factories must use the HTTP types owned by the installed MCP major version (v1 or v2), or pin mcp<2, due to the MCP SDK v2 dependency migration.
v0.20.0 Aug 11, 2026 · issue 002

OpenAI Agents SDK v0.20.0 switches the default model to gpt-5.6-luna, adds RunState.add_input(), MCP SDK v2 support, and GA realtime transcription settings.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.20.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.20.0
```
└──▷ USE IT
Stage additional user input into a paused run before resuming it — useful when a human-in-the-loop step collects a reply that should be treated as durable conversation input.
python
```
from agents import Runner
from agents.run import RunState

# After an interrupted run returns a RunState:
state: RunState = ...
state.add_input("The approval code is XYZ-42.")

result = await Runner.run(starting_agent=agent, input=state)
```
- ›Adds RunState.add_input() to stage durable user input before a resumed model call, with guardrail, persistence, and serialization support.
- ›Supports MCP Python SDK v2 alongside v1 across stdio, SSE, and Streamable HTTP transports for local MCP connections.
- ›Adds explicit credential-exposure acknowledgements for sandbox mount configurations.
- ›Realtime input transcription now supports GA transcription settings for gpt-live-transcribe, gpt-transcribe, and gpt-realtime-whisper.
- ›Passes run context to custom session implementations.
+2 moreshow less
- ›Preserves raw usage payloads from provider responses.
- ›Allows applications to approve unsafe replays explicitly.
└──▷ BREAKING ON UPGRADE
- !The implicit default model is now gpt-5.6-luna (previously a different model); workloads that relied on the old default will use the new model on upgrade. Explicit model settings, run-level overrides, and OPENAI_DEFAULT_MODEL continue to take precedence.
- !Applications using custom MCP HTTP authentication or client factories must use the HTTP types owned by the installed MCP major version, or pin mcp<2.
v0.19.2 Aug 1, 2026 · issue -018

OpenAI Agents SDK v0.19.2 exposes original callables through wrapped functions for easier introspection.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.19.2 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.19.2
```
- ›Exposes the original callable via a wrapped attribute on wrapped functions, enabling runtime introspection of the underlying function.
v0.19.2 Aug 1, 2026 · issue 002

Exposes original callable through wrapped functions, enabling introspection of tool wrappers in the OpenAI Agents SDK.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.19.2 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.19.2
```
- ›Exposes the original callable via a wrapped attribute on wrapped functions, allowing introspection of the underlying tool implementation at runtime.
v0.19.1 Jul 29, 2026 · issue -021

OpenAI Agents SDK v0.19.1 adds native host path support in sandbox path grants.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.19.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.19.1
```
- ›Adds support for native host paths in sandbox path grants, enabling direct host filesystem access without path translation.
v0.19.1 Jul 29, 2026 · issue 002

OpenAI Agents SDK v0.19.1 adds native host path support in sandbox path grants.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.19.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.19.1
```
- ›Supports native host paths in sandbox path grants, allowing local filesystem directories to be granted directly to sandbox agents.
v0.19.0 Jul 27, 2026 · issue -023

OpenAI Agents SDK v0.19.0 adds Programmatic Tool Calling, a @tool decorator alias, and a Vercel cloud bucket mount strategy.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.19.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.19.0
```
└──▷ USE IT
Decorate a plain function as an agent tool using the new short-form @tool alias from the public agents.decorators module.
python
```
from agents.decorators import tool

@tool
def get_weather(city: str) -> str:
    """Return current weather for the given city."""
    return fetch_weather_api(city)
```
- ›Adds agents.tool.ProgrammaticToolCallingTool class, enabling supported OpenAI Responses models to generate JavaScript to coordinate eligible tools, with per-tool allowed_callers, structured function-tool outputs, and integration with Runner streaming, guardrails, approvals, sessions, and RunState.
- ›Adds the public agents.decorators module and a shorter @tool alias alongside existing function and guardrail decorators.
- ›Extends function tools to support async callable objects in addition to plain async functions.
- ›Adds VercelCloudBucketMountStrategy for sandbox sessions, excluding bucket contents from workspace persistence.
- ›SDK configuration now consistently accepts either typed settings objects or plain dictionaries across agents, runs, models, sessions, sandboxes, and voice pipelines, with validation for unknown settings.
v0.19.0 Jul 27, 2026 · issue 002

OpenAI Agents SDK v0.19.0 adds Programmatic Tool Calling, a @tool decorator alias, and a VercelCloudBucketMountStrategy.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.19.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.19.0
```
└──▷ USE IT
Define a function tool with the new shorter @tool decorator alias from the public agents.decorators module.
python
```
from agents.decorators import tool

@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"Sunny in {city}"

from agents import Agent, Runner
agent = Agent(name="WeatherBot", instructions="Answer weather questions.", tools=[get_weather])
print(Runner.run_sync(agent, "What is the weather in Tokyo?").final_output)
```
- ›Adds agents.tool.ProgrammaticToolCallingTool, enabling supported OpenAI Responses models to generate JavaScript to coordinate eligible tools, with support for per-tool allowed_callers, structured function-tool outputs, and integration with Runner streaming, guardrails, approvals, sessions, and RunState.
- ›Adds the public agents.decorators module and a shorter @tool alias alongside existing function and guardrail decorators.
- ›Supports async callable objects as function tools.
- ›Adds VercelCloudBucketMountStrategy for sandbox session mounting; mounted sessions exclude bucket contents from workspace persistence and do not support dynamic mount changes or session resume.
- ›SDK configuration now consistently accepts either typed settings objects or plain dictionaries across agents, runs, models, sessions, sandboxes, and voice pipelines, with validation for unknown settings.
v0.18.3 Jul 17, 2026 · issue -033

OpenAI Agents SDK v0.18.3 adds configurable tracing spans and realtime response usage tracking in session context.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.18.3 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.18.3
```
- ›Enables configuration of task and turn tracing spans, giving developers control over how agent execution is traced.
- ›Tracks response usage in realtime session context, making token and resource consumption visible within a session.
v0.18.2 Jul 11, 2026 · issue -039

OpenAI Agents SDK v0.18.2 adds GPT-5.6 request controls and hosted multi-agent beta support.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.18.2 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.18.2
```
- ›Adds GPT-5.6 request controls support to the SDK.
- ›Adds hosted multi-agent beta support.
v0.18.1 Jul 9, 2026 · issue -041

OpenAI Agents SDK v0.18.1 adds GPT-4.1 model defaults and migrates examples to the new defaults.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.18.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.18.1
```
- ›Adds GPT-5.6 model defaults and migrates bundled examples to use them.
v0.18.0 Jul 7, 2026 · issue -043

RealtimeAgent defaults to gpt-realtime-2.1 and SQLAlchemySession gains a Unicode storage option.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.18.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.18.0
```
- ›Adds Unicode storage option to SQLAlchemySession for broader character-set support in session persistence.
- ›Changes the default model for RealtimeAgent to gpt-realtime-2.1.
└──▷ BREAKING ON UPGRADE
- !The default model for RealtimeAgent is now gpt-realtime-2.1; any existing code that relied on the previous default model will silently switch behaviour on upgrade.
v0.17.8 Jul 6, 2026 · issue -044

OpenAI Agents SDK v0.17.8 adds an invalid final output recovery handler for more resilient agent runs.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.17.8 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.17.8
```
- ›Adds an invalid final output recovery handler, letting agents recover gracefully when a run produces a final output that fails validation.
v0.17.7 Jun 24, 2026 · issue -056

v0.17.7 adds configurable WebSocket max_size and buffered Chat Completions tool-call streaming.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.17.7 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.17.7
```
- ›Exposes a configurable max_size limit for WebSocket connections, allowing callers to raise or lower the message-size cap.
- ›Adds buffered Chat Completions tool-call streaming, delivering complete tool-call payloads as a single event rather than fragmenting them across stream chunks.
v0.17.6 Jun 19, 2026 · issue -061

OpenAI Agents SDK v0.17.6 adds pre-approval tool input guardrails and SDK-only custom data for tool outputs.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.17.6 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.17.6
```
- ›Adds pre-approval tool input guardrails, enabling validation or interception of tool inputs before a tool call is executed.
- ›Adds SDK-only custom data for tool outputs, allowing developers to attach arbitrary metadata to tool results without affecting the JSON-compatible contract sent to the model.
v0.17.4 May 26, 2026 · issue -085

OpenAI Agents SDK v0.17.4 adds support for Realtime custom voice objects.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.17.4 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.17.4
```
- ›Supports custom voice objects in the Realtime API integration.
v0.17.0 May 8, 2026 · issue -103

OpenAI Agents SDK v0.17.0 defaults RealtimeAgent to gpt-realtime-2 and tightens sandbox path controls via SandboxPathGrant
└──▷ GET THIS VERSION
```
$ git clone --branch v0.17.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.17.0
```
└──▷ USE IT
Grant a trusted host directory outside the SDK process base_dir so a sandbox manifest can read it as a LocalDir source.
python
```
from pathlib import Path
from agents.sandbox import Manifest, SandboxPathGrant
from agents.sandbox.entries import Dir, LocalDir

TRUSTED_DOCS_ROOT = Path("/opt/my-app/docs")

manifest = Manifest(
    extra_path_grants=(
        SandboxPathGrant(path=str(TRUSTED_DOCS_ROOT), read_only=True),
    ),
    entries={
        "fixtures": LocalDir(src=Path("fixtures"), description="Local test fixtures."),
        "docs": LocalDir(src=TRUSTED_DOCS_ROOT, description="Trusted local documents."),
        "output": Dir(description="Generated artifacts."),
    },
)
```
- ›Adds SandboxPathGrant to Manifest.extra_path_grants so trusted host paths outside the SDK process base_dir can be explicitly granted (optionally read_only=True) for sandbox source materialization.
- ›Changes the default model for RealtimeAgent sessions to gpt-realtime-2.
└──▷ BREAKING ON UPGRADE
- !Sandbox local source materialization now constrains LocalFile.src and LocalDir.src to the SDK process current working directory (base_dir) unless the path is covered by Manifest.extra_path_grants. Applications that copy host files or directories from outside base_dir into a sandbox workspace must add a SandboxPathGrant for each trusted host root.
v0.16.0 May 7, 2026 · issue -104

OpenAI Agents SDK v0.16.0 adds MCP server-prefixed tool names, per-run tool concurrency config, and an unlimited-turns mode.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.16.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.16.0
```
└──▷ USE IT
Prevent tool name collisions when two MCP servers expose tools with the same name by prefixing each tool with its server name.
python
```
agent = Agent(
    name="Assistant",
    mcp_servers=[my_mcp_server],
    mcp_config={"include_server_in_tool_names": True},
)
```
Keep the previous default model for all runs without changing every Agent instantiation.
```
$ OPENAI_DEFAULT_MODEL=gpt-4.1 python my_agent.py
```
- ›Adds include_server_in_tool_names to MCPConfig (set True) to prefix each MCP tool name with its server name, preventing collisions when multiple MCP servers expose identically named tools.
- ›Adds ToolExecutionConfig(max_function_tool_concurrency=...) on RunConfig to cap SDK-side local function tool execution concurrency independently of the provider-side ModelSettings.parallel_tool_calls setting.
- ›Adds max_turns=None to the run API to disable the turn limit entirely, while preserving the existing default of DEFAULT_MAX_TURNS (10) when max_turns is omitted.
- ›Adds OPENAI_DEFAULT_MODEL environment variable as a global override for the SDK default model, allowing the previous gpt-4.1 behavior to be restored without per-agent code changes.
└──▷ BREAKING ON UPGRADE
- !The SDK default model is changed from gpt-4.1 to gpt-5.4-mini; agents and runs that do not explicitly set a model will now use gpt-5.4-mini, which implicitly applies GPT-5 defaults including reasoning.effort="none" and verbosity="low".
v0.15.2 May 6, 2026 · issue -105

OpenAI Agents SDK v0.15.2 adds a context management model setting for finer control over conversation context.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.15.2 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.15.2
```
- ›Adds a context management model setting to control how conversation context is managed within a session.
v0.15.1 May 2, 2026 · issue -109

OpenAI Agents SDK v0.15.1 exposes WebSocket keepalive options for the Responses API connection.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.15.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.15.1
```
- ›Exposes WebSocket keepalive options for the Responses API, giving callers control over connection liveness behavior.
v0.15.0 May 1, 2026 · issue -110

OpenAI Agents SDK v0.15.0 surfaces model refusals as ModelRefusalError with a new model_refusal error handler.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.15.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.15.0
```
└──▷ USE IT
Handle a model refusal gracefully instead of letting ModelRefusalError propagate — useful in production pipelines where a refusal should yield a fallback value rather than crash.
python
```
result = Runner.run_sync(
    agent,
    input,
    error_handlers={"model_refusal": lambda data: data.error.refusal},
)
```
- ›Adds ModelRefusalError exception type so model refusals are raised explicitly instead of producing an empty final_output or looping until MaxTurnsExceeded.
- ›Adds model_refusal key to the error_handlers dict in Runner.run_sync / Runner.run to intercept refusals and return a custom value — including a value matching the agent's output schema for structured-output agents.
└──▷ BREAKING ON UPGRADE
- !Code that expected a refusal-only model response to complete with final_output == "" will now receive a ModelRefusalError instead; a model_refusal run error handler must be provided to suppress the exception.
v0.14.7 Apr 28, 2026 · issue -113

Adds tool_name and call_id convenience properties to tool items in the OpenAI Agents SDK.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.14.7 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.14.7
```
└──▷ USE IT
Access the tool name and call ID directly from a tool item when handling tool call results in an agent run.
python
```
# Given a tool item from an agent run result
for item in result.tool_items:
    print(item.tool_name)  # e.g. 'search_web'
    print(item.call_id)    # e.g. 'call_abc123'
```
- ›Adds tool_name and call_id convenience properties to tool items, making it easier to inspect tool call context without manual attribute lookup.
v0.14.5 Apr 23, 2026 · issue -118

OpenAI Agents SDK v0.14.5 adds an idle timeout option for Modal sandbox environments.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.14.5 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.14.5
```
- ›Adds an idle timeout option for Modal sandbox code execution environments, allowing control over how long a sandbox remains active without activity.
v0.14.4 Apr 21, 2026 · issue -120

OpenAI Agents SDK v0.14.4 adds BoxMount support for sandbox environments.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.14.4 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.14.4
```
- ›Adds BoxMount support for mounting box-based storage into sandbox environments.
v0.14.2 Apr 18, 2026 · issue -123

OpenAI Agents SDK v0.14.2 adds MongoDB session backend, sandbox extra path grants, and tool origin metadata on run items.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.14.2 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.14.2
```
- ›Adds MongoDB session backend via the extensions module, giving agents a persistent conversation store backed by MongoDB.
- ›Supports sandbox extra path grants, allowing additional filesystem paths to be granted to the code-execution sandbox.
- ›Persists tool origin metadata in run items, so downstream code can inspect which tool produced each item in a run.
v0.14.0 Apr 15, 2026 · issue -126

OpenAI Agents SDK v0.14.0 ships Sandbox Agents — persistent isolated workspaces with shell, filesystem, memory, snapshots, and hosted-provider backends.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.14.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.14.0
```
- ›Adds SandboxAgent class (extends Agent) with default_manifest, sandbox instructions, capabilities, and run_as for running agents inside persistent, isolated workspaces.
- ›Adds SandboxRunConfig for per-run sandbox wiring: client creation, live session injection, serialized session resume via SandboxSessionState, manifest overrides, snapshots, and materialization_concurrency limits.
- ›Adds Manifest — a workspace-bootstrap contract covering files, directories, local files, local directories, Git repos, environment variables, users, groups, and mounts.
- ›Adds built-in sandbox capabilities for shell access, filesystem editing and image inspection, skills, memory, and compaction.
- ›Adds UnixLocalSandboxClient for fast local development and DockerSandboxClient for container-isolated runs with image parity.
+10 moreshow less
- ›Adds hosted sandbox provider clients for Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, and Vercel, installable as optional extras.
- ›Adds remote storage mount support for S3, Cloudflare R2, Google Cloud Storage, Azure Blob Storage, and S3 Files across Docker, Modal, Cloudflare, Blaxel, Daytona, E2B, and Runloop backends.
- ›Adds sandbox memory capability: stores extracted lessons in the workspace, injects summaries into later runs, and supports read-only or generate-only modes, live stale-memory updates, and S3-backed persistence.
- ›Adds multi-turn memory grouping via conversation_id, SDK Session, RunConfig.group_id, or auto-generated run IDs, with separate memory layouts for per-agent or per-workflow isolation.
- ›Adds portable workspace snapshots with path normalization, symlink preservation, mount-safe snapshotting, and remote snapshot support.
- ›Adds resume paths through runner-managed RunState, explicit SandboxSessionState, or saved snapshots so agents can continue work across runs.
- ›Adds sandbox-aware RunState serialization and unified sandbox tracing integrated with existing SDK spans.
- ›Adds token usage reporting on tracing spans.
- ›Adds safer redaction of sensitive MCP tool outputs when sensitive tracing is disabled.
- ›Adds a large examples/sandbox/ suite covering local/Docker runners, hosted providers, memory patterns, mount smoke tests, coding tasks, handoff patterns, and domain-specific tutorials (tax-prep, healthcare, dataroom QA, code review, vision website clone).
v0.13.5 Apr 6, 2026 · issue -135

OpenAI Agents SDK v0.13.5 adds callable approval policies for local MCP servers and a public flush_traces API.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.13.5 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.13.5
```
└──▷ USE IT
Flush all buffered traces immediately — useful in short-lived scripts or tests where the process may exit before traces are sent.
python
```
from agents import flush_traces

await flush_traces()
```
- ›Adds flush_traces as a public API to programmatically flush buffered trace data on demand.
- ›Supports callable approval policies for local MCP servers, enabling dynamic, code-driven control over tool-call approvals.
v0.13.2 Mar 26, 2026 · issue -146

OpenAI Agents SDK v0.13.2 adds external_web_access parameter to WebSearchTool.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.13.2 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.13.2
```
└──▷ USE IT
Enable external web access in a WebSearchTool to allow agents to retrieve results from outside a restricted environment.
python
```
from agents.tools import WebSearchTool

search_tool = WebSearchTool(external_web_access=True)
```
- ›Adds external_web_access parameter to WebSearchTool to control whether the tool can access external web sources.
v0.13.1 Mar 25, 2026 · issue -147

OpenAI Agents SDK v0.13.1 adds an any-llm adapter to the extension module for responses-compatible multi-LLM routing.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.13.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.13.1
```
- ›Adds an any-llm adapter to the extension module, enabling responses-compatible routing to any LLM supported by the [any-llm](https://github.com/mozilla-ai/any-llm) library.
v0.13.0 Mar 23, 2026 · issue -149

OpenAI Agents SDK v0.13.0 adds MCP resource methods, streamable HTTP session resumption, and opt-in reasoning-content replay for Chat Completions.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.13.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.13.0
```
└──▷ USE IT
Resume a stateless or reconnected MCP streamable HTTP session by capturing and reusing its session ID.
python
```
session_id = mcp_server.session_id
```
Enable reasoning-content replay for a LiteLLM or DeepSeek Chat Completions adapter so tool-call continuity is preserved across turns.
python
```
model = LiteLLMModel(..., should_replay_reasoning_content=True)
```
Fetch available resources and read one from an MCP server — useful when building agents that browse or act on server-side resources.
python
```
resources = await mcp_server.list_resources()
content = await mcp_server.read_resource(resources[0].uri)
```
- ›Adds list_resources(), list_resource_templates(), and read_resource() methods to MCPServer, exposing MCP resource access directly from the SDK.
- ›Adds session_id property to MCPServerStreamableHttp, enabling streamable HTTP sessions to be resumed across reconnects or stateless workers.
- ›Adds should_replay_reasoning_content opt-in flag to Chat Completions integrations, improving reasoning/tool-call continuity for adapters such as LiteLLM and DeepSeek.
- ›Changes the default Realtime WebSocket model to gpt-realtime-1.5, so new Realtime agent setups use the newer model without extra configuration.
v0.12.5 Mar 19, 2026 · issue -153

OpenAI Agents SDK v0.12.5 exposes auth and httpx_client_factory in MCP SSE/StreamableHttp transport params.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.12.5 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.12.5
```
- ›Adds auth and httpx_client_factory parameters to MCP SSE and StreamableHttp transport configuration, enabling custom authentication and HTTP client injection for MCP server connections.
v0.12.1 Mar 13, 2026 · issue -158

OpenAI Agents SDK v0.12.1 preserves explicit approval rejection messages across resume flows.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.12.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.12.1
```
- ›Preserves explicit approval rejection messages across resume flows, so rejection context is no longer lost when an interrupted run is resumed.
v0.12.0 Mar 12, 2026 · issue -159

OpenAI Agents SDK v0.12.0 adds opt-in retry policies for model API calls via ModelSettings.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.12.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.12.0
```
- ›Adds opt-in retry policy configuration to ModelSettings, passable as run config or per-agent model settings to automatically retry failed model API calls.
v0.11.0 Mar 9, 2026 · issue -162

OpenAI Agents SDK v0.11.0 adds tool search support with namespaces and extends computer use to the GA gpt-5.4 model.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.11.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.11.0
```
- ›Adds tool search tool support via the Responses API, including namespace scoping — see the tool_search.py example for usage.
- ›Extends ComputerTool to support the GA gpt-5.4 model in addition to the existing computer-use-preview model.
v0.10.5 Mar 5, 2026 · issue -166

OpenAI Agents SDK v0.10.5 adds explicit prefix mode control to MultiProvider.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.10.5 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.10.5
```
- ›Adds explicit prefix modes to MultiProvider, giving developers direct control over how model-name prefixes are applied when routing across multiple model providers.
v0.10.3 Mar 2, 2026 · issue -169

OpenAI Agents SDK v0.10.3 exposes agent tool invocation metadata and a new tool_context accessor on RunResult.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.10.3 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.10.3
```
- ›Adds tool_context accessor on RunResult to retrieve agent tool invocation context during a run.
- ›Exposes immutable agent tool invocation metadata on run results, making per-tool call details available after execution.

v0.10.0 Feb 23, 2026 · issue -175

OpenAI Agents SDK v0.10.0 adds opt-in WebSocket mode for the Responses API with a reusable session helper.

└──▷ GET THIS VERSION

$ git clone --branch v0.10.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.10.0

└──▷ USE IT

Reuse a single WebSocket connection across two consecutive streamed turns to reduce connection overhead.

python

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())

›Adds set_default_openai_responses_transport('websocket') to switch all Responses API calls to WebSocket mode globally.
›Adds responses_websocket_session() async context manager for a reusable WebSocket connection across multiple streamed agent runs.
›Adds use_responses_websocket=True parameter to OpenAIProvider to enable WebSocket mode per-provider.

v0.9.2 Feb 19, 2026 · issue -179

OpenAI Agents SDK v0.9.2 adds reasoning_item_id_policy to RunConfig to suppress 400 errors with reasoning models.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.9.2 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.9.2
```
└──▷ USE IT
Prevent 400 errors when running a reasoning model by opting in to omitting reasoning item IDs across a full multi-turn session.
python
```
run_config = RunConfig(reasoning_item_id_policy="omit")
result = await Runner.run(
    agent,
    "Tell me about recursion in programming.",
    run_config=run_config,
)
```
- ›Adds reasoning_item_id_policy='omit' option to RunConfig to drop reasoning item IDs when using reasoning models, preventing 400 errors from inconsistent item sets; opt-in with default behavior unchanged.
- ›Persists reasoning_item_id_policy across agent resumes and streamed follow-up turns.
v0.9.0 Feb 13, 2026 · issue -185

OpenAI Agents SDK v0.9.0 adds configurable function-tool timeouts and a ToolOutputTrimmer for smart context management.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.9.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.9.0
```
└──▷ USE IT
Cap a slow function tool at 5 seconds and surface the timeout as a result string rather than crashing the run.
python
```
from agents import function_tool, ToolTimeoutBehavior

@function_tool(timeout_seconds=5.0, timeout_behavior="error_as_result")
def slow_lookup(query: str) -> str:
    ...  # long-running external call
```
- ›Adds timeout_seconds, timeout_behavior, and timeout_error_function parameters to function tools, letting you cap execution time and choose between 'error_as_result' or 'raise_exception' on timeout via ToolTimeoutBehavior and ToolErrorFunction.
- ›Adds ToolOutputTrimmer for smart context management, enabling automatic trimming of tool output to fit within context limits.
└──▷ BREAKING ON UPGRADE
- !Python 3.9 is no longer supported; upgrade to Python 3.10 or newer.
- !Agent.as_tool() now returns FunctionTool instead of the broader Tool union type; code that depends on the Tool return type may require adjustment.

v0.8.4 Feb 11, 2026 · issue -187

OpenAI Agents SDK v0.8.4 adds ShellTool with container runtime and native skills support.

└──▷ GET THIS VERSION

$ git clone --branch v0.8.4 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.8.4

└──▷ USE IT

Run an agent with a sandboxed container shell and a pinned skill reference — useful when your agent needs to execute shell commands inside an isolated, network-disabled container with a pre-built skill.

python

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",
                    }
                ],
            }
        )
    ],
)

›Adds ShellTool with environment parameter supporting type: container_auto, network_policy, and skills (via skill_reference with skill_id and version) for hosted container shell runtime with native skills support.

v0.8.3 Feb 10, 2026 · issue -188

Realtime agents SDK gains model_version param for turn detection control.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.8.3 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.8.3
```
- ›Adds model_version parameter to turn detection configuration in the realtime agents SDK, allowing selection of the turn-detection model version.
v0.8.2 Feb 9, 2026 · issue -189

OpenAI Agents SDK v0.8.2 adds Annotated[T, Field(...)] support in function schemas and exposes the agent inside ToolContext tool calls.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.8.2 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.8.2
```
└──▷ USE IT
Attach a Pydantic Field description and constraints to a tool parameter so the model receives richer schema metadata.
python
```
from typing import Annotated
from pydantic import Field
from agents import function_tool

@function_tool
def search(query: Annotated[str, Field(description="The search query", min_length=1)]) -> str:
    return f"Results for: {query}"
```
Access the current agent from within a tool at runtime using the ToolContext passed to the tool call.
python
```
from agents import function_tool, ToolContext

@function_tool
def my_tool(ctx: ToolContext, input: str) -> str:
    agent = ctx.agent  # the agent invoking this tool
    return f"Called by agent: {agent.name}, input: {input}"
```
- ›Supports Annotated[T, Field(...)] syntax in function tool schemas, letting practitioners attach Pydantic field metadata (descriptions, constraints, aliases) directly to tool function parameters.
- ›Includes the calling agent instance in ToolContext during tool calls, giving tool implementations access to the agent at runtime.
v0.8.1 Feb 6, 2026 · issue -192

OpenAI Agents SDK v0.8.1 adds run-context thread reuse for codex_tool and a max-turns limit for the REPL.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.8.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.8.1
```
- ›Adds a max-turns limit to the REPL loop, preventing runaway multi-turn agent sessions.
- ›Adds run-context thread reuse for codex_tool, allowing tool invocations within a run to share execution context across turns.
v0.8.0 Feb 5, 2026 · issue -193

OpenAI Agents SDK v0.8.0 adds human-in-the-loop approval flows, structured tool input, configurable MCP failure handling, and max-turns error hooks.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.8.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.8.0
```
└──▷ USE IT
Gate a sensitive tool behind human approval so an operator can confirm or deny each invocation before the agent proceeds.
python
```
@function_tool(needs_approval=True)
async def delete_record(record_id: str) -> str:
    # Only runs after a human approves
    return f"Record {record_id} deleted"

result = await Runner.run(agent, "Delete record 42")
for interruption in result.interruptions:
    state = result.to_state()
    if await confirm(f"Approve {interruption.name}({interruption.arguments})?"):
        state.approve(interruption)
    else:
        state.reject(interruption)
result = await Runner.run(agent, state)
```
Restore fail-fast behavior for MCP tool errors on an agent that previously expected the run to abort when an MCP tool failed.
python
```
agent = Agent(
    name="My Agent",
    instructions="...",
    tools=[...],
    mcp_config={"failure_error_function": None},
)
```
- ›Adds needs_approval=True parameter to @function_tool to declare that a tool call requires human approval before execution; pending approvals surface as result.interruptions on the run result.
- ›Adds RunState class with state.approve(interruption) and state.reject(interruption) methods, and result.to_state() to serialize a paused run so it can be resumed via Runner.run(agent, state) after human decisions.
- ›Adds mcp_config={"failure_error_function": ...} agent-level config key to control MCP tool failure handling; defaults now return model-visible error output instead of failing the whole run; set failure_error_function=None on individual MCP servers to restore fail-fast behavior.
- ›Adds tool_error_formatter parameter for customizing the error output returned to the model when a tool call fails.
- ›Adds max_turns run error handlers so callers can supply a callback when the agent hits its turn limit.
+5 moreshow less
- ›Adds session customization parameters to Runner for controlling session behavior.
- ›Adds MCP tool meta resolver support, allowing dynamic resolution of MCP tool metadata.
- ›Supports image responses from MCP servers, enabling MCP tools to return image content.
- ›Adds CRLF line-ending support for apply_diff, broadening compatibility with Windows-style patch content.
- ›Adds structured agent tool input support, enabling agents-as-tools to receive typed, structured input.
└──▷ BREAKING ON UPGRADE
- !Synchronous Python function tools now execute on worker threads via asyncio.to_thread(...) instead of the event loop thread; tools that depend on thread-local state or thread-affine resources must migrate to async implementations or make thread affinity explicit.
- !Local MCP tool failure handling default behavior changed: failures now return model-visible error output instead of failing the whole run; to restore fail-fast semantics, set mcp_config={"failure_error_function": None} at the agent level and failure_error_function=None on each local MCP server that has an explicit handler.
v0.7.0 Jan 23, 2026 · issue -206

OpenAI Agents SDK v0.7.0 adds MCPServerManager for parallel MCP lifecycle management and makes nested handoffs opt-in.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.7.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.7.0
```
└──▷ USE IT
Manage multiple MCP servers in parallel inside a FastAPI lifespan, making all active servers available to an Agent.
python
```
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=req.query)
    return {"output": result.final_output}
```
Re-enable nested handoff history for agents that depend on the v0.6.0 default behavior.
python
```
from agents import Agent, 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),
)
```
- ›Adds MCPServerManager class in agents.mcp to safely manage multiple MCP server instances (e.g., MCPServerStreamableHttp) with a connect_in_parallel=True option and an active_servers property for use with Agent.
- ›Adds nest_handoff_history boolean field to RunConfig to opt in to nested handoff history (previously on by default since v0.6.0, now defaults to False).
- ›Makes session_input_callback optional when using a sessions store; the default behavior is now to append new input to the session history automatically.
- ›Sets the default reasoning.effort to 'none' for gpt-5.1/5.2 models in the default model configuration.
└──▷ BREAKING ON UPGRADE
- !The nest_handoff_history behavior introduced in v0.6.0 is now disabled by default; set RunConfig(nest_handoff_history=True) to restore the previous behavior.
- !The default reasoning.effort for gpt-5.1/5.2 is changed from 'low' to 'none'; explicitly set reasoning.effort='low' in your agent's model_settings if you relied on the previous default.
v0.6.9 Jan 20, 2026 · issue -209

OpenAI Agents SDK v0.6.9 adds input-based responses compaction with store-aware auto mode.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.6.9 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.6.9
```
- ›Adds input-based responses compaction with a store-aware auto mode, enabling smarter context management when responses are stored.
v0.6.7 Jan 16, 2026 · issue -213

OpenAI Agents SDK v0.6.7 adds experimental Codex tool integration and enforces max_output_length on shell tool outputs.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.6.7 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.6.7
```
└──▷ USE IT
Let an agent delegate coding tasks to Codex CLI on the host machine without any extra configuration.
python
```
from agents import Agent, Runner
from agents.extensions.experimental.codex import codex_tool

agent = Agent(
    name="codex-agent",
    tools=[codex_tool()],
)

result = Runner.run_sync(agent, "Refactor this function to use async/await")
print(result.final_output)
```
- ›Adds codex_tool() from agents.extensions.experimental.codex — an experimental tool that runs the Codex CLI as a subprocess, making all existing Codex configuration, skills, and capabilities available to agents without additional setup.
- ›Enforces max_output_length for shell tool outputs, capping runaway output from subprocess-based tools.
v0.6.6 Jan 15, 2026 · issue -214

OpenAI Agents SDK v0.6.6 adds auto-compaction for long conversations and an async SQLite session store.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.6.6 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.6.6
```
- ›Adds responses.compact setting to auto-compact long conversations, preventing context-window overflow in multi-turn agent runs.
- ›Adds AsyncSQLiteSession, an aiosqlite-backed async session store for persisting conversation state without blocking the event loop.
v0.6.5 Jan 6, 2026 · issue -223

v0.6.5 adds per-run tracing API keys, tool guardrails, AgentHookContext, and Gemini 3 Pro support
└──▷ GET THIS VERSION
```
$ git clone --branch v0.6.5 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.6.5
```
└──▷ USE IT
Attach guardrails directly to a function tool at decoration time, avoiding separate wiring in the agent definition.
python
```
@function_tool(guardrails=[my_input_guardrail])
async def lookup_user(user_id: str) -> str:
    ...
```
Access the current turn's input inside an agent hook to log or gate behaviour per turn.
python
```
async def on_agent_start(ctx: AgentHookContext, agent: Agent) -> None:
    print(f'Turn input: {ctx.turn_input}')
```
- ›Adds per-run tracing API key support, allowing a different API key to be specified for tracing on individual runs rather than globally.
- ›Adds AgentHookContext with a turn_input field for agent hooks, giving hook callbacks access to the current turn's input.
- ›Adds tool guardrails as arguments to the @function_tool decorator, enabling inline guardrail configuration directly on tool definitions.
- ›Adds realtime audio mapping support and SIP session payload handling for realtime agents.
- ›Adds Gemini 3 Pro support with cross-model conversation compatibility.
+1 moreshow less
- ›Preserves non-text tool outputs in LiteLLM and chatcmpl converters, improving fidelity when routing through alternate model backends.
v0.6.4 Dec 19, 2025 · issue -241

OpenAI Agents SDK v0.6.4 adds streaming and failure-handler control when agents are composed as tools.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.6.4 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.6.4
```
└──▷ USE IT
Supply a custom error message when an agent-as-tool run fails, instead of propagating a raw exception to the parent agent.
python
```
tool = child_agent.as_tool(
    tool_name="research",
    tool_description="Research a topic",
    failure_error_function=lambda ctx, exc: f"Research failed: {exc}"
)
```
Stream incremental output from an agent used as a tool so the parent agent can process partial results in real time.
python
```
tool = child_agent.as_tool(
    tool_name="summarizer",
    tool_description="Summarize a document",
    on_stream=lambda event: print(event)
)
```
- ›Exposes failure_error_function parameter in Agent.as_tool() so callers can supply a custom error handler when an agent-as-tool run fails.
- ›Adds on_stream callback to Agent.as_tool(), enabling streaming output from agents that are themselves used as tools inside a parent agent.
v0.6.3 Dec 11, 2025 · issue -249

OpenAI Agents SDK v0.6.3 preserves logprobs from the chat completions API in ModelResponse.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.6.3 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.6.3
```
- ›Preserves logprobs data from the chat completions API in ModelResponse, making token-level probability information available to callers downstream.
v0.6.0 Nov 18, 2025 · issue -272

OpenAI Agents SDK v0.6.0 adds parallel input guardrails, prompt cache retention, tool error logging, and a breaking handoff history change.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.6.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.6.0
```
└──▷ USE IT
Pin a prompt cache retention window in ModelSettings to control how long cached prompts are retained for a cost- or latency-sensitive agent.
python
```
from agents import Agent, ModelSettings

agent = Agent(
    name='my-agent',
    model='gpt-4o',
    model_settings=ModelSettings(prompt_cache_retention=300),
)
```
- ›Adds prompt_cache_retention field to ModelSettings to control prompt cache retention behaviour.
- ›Adds run_in_parallel parameter to input guardrails, allowing multiple guardrails to execute concurrently instead of sequentially.
- ›Adds tool error logging so errors raised during tool execution are now captured in logs.
- ›Handoff message history is now collapsed into a single message by default when handing off to a new agent (replaces the previous multi-message history pass-through).
└──▷ BREAKING ON UPGRADE
- !On agent handoff, message history is now collapsed into a single message by default ('Nest handoff history by default'). Agents that previously relied on the full expanded message history being passed to the receiving agent may behave differently; test before upgrading to v0.6.0 in production.
v0.5.1 Nov 13, 2025 · issue -277

Adds shell and apply_patch built-in tools introduced with the GPT-5.1 launch.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.5.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.5.1
```
- ›Adds shell and apply_patch as new supported tools for use with GPT-5.1 models.
v0.5.0 Nov 5, 2025 · issue -285

OpenAI Agents SDK v0.5.0 adds SIP protocol support for RealtimeRunner, per-request usage tracking, and Dapr session storage.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.5.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.5.0
```
- ›Adds SIP protocol connection support to RealtimeRunner, enabling realtime agents to handle SIP-based voice calls.
- ›Adds a list of per-request usage data to the Usage object, giving finer-grained token consumption tracking across multi-step runs.
- ›Adds Dapr as a session storage option for agent runs.
- ›Adds Python 3.14 to the list of officially supported versions.
v0.4.2 Oct 24, 2025 · issue -297

OpenAI Agents SDK v0.4.2 enables async tool calling in Realtime sessions and custom reasoning effort for LiteLLM providers.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.4.2 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.4.2
```
- ›Enables async tool calling in Realtime sessions, allowing asynchronous tools to be invoked during real-time agent interactions.
- ›Supports passing custom reasoning effort when using LiteLLM providers.
v0.4.0 Oct 17, 2025 · issue -304

OpenAI Agents SDK v0.4.0 adds image/file function outputs, graceful stream cancellation, MCP message handler config, and custom HTTP client factory.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.4.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.4.0
```
└──▷ USE IT
Inject a custom HTTPX client (e.g. with custom timeouts or auth headers) when initializing an MCP streamable-HTTP server connection.
python
```
import httpx
from agents.mcp import MCPServerStreamableHttp

server = MCPServerStreamableHttp(
    url="https://my-mcp-server.example.com/mcp",
    httpx_client_factory=lambda: httpx.AsyncClient(timeout=30.0, headers={"Authorization": "Bearer <token>"}),
)
```
- ›Adds httpx_client_factory initialization option to MCPServerStreamableHttp for supplying a custom HTTPX client when connecting to MCP servers.
- ›Exposes MCP message handler configuration, allowing callers to customize how MCP protocol messages are handled.
- ›Supports image and file output types as return values from agent tool functions.
- ›Adds a graceful cancel mode for streaming runs, enabling clean shutdown of in-progress streamed agent executions.
└──▷ BREAKING ON UPGRADE
- !openai package v1.x is no longer supported; the SDK now requires openai v2.x (migrated to v2.2.0).
v0.3.3 Sep 30, 2025 · issue -320

OpenAI Agents SDK v0.3.3 adds AdvancedSQLiteSession with branching, Redis session support, and tool-level input/output guardrails.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.3.3 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.3.3
```
- ›Adds AdvancedSQLiteSession class with conversation branching and usage tracking for persistent local agent memory.
- ›Adds Redis session support via a new Redis-backed session class for scalable, distributed agent memory across multiple instances.
- ›Adds tool input and output guardrails, enabling validation and filtering at the individual tool call level.
v0.3.2 Sep 23, 2025 · issue -327

OpenAI Agents SDK v0.3.2 adds tool-call arguments to ToolContext, Annotated-type schema support, and full header overrides.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.3.2 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.3.2
```
└──▷ USE IT
Inspect tool call arguments inside a RunHook to log or gate on what arguments were passed to a tool at runtime.
python
```
class MyHooks(RunHooks):
    async def on_tool_start(self, context: ToolContext, agent: Agent, tool: Tool) -> None:
        print(f"Tool '{tool.name}' called with args: {context.tool_call_arguments}")
```
Use Annotated to attach descriptions and constraints to function tool parameters so the model receives richer schema information.
python
```
from typing import Annotated
from agents import function_tool

@function_tool
def search(query: Annotated[str, "The search query, max 200 chars"]) -> str:
    ...
```
- ›Adds tool call arguments to ToolContext in RunHooks, giving hook implementations direct access to the arguments passed to each tool invocation.
- ›Supports Annotated types in function tool schemas, enabling richer metadata and constraints on tool parameters.
- ›Allows full HTTP header overrides on the client (previously limited to the user-agent header only).
v0.3.1 Sep 18, 2025 · issue -332

OpenAI Agents SDK v0.3.1 adds Anthropic extended thinking, input audio noise reduction, session encryption, Annotated-type tool params, and expanded Agent#as_tool options.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.3.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.3.1
```
└──▷ USE IT
Attach a plain-English description to a function tool parameter without a separate docstring, using Annotated.
python
```
from typing import Annotated
from agents import function_tool

@function_tool
def search(query: Annotated[str, 'The search query to look up'], max_results: Annotated[int, 'Maximum number of results to return'] = 10) -> list[str]:
    ...
```
- ›Supports typing.Annotated types for function tool parameter descriptions, letting developers embed param metadata directly in type hints.
- ›Adds more options to Agent#as_tool for finer control when exposing an agent as a callable tool.
- ›Exports user_agent_override context manager for overriding the HTTP User-Agent header at runtime.
- ›Adds input audio noise reduction for realtime voice sessions via the Realtime API.
- ›Migrates STT streaming to match the GA Realtime API.
+3 moreshow less
- ›Adds session encryption support using the cryptography library in the Sessions implementation.
- ›Supports Anthropic extended thinking and interleaved thinking in agent runs.
- ›Adds a warning when agent names transform into conflicting function names.
└──▷ BREAKING ON UPGRADE
- !Voice STT streaming has been migrated to match the GA Realtime API — existing STT streaming integrations may need to be updated.
v0.3.0 Sep 11, 2025 · issue -339

OpenAI Agents SDK v0.3.0 migrates the Realtime Agent integration to the GA Realtime API.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.3.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.3.0
```
- ›Updates Realtime Agent support to target the generally available OpenAI Realtime API, replacing the previous preview integration.
- ›Allows passing both a session and an input list together when running agents, enabling more flexible session-and-input composition.
v0.2.10 Aug 29, 2025 · issue -352

Adds environment-variable control for trace_include_sensitive_data, conversations API support, and reasoning text delta events for gpt-oss models.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.2.10 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.2.10
```
- ›Enables trace_include_sensitive_data to be configured via an environment variable, letting operators control sensitive data inclusion in traces without code changes.
- ›Adds conversations API support.
- ›Adds reasoning text delta event support for gpt-oss models in streaming runs.
v0.2.9 Aug 22, 2025 · issue -359

OpenAI Agents SDK v0.2.9 adds lifecycle hooks, SQLAlchemy history backend, MCP retry logic, and realtime input timeouts.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.2.9 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.2.9
```
- ›Adds on_llm_start and on_llm_end lifecycle hooks to the agent, letting callers instrument or intercept LLM calls at the start and end of each invocation.
- ›Adds a context parameter to run_demo_loop, enabling callers to pass runtime context through the interactive demo loop.
- ›Adds a SQLAlchemy session backend for conversation history management, enabling persistent, database-backed storage of conversation state.
- ›Adds retry logic to MCP server operations, improving resilience when MCP servers are temporarily unavailable.
- ›Adds a realtime input timeout trigger event, surfacing a new event type when realtime session input exceeds a configured timeout.
+2 moreshow less
- ›Adds conditional tool enabling to agent-as-tool, allowing tools exposed via an agent to be selectively enabled or disabled at runtime.
- ›Adds a quick opt-in option to switch to the gpt-5 model.
0.2.8 Aug 15, 2025 · issue -363

OpenAI Agents SDK 0.2.8 adds input modification hooks and removes Realtime message size limits.
└──▷ GET THIS VERSION
```
$ git clone --branch 0.2.8 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout 0.2.8
```
- ›Allows modifying the input sent to the model before it is dispatched, enabling pre-processing or sanitization of agent inputs at runtime.
- ›Realtime transport now accepts arbitrarily sized messages, removing previous message-length restrictions.
v0.2.7 Aug 14, 2025 · issue -363

OpenAI Agents SDK v0.2.7 adds reasoning.effort and verbosity params to ModelSettings plus a Realtime handoff prompt prefix.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.2.7 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.2.7
```
- ›Adds reasoning.effort='minimal' and verbosity parameters to ModelSettings for fine-grained control over model reasoning behaviour.
- ›Adds a handoff prompt prefix for Realtime agents, improving context handoff in real-time sessions.
- ›Adds runtime validation for Agent constructor arguments, catching misconfiguration at instantiation time.
v0.2.6 Aug 11, 2025 · issue -363

OpenAI Agents SDK v0.2.6 adds output guardrails for realtime agents and logprobs to ModelSettings.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.2.6 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.2.6
```
└──▷ USE IT
Request log probabilities from the model to inspect token-level confidence scores during inference.
python
```
from agents import Agent, ModelSettings

agent = Agent(
    name='analyzer',
    model='gpt-4o',
    model_settings=ModelSettings(logprobs=True)
)
```
- ›Adds logprobs field to ModelSettings class, enabling log-probability output from model responses.
- ›Supports agent output guardrails in realtime sessions, bringing parity with non-realtime guardrail enforcement.
v0.2.5 Aug 7, 2025 · issue -363

OpenAI Agents SDK v0.2.5 adds realtime speed control, agent-update-mid-session, MCP server visualization, and split stream events.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.2.5 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.2.5
```
└──▷ USE IT
Distinguish between a tool being called and its output arriving in a streaming run, so you can log or gate on each phase separately.
python
```
async for event in runner.stream():
    if event.type == 'tool_call_item':
        print('Tool invoked:', event.item)
    elif event.type == 'tool_call_output_item':
        print('Tool output:', event.item)
```
- ›Adds speed parameter to the realtime API to control the pace of model responses during a session.
- ›Adds the ability to update an agent's configuration during an active realtime session via the new update-agent functionality.
- ›Separates tool_call_item and tool_call_output_item into distinct stream events, giving handlers finer-grained control over tool call lifecycle.
- ›Exports MultiProvider in the public API, making multi-model-provider routing directly importable from the agents module.
- ›Visualization now draws MCP servers in agent graphs, making the full tool topology visible.
+1 moreshow less
- ›Enables passing async functions to HandoffInputData, expanding handoff customization options.
v0.2.4 Jul 29, 2025 · issue -364

OpenAI Agents SDK v0.2.4 adds Realtime playback tracking, raw model event forwarding, and a Twilio integration example.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.2.4 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.2.4
```
- ›Realtime: enables a playback tracker to monitor audio playback state during realtime sessions.
- ›Realtime: forwards all raw model events to callers, giving full visibility into underlying model event stream.
- ›Realtime: sends audio item and content index in audio events for more precise audio handling.
- ›Realtime: adds a Twilio integration example demonstrating how to connect the Realtime API to a Twilio voice session.
- ›Realtime: optimizes response cancellation to only cancel a response when actually necessary.
v0.2.3 Jul 21, 2025 · issue -364

OpenAI Agents SDK v0.2.3 adds direct access to the model layer from a realtime session.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.2.3 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.2.3
```
- ›Adds direct access to the model layer from a realtime session, enabling lower-level control over the realtime model interface.
v0.2.1 Jul 16, 2025 · issue -364

OpenAI Agents SDK v0.2.1 adds beta Realtime agents with handoffs and MCP structuredContent support.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.2.1 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.2.1
```
- ›Supports structuredContent in MCP tool_result responses, enabling richer structured data from MCP tools.
- ›Introduces Realtime agents (beta) with support for handoffs between agents during live audio/streaming sessions.
- ›Adds streaming of function call arguments to Chat Completions.
v0.2.0 Jul 15, 2025 · issue -364

OpenAI Agents SDK v0.2.0 adds Sessions for conversation history, beta RealtimeAgent support, MCP prompts, and file_input content.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.2.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.2.0
```
└──▷ USE IT
Annotate tool arguments with pydantic Field metadata (descriptions, constraints) for richer schema generation.
python
```
from pydantic import Field
from openai_agents import function_schema

@function_schema
def search_cve(cve_id: str = Field(..., description="CVE identifier, e.g. CVE-2024-1234"),
              severity: str = Field("high", description="Minimum severity filter")) -> str:
    ...
```
- ›Introduces Sessions API for automatic conversation history management, letting agents maintain context across multiple turns without manual history threading.
- ›Adds RealtimeAgent class (beta) with a dedicated RealtimeSession, OpenAI realtime transport implementation, guardrail support, and built-in tracing.
- ›Adds on_start support to VoiceWorkflowBase and VoicePipeline for lifecycle hooks at session start.
- ›Supports file_input content type in agent inputs.
- ›Supports MCP prompts via the MCP integration layer.
+1 moreshow less
- ›Adds support for pydantic Field annotations in tool arguments for tools decorated with @function_schema.
└──▷ BREAKING ON UPGRADE
- !The Agent class is split into AgentBase and Agent; code that references or subclasses Agent directly may break if it relied on internals now moved to AgentBase.
v0.1.0 Jun 27, 2025 · issue -365

OpenAI Agents SDK v0.1.0 adds is_enabled on handoffs, MCP tool filtering, safety check handling for ComputerTool, and reasoning content support.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.1.0 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.1.0
```
└──▷ USE IT
Conditionally disable a handoff at runtime — useful when an escalation path should only be available under certain conditions.
python
```
handoff = Handoff(agent=escalation_agent, is_enabled=lambda ctx: ctx.metadata.get('allow_escalation', False))
```
- ›Adds is_enabled to handoffs, allowing conditional enabling/disabling of agent handoff targets at runtime.
- ›Adds MCP tool filtering support, enabling agents to restrict which tools are exposed from an MCP server.
- ›Adds safety check handling for ComputerTool, surfacing safety blocks during computer-use actions.
- ›Adds reasoning content output, making reasoning model intermediate thoughts accessible in responses.
└──▷ BREAKING ON UPGRADE
- !MCP server interface includes a breaking change in this release; see https://openai.github.io/openai-agents-python/release/ for the specific migration details.
v0.0.19 Jun 18, 2025 · issue -365

OpenAI Agents SDK v0.0.19 makes Runner an abstract base class, enabling custom runner implementations.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.19 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.19
```
- ›Converts Runner to an abstract base class, allowing practitioners to subclass and implement custom runner logic.
└──▷ BREAKING ON UPGRADE
- !The Runner class is now abstract; any code that instantiates Runner directly will break on upgrade — subclass it instead.
v0.0.18 Jun 16, 2025 · issue -365

OpenAI Agents SDK v0.0.18 adds REPL support, dynamic prompt templates, and tool_call_id access in tool context.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.18 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.18
```
└──▷ USE IT
Spin up an interactive REPL to manually test an agent's responses during development.
python
```
from agents import Agent, run_demo_loop

agent = Agent(name='Assistant', instructions='You are a helpful assistant.')

import asyncio
asyncio.run(run_demo_loop(agent))
```
Access the current tool call ID inside a tool function to correlate responses or build stateful workflows.
python
```
from agents import Agent, RunContextWrapper, function_tool

@function_tool
def my_tool(ctx: RunContextWrapper, query: str) -> str:
    call_id = ctx.tool_call_id
    # use call_id for logging or stateful tracking
    return f'Handled call {call_id}: {query}'
```
- ›Adds run_demo_loop REPL helper for interactive agent testing sessions.
- ›Adds tool_call_id access via RunContextWrapper so tool functions can read the ID of the current tool call.
- ›Supports dynamic prompt templates through the OpenAI Prompts feature, enabling centrally managed, versioned agent instructions.
- ›Allows arbitrary keyword arguments to be passed through to the underlying model, enabling access to provider-specific parameters not yet explicitly supported.
└──▷ BREAKING ON UPGRADE
- !Timeout parameters now accept float (seconds) instead of timedelta objects — any code passing timedelta values to timeout parameters will break.
v0.0.17 Jun 4, 2025 · issue -365

v0.0.17 adds Portkey AI tracing, RunErrorDetails for max-turns exceptions, and is_enabled on FunctionTool.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.17 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.17
```
└──▷ USE IT
Conditionally disable a FunctionTool at runtime — useful when a tool should only be available based on dynamic state (e.g. user permissions or environment).
python
```
from agents import FunctionTool

def lookup_order(order_id: str) -> str:
    return f"Order {order_id}: shipped"

tool = FunctionTool(
    name="lookup_order",
    description="Look up an order by ID",
    params_json_schema={"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]},
    on_invoke_tool=lookup_order,
    is_enabled=False  # disable until user is authenticated
)
```
- ›Adds is_enabled field to FunctionTool, allowing tools to be conditionally activated or deactivated at runtime.
- ›Adds RunErrorDetails object to the MaxTurnsExceeded exception, giving callers structured context when an agent run hits its turn limit.
- ›Adds Portkey AI as a tracing provider, enabling traces to be sent to the Portkey observability platform.
v0.0.16 May 21, 2025 · issue -366

Adds hosted remote MCP, code interpreter, image generator, and local shell tools, plus an MCP server instructions attribute.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.16 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.16
```
- ›Adds an instructions attribute to MCP server configuration, allowing per-server instruction strings to be passed alongside tool definitions.
- ›Adds support for hosted remote MCP as a first-class tool type, enabling agents to call remote MCP endpoints without self-hosting a proxy.
- ›Adds a hosted code interpreter tool, letting agents execute code in a sandboxed environment via the Responses API.
- ›Adds a hosted image generator tool, enabling agents to generate images as part of a response pipeline.
- ›Adds a local shell tool, allowing agents to run shell commands on the local machine as a built-in tool type.
v0.0.15 May 15, 2025 · issue -366

OpenAI Agents SDK v0.0.15 adds Streamable HTTP transport for MCP servers and extra_body pass-through to LiteLLM.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.15 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.15
```
- ›Passes extra_body through to LiteLLM acompletion calls, enabling custom request body fields when using LiteLLM as a model provider.
- ›Adds Streamable HTTP transport support for MCP servers, enabling agents to connect to MCP servers over streamable HTTP in addition to existing transports.
v0.0.14 Apr 30, 2025 · issue -367

OpenAI Agents SDK v0.0.14 exposes token usage in streaming context and makes TTS voice types exportable.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.14 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.14
```
- ›Exposes usage data on the streaming context, letting callers inspect token consumption during streamed agent runs.
- ›Makes the TTS voices type exportable from the SDK, enabling typed references to voice options in downstream code.
v0.0.13 Apr 24, 2025 · issue -367

OpenAI Agents SDK v0.0.13 adds extra_headers to ModelSettings, streaming cancellation, and to_json_dict serialization.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.13 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.13
```
└──▷ USE IT
Pass custom HTTP headers (e.g. for routing or auth) on every request made with a given ModelSettings.
python
```
from agents import ModelSettings

settings = ModelSettings(
    model="gpt-4o",
    extra_headers={"X-Custom-Header": "my-value", "X-Team-ID": "team-42"}
)
```
Serialize current ModelSettings to a dict for logging, caching, or passing over a network boundary.
python
```
from agents import ModelSettings

settings = ModelSettings(model="gpt-4o", temperature=0.7)
print(settings.to_json_dict())
```
- ›Adds extra_headers parameter to ModelSettings to pass custom HTTP headers on a per-model-settings basis.
- ›Adds to_json_dict() method to ModelSettings for serializing model configuration to a JSON-compatible dictionary.
- ›Enables cancellation of in-progress streaming runs via the streaming result object.
v0.0.12 Apr 22, 2025 · issue -367

OpenAI Agents SDK v0.0.12 adds LiteLLM integration for any third-party model and lifts strict-mode restrictions on agent output types.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.12 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.12
```
└──▷ USE IT
Run an agent backed by Anthropic Claude via LiteLLM without changing any other agent code.
python
```
from agents import Agent

agent = Agent(
    name="claude-agent",
    model="litellm/anthropic/claude-3-5-sonnet-20240620",
    instructions="You are a helpful assistant.",
)
```
- ›Adds LiteLLM integration: pass any provider model to Agent via model="litellm/<provider>/<model_name>" (e.g. model="litellm/anthropic/claude-3-5-sonnet-20240620") to route completions through LiteLLM's unified interface.
- ›Enables non-strict output types on Agent, allowing more complex structured outputs that previously required strict JSON schema mode.
v0.0.10 Apr 15, 2025 · issue -367

OpenAI Agents SDK v0.0.10 adds previous_response_id support and new ModelSettings fields extra_query, extra_body, and stream_options.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.10 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.10
```
└──▷ USE IT
Pass custom query parameters or body fields through to the underlying API request for advanced use cases.
python
```
from agents import ModelSettings

settings = ModelSettings(
    extra_query={'my-param': 'value'},
    extra_body={'custom_field': True}
)
```
- ›Adds extra_query and extra_body fields to ModelSettings for passing extra request parameters directly to the underlying API call.
- ›Adds support for previous_response_id from the OpenAI Responses API, enabling stateful multi-turn conversations without re-sending full message history.
- ›Adds overwrite mechanism for stream_options in ModelSettings, allowing fine-grained control over streaming behavior.
└──▷ BREAKING ON UPGRADE
- !The referencable_id field is renamed to response_id — any code referencing referencable_id will break.
v0.0.8 Apr 3, 2025 · issue -367

OpenAI Agents SDK v0.0.8 adds store, metadata, and reasoning to ModelSettings, plus Databricks MLflow tracing and MCP strict-schema conversion.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.8 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.8
```
└──▷ USE IT
Pass reasoning configuration and metadata alongside a stored model call in a single ModelSettings definition.
python
```
from agents import Agent, ModelSettings

agent = Agent(
    name="analyst",
    model="o3",
    model_settings=ModelSettings(
        store=True,
        reasoning={"effort": "high"},
        metadata={"session": "pentest-42", "owner": "red-team"}
    )
)
```
- ›Adds store parameter to ModelSettings to control whether model responses are stored.
- ›Adds metadata field to ModelSettings for attaching arbitrary key-value metadata to model requests.
- ›Adds reasoning parameter to ModelSettings to configure model reasoning behavior.
- ›Converts MCP tool schemas to strict mode where possible, improving compatibility with strict-schema model APIs.
- ›Adds Databricks MLflow tracing integration for agent observability.
v0.0.7 Mar 26, 2025 · issue -368

OpenAI Agents SDK v0.0.7 adds MCP server support, Graphviz agent visualization, and configurable tool-choice reset behavior.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.7 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.7
```
- ›Adds MCP (Model Context Protocol) types to the SDK, enabling agents to connect to MCP servers as tool sources.
- ›Adds MCP support to the Runner, allowing agents to invoke tools served over MCP stdio transports.
- ›Adds MCP tracing so MCP tool calls appear as spans in the existing tracing pipeline.
- ›Adds Graphviz-based agent visualization functionality to graph agent topology.
- ›Makes the tool-use reset behavior configurable when tool_choice is set, giving callers control over how the SDK handles repeated tool-call loops.
v0.0.6 Mar 20, 2025 · issue -368

OpenAI Agents SDK v0.0.6 adds voice pipeline support to the Python library.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.6 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.6
```
- ›Adds voice pipeline support, enabling agents to process and respond to audio input/output within the SDK.
v0.0.5 Mar 19, 2025 · issue -368

Adds tool_use_behavior on agents and strict_mode on function tools, plus TracingProcessor public export
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.5 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.5
```
└──▷ USE IT
Enforce strict JSON schema validation on a function tool to catch malformed tool calls at the schema level.
python
```
@function_tool(strict_mode=True)
def lookup_order(order_id: str) -> str:
    return fetch_order(order_id)
```
Control agent behavior after tool execution — e.g. stop running the model again and return the tool result directly.
python
```
from agents import Agent

agent = Agent(
    name="Order Assistant",
    tools=[lookup_order],
    tool_use_behavior="stop_on_first_tool",
)
```
- ›Adds strict_mode option to function_schema and function_tool to control strict JSON schema enforcement on tool inputs.
- ›Introduces tool_use_behavior field on agents to configure how the agent responds when tools are used.
- ›Exports TracingProcessor from the top-level __init__.py, making it directly importable as a public API.
- ›Pretty-prints result classes for improved readability during development and debugging.
v0.0.4 Mar 13, 2025 · issue -368

v0.0.4 adds max_tokens to model settings, request ID tracking, and Keywords AI and Scorecard as external trace processors.
└──▷ GET THIS VERSION
```
$ git clone --branch v0.0.4 https://github.com/openai/openai-agents-python.git
# already have the repo? check out this version:
$ git checkout v0.0.4
```
- ›Adds max_tokens field to ModelSettings to cap token usage per model call.
- ›Adds request ID tracking to model responses, enabling correlation of SDK calls to upstream API requests.
- ›Adds Keywords AI as a supported external trace processor for agent observability pipelines.
- ›Adds Scorecard as a supported external trace processor for agent observability pipelines.
- ›Adds examples and documentation for using custom model providers with the SDK.

OpenAI Agents SDK

Summary

What OpenAI Agents SDK answers

Examples

Command line

Release history