v0.9.3

What's Changed

• fix: strip #2518 total_tokens from OpenAI tracing usage payloads by @seratch in #2521
• Release 0.9.3 by @github-actions[bot] in #2522

Full Changelog: v0.9.2...v0.9.3

v0.9.2

Key Changes

reasoning_item_id_policy: omit for reasoning models

To mitigate 400 errors caused by an inconsistent set of items when using reasoning models, this release introduces the reasoning_item_id_policy: 'omit' option to RunConfig. This is a new, opt-in option, so the default behavior is unchanged.

run_config = RunConfig(reasoning_item_id_policy="omit")
result = await Runner.run(
    agent,
    "Tell me about recursion in programming.",
    run_config=run_config,
)

What's Changed

• feat: persist reasoning item ID policy across resumes and streamed follow-up turns by @seratch in #2512
• fix: filter reasoning items from nested handoff input by @seratch in #2508
• fix(voice): keep trace active until pipeline processing completes by @OiPunk in #2472

Documents & Other Changes

• docs: update configuration details by @seratch in #2507
• docs: update translated document pages by @github-actions[bot] in #2509
• Release 0.9.2 by @github-actions[bot] in #2510

Full Changelog: v0.9.1...v0.9.2

v0.9.1

What's Changed

• fix: materialize iterable input history in ItemHelpers.input_to_new_input_list by @seratch in #2496
• fix: emit tracing function spans for shell/apply_patch/computer runtime tools by @seratch in #2498
• fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards by @seratch in #2499
• fix: #2487 persist nested agent-tool HITL state across RunState JSON round-trips by @seratch in #2500
• fix: isolate nested agent-tool resume cache by RunState scope by @seratch in #2501
• fix: bump RunState schema to 1.1 with explicit backward-read policy by @seratch in #2502

Documents & Other Changes

• docs: updates for 0.9.0 release by @seratch in #2481
• docs: update translated document pages by @github-actions[bot] in #2482
• docs: update translated document pages by @github-actions[bot] in #2483
• docs: update translated document pages by @github-actions[bot] in #2484
• docs: sync tool docs and add coverage for internal helper branches by @seratch in #2485
• docs: update translated document pages by @github-actions[bot] in #2486
• Release 0.9.1 by @github-actions[bot] in #2497

Full Changelog: v0.9.0...v0.9.1

v0.9.0

Key Changes

Python 3.9 is no longer supported

Since Python 3.9 is EOLed three months ago, this SDK no longer support the version. Please upgrade to Python 3.10 or newer.

Timeouts for function tools

Now you can pass the following options to customize function tool behavior:

• timeout_seconds: float | None
• timeout_behavior: ToolTimeoutBehavior = "error_as_result" # or "raise_exception"
• timeout_error_function: ToolErrorFunction | None

Agent#as_tool() now returns FunctionTool

Additionally, the type hint for the value returned from the Agent#as_tool() method has been narrowed from Tool to FunctionTool. This change should not usually cause breaking issues, but if your code relies on the broader union type, you may need to make some adjustments on your side.

What's Changed

• chore: drop Python 3.9 support across metadata, CI, and docs by @seratch in #2474
• feat: #2346 add configurable timeout handling for function tools by @seratch in #2479
• feat: add ToolOutputTrimmer for smart context management by @jkrish in #2468
• fix: narrow Agent.as_tool return type to FunctionTool by @seratch in #2473
• fix(tracing): propagate trace metadata to spans for processors by @seratch in #2478
• fix(voice): handle odd-length audio buffers in StreamedAudioResult by @OiPunk in #2456

Documents & Other Changes

• docs: update translated document pages by @github-actions[bot] in #2475
• Release 0.9.0 by @github-actions[bot] in #2480

New Contributors

• @jkrish made their first contribution in #2468

Full Changelog: v0.8.4...v0.9.0

v0.8.4

Key Changes

Hosted container tool + Skills

This release includes the hosted shell runtime tool along with its native skills support. Developers now can pass a container-based shell runtime with skills this way:

from agents import Agent, ShellTool

agent = Agent(
    name="Shell Agent",
    model="gpt-5.2",
    instructions="Use the available shell tool to answer user requests.",
    tools=[
        ShellTool(
            environment={
                "type": "container_auto",
                "network_policy": {"type": "disabled"},
                "skills": [
                    {
                        "type": "skill_reference",
                        "skill_id": "skill_698bbe879adc81918725cbc69dcae7960bc5613dadaed377",
                        "version": "1",
                    }
                ],
            }
        )
    ],
)

Refer to examples/tools/container_shell_inline_skill.py and examples/tools/container_shell_skill_reference.py for more details.

What's Changed

• feat: add container shell + skills support by @seratch in #2469
• fix(realtime): omit null audio formats in SIP call attach updates by @OiPunk in #2454
• fix(result): support Pydantic model_rebuild for RunResultStreaming by @OiPunk in #2455
• fix(tool): resolve default failure handler at invoke time by @OiPunk in #2460
• fix(agent-tools): inherit parent RunConfig when agent-as-tool is invoked by @OiPunk in #2463
• fix(stream): emit queued events before max-turns exception by @OiPunk in #2458
• fix(prompt): omit tool_choice when prompt manages built-in tools by @OiPunk in #2464

Documents & Other Changes

• docs: update translated document pages by @github-actions[bot] in #2452
• fix(mcp): validate required params before call_tool by @OiPunk in #2453
• docs: clarify Azure Realtime GA endpoint configuration by @OiPunk in #2440
• docs: update translated document pages by @github-actions[bot] in #2466
• Release 0.8.4 by @github-actions[bot] in #2465

Full Changelog: v0.8.3...v0.8.4

v0.8.3

What's Changed

• Support model_version param for turn detection in realtime agents sdk by @jhills20 in #2450

Documents & Other Changes

• docs: describe Pydantic Field annotations for tool args by @haasonsaas in #2436
• Release 0.8.3 by @github-actions[bot] in #2451

Full Changelog: v0.8.2...v0.8.3

v0.8.2

What's Changed

• feat: support Annotated[T, Field(...)] in function schema by @haasonsaas in #2435
• feat: include agent in ToolContext tool calls by @rm-openai in #2446
• fix(tracing): #2444 drop unsupported usage fields for OpenAI trace ingest by @seratch in #2448
• fix(core): avoid noisy pydantic serialization warnings for model_dump items by @OiPunk in #2443
• refactor: Extract duplicate Gemini tool call ID cleanup logic by @hobostay in #2438

Documents & Other Changes

• docs: update document pages for v0.8.1 release by @seratch in #2432
• docs: update translated document pages by @github-actions[bot] in #2434
• Release 0.8.2 by @github-actions[bot] in #2447

New Contributors

• @OiPunk made their first contribution in #2443
• @hobostay made their first contribution in #2438
• @haasonsaas made their first contribution in #2435

Full Changelog: v0.8.1...v0.8.2

v0.8.1

What's Changed

• feat: add run-context thread reuse for codex_tool by @seratch in #2425
• feat: add max turns in REPL by @xju2 in #2431
• fix: #2426 persist streamed run-again tool items to session by @seratch in #2433
• fix: preserve handoff target resolution compatibility in run-state agent maps by @seratch in #2423

Documents & Other Changes

• docs: v0.8.0 changes by @seratch in #2405
• docs: update translated document pages by @github-actions[bot] in #2420
• Release 0.8.1 by @github-actions[bot] in #2424

New Contributors

• @xju2 made their first contribution in #2431

Full Changelog: v0.8.0...v0.8.1

v0.8.0

Key Changes

Human-in-the-Loop (HITL)

The human-in-the-loop (HITL) flow enables your agents to pause execution until a person approves or rejects sensitive tool calls. Tools declare when they need approval, run results surface pending approvals as interruptions, and RunState lets you serialize and resume runs after decisions are made.

import asyncio
from agents import Agent, Runner, RunState, function_tool

@function_tool
async def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny"

# This function requires approval
@function_tool(needs_approval=True)
async def get_temperature(city: str) -> str:
    return f"The temperature in {city} is 20° Celsius"

agent = Agent(
    name="Weather Assistant",
    instructions="You are a helpful weather assistant. Answer questions about weather and temperature using the available tools.",
    tools=[get_weather, get_temperature],
)

async def main():
    result = await Runner.run(agent, "What is the weather and temperature in Oakland?")
    has_interruptions = len(result.interruptions) > 0

    while has_interruptions:
        state = result.to_state()
        # Process each interruption
        for interruption in result.interruptions:
            print("\nTool call details:")
            print(f"  Agent: {interruption.agent.name}")
            print(f"  Tool: {interruption.name}")
            print(f"  Arguments: {interruption.arguments}")
            confirmed = await confirm("\nDo you approve this tool call?")
            if confirmed:
                print(f"✓ Approved: {interruption.name}")
                state.approve(interruption)
            else:
                print(f"✗ Rejected: {interruption.name}")
                state.reject(interruption)

        # Resume execution with the updated state
        print("\nResuming agent execution...")
        result = await Runner.run(agent, state)
        has_interruptions = len(result.interruptions) > 0

    print(result.final_output)

Refer to the document page and examples for more details.

Migration Guide

In this version, two runtime behavior changes may require migration work:

• Function tools wrapping synchronous Python callables now execute on worker threads via asyncio.to_thread(...) instead of running on the event loop thread. If your tool logic depends on thread-local state or thread-affine resources, migrate to an async tool implementation or make thread affinity explicit in your tool code.
• Local MCP tool failure handling is now configurable, and the default behavior can return model-visible error output instead of failing the whole run. If you rely on fail-fast semantics, set mcp_config={"failure_error_function": None}. Server-level failure_error_function values override the agent-level setting, so set failure_error_function=None on each local MCP server that has an explicit handler.

What's Changed

• feat: #636 Add human-in-the-loop (HITL) support by @seratch in #2230
• feat: add structured agent tool input support by @seratch in #2383
• feat: add max_turns run error handlers by @seratch in #2347
• feat: Add session customization params by @danielquintas8 in #2196
• feat: #2367 add MCP tool meta resolver support by @seratch in #2375
• feat: Image response from an MCP server by @seratch in #2369
• feat: #1788 add configurable MCP tool failure handlers by @seratch in #2378
• feat: Add CRLF support for apply_diff by @gustavz in #2394
• feat: propagate tool description to ToolCallItem (#2379) by @k1eran in #2381
• fix: Fix MCP tool timeouts halting agent flow by @habema in #2249
• fix: Fix compaction-aware session check for lazy sessions for #2196 by @seratch in #2368
• fix: #2370 guard realtime truncate against completed audio by @seratch in #2374
• fix: #2386 offload sync tool execution to worker threads by @seratch in #2387
• fix: include full usage details in generation span usage by @stanleychu2 in #2391
• fix: #2370 send truncate events independent of response state by @seratch in #2385
• fix: remove erroneous isinstance(agent, Tool) check in visualization by @leesta24 in #2399
• feat: add tool_error_formatter for customizing error tool output by @seratch in #2400
• fix: resolve a migration error in #2230 by @seratch in #2404
• fix: preserve legacy positional previous_response_id in Runner.run_streamed by @seratch in #2408
• fix: restore MCPUtil.to_function_tool legacy call compatibility by @seratch in #2409
• fix: make codex subprocess stream limit configurable and validate bounds by @seratch in #2410
• fix: preserve latest session tool outputs and keep orphan calls in non-resume input prep by @seratch in #2411
• fix: preserve positional-argument compatibility for public runtime constructors by @seratch in #2413
• fix: restore v0.7.0 constructor compatibility for RunResult types by @seratch in #2414
• fix: restore replay compatibility for run context approvals and guardrail execution by @seratch in #2415
• fix: cancel model task when parallel input guardrail trips by @seratch in #2416

Documents & Other Changes

• Update docs for #2272 nested handoff to opt-in by @seratch in #2273
• docs: update translated document pages by @github-actions[bot] in #2357
• Add OpenAI Agents SDK + Restate integration to the docs by @gvdongen in #2359
• docs: update translated document pages by @github-actions[bot] in #2360
• docs: add prompt template setup steps and MCP server manager guide by @seratch in #2362
• Upgrade GitHub Actions for Node 24 compatibility by @salmanmkc in #2355
• Upgrade GitHub Actions to latest versions by @salmanmkc in #2356
• docs: update translated document pages by @github-actions[bot] in #2363
• Add PostHog integration link to tracing documentation by @andrewm4894 in #2380
• docs: update translated document pages by @github-actions[bot] in #2382
• chore(deps): bump actions/checkout from 6.0.1 to 6.0.2 by @dependabot[bot] in #2390
• chore(deps): bump astral-sh/setup-uv from 5.4.2 to 7.2.1 by @dependabot[bot] in #2389
• add Traccia integration link to tracing documentation by @AdityaSaroj in #2395
• fix: correct typo 'revist' → 'revisit' in TODO comments by @leesta24 in #2398
• chore: migrate repository skill paths to .agents/skills by @seratch in #2402
• docs: Add Agents SDK DBOS integration to the docs for long-running agents and human-in-the-loop by @qianl15 in #2418
• docs: update translated document pages by @github-actions[bot] in #2419
• Release 0.8.0 by @github-actions[bot] in #2377

New Contributors

• @gvdongen made their first contribution in #2359
• @danielquintas8 made their first contribution in #2196
• @andrewm4894 made their first contribution in #2380
• @k1eran made their first contribution in #2381
• @AdityaSaroj made their first contribution in #2395
• @stanleychu2 made their first contribution in #2391
• @leesta24 made their first contribution in #2399
• @qianl15 made their first contribution in #2418

Full Changelog: v0.7.0...v0.8.0

v0.7.0

Key Changes

Nested handoff behavior is now opt-in

The nested handoffs behavior were enabled by default in v0.6.0. Now, it is now disabled by default. To enable it again, you need to set the nest_handoff_history option to True.

from agents import Agent, MCPServerManager, RunConfig, Runner

agent = Agent(name="My agent", instructions="Be creative")
result = await Runner.run(
    agent,
    input="Hey, can you tell me something interesting about Japan?",
    run_config=RunConfig(nest_handoff_history=True),
)

MCPServerManager for multiple MCP server instances

Starting with this version, there is a new, convenient way to manage multiple MCP server instances. See #2350 and examples/mcp/manager_example.

from contextlib import asynccontextmanager
from fastapi import FastAPI
from agents import Agent, Runner
from agents.mcp import MCPServerManager, MCPServerStreamableHttp

@asynccontextmanager
async def lifespan(app: FastAPI):
    async with MCPServerManager(
        servers=[
            MCPServerStreamableHttp({"url": 'http://localhost:8001/mcp'}),
            MCPServerStreamableHttp({"url": 'http://localhost:8002/mcp'}),
        ],
        connect_in_parallel=True,
    ) as manager:
        app.state.mcp_manager = manager
        yield

app = FastAPI(lifespan=lifespan)

@app.post("/agent")
async def run_agent(req) -> dict[str, object]:
    agent = Agent(
        name="Test Agent",
        instructions="Use the MCP tools when needed.",
        mcp_servers= app.state.mcp_manager.active_servers,
    )
    result = await Runner.run(starting_agent=agent, input=build_query(req))
    return {"output": result.final_output}

Other key changes

• The default reasoning.effort for gpt-5.1/5.2 is now set to "none"; if you rely on the previous default "low" set by the default model configuration, please explicitly set it to "low" in your agent's model_settings.
• When using a sessions store, session_input_callback used to be required to be provided. Now, it is optional and the default behavior is to append the new input to the session history.

What's Changed

• fix: #2211 Move nested handoffs to opt-in feature by @seratch in #2272
• feat: add MCPServerManager for safely managing server lifecycle by @seratch in #2350
• fix: Make session list inputs auto-append by default by @seratch in #2282
• feat: update gpt-5.1/5.2 default model settings by @seratch in #2327
• Add WebSocket custom options to OpenAIRealtimeWebSocketModel by @aligokalppeker in #2264

Documents & Other Changes

• chore(deps): bump openai/codex-action from f5c0ca71642badb34c1e66321d8d85685a0fa3dc to 086169432f1d2ab2f4057540b1754d550f6a1189 by @dependabot[bot] in #2340
• chore(deps): bump actions/setup-python from 5.6.0 to 6.1.0 by @dependabot[bot] in #2341
• chore(deps): bump astral-sh/setup-uv from e58605a9b6da7c637471fab8847a5e5a6b8df081 to d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 by @dependabot[bot] in #2342
• docs: #2343 clarify how to use compaction in practice by @seratch in #2344
• docs: update translated document pages by @github-actions[bot] in #2345
• Update all translated document pages by @github-actions[bot] in #2338
• Release 0.7.0 by @github-actions[bot] in #2339

New Contributors

• @dependabot[bot] made their first contribution in #2340

Full Changelog: v0.6.9...v0.7.0