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

v0.6.9

What's Changed

• feat: #2333 support input-based responses compaction with store-aware auto mode by @seratch in #2334
• fix: #2061 handle invalid tool arguments JSON without crashing by @seratch in #2337
• Release 0.6.9 by @github-actions[bot] in #2336

Full Changelog: v0.6.8...v0.6.9

v0.6.8

What's Changed

• Enhance exception handling in MCP server initialization and cleanup by @habema in #2268
• Bump LiteLLM to fix Vertex AI function calling with no-param tools by @habema in #2329
• Fix: Tool message ordering for Gemini models by @habema in #2331
• fix: #2155 DeepSeek reasoning_content missing in tool call messages by @wahmd in #2328

Documents & Others

• docs: add codex tool document section by @seratch in #2325
• Update all translated document pages by @github-actions[bot] in #2326
• Release 0.6.8 by @github-actions[bot] in #2332

New Contributors

• @wahmd made their first contribution in #2328

Full Changelog: v0.6.7...v0.6.8

v0.6.7

What's Changed

• feat: add experimental Codex extension and tool by @seratch in #2320
• Enforce max_output_length for shell tool outputs by @gustavz in #2299
• fix: #2171 dedupe nested handoff inputs by @seratch in #2323
• fix: #2317 defer compaction when local tool outputs are present by @seratch in #2322

Experimental: Codex Tool Support

Starting with this version, we have added a new experimental Codex extension (agents.extensions.experimental.codex). This extension allows you to use Codex as a tool within your agents. Since this module is still experimental, its behavior and implementation details may change in future releases.

If you run an agent with codex_tool() on a host where Codex is installed, the agent will use Codex as a tool to answer the question. The tool simply runs the Codex CLI as a subprocess, so all existing Codex configuration, skills, and capabilities are available without any additional setup.

See the example code and #2320 for more details.

Documents & Others

• Update docs by @seratch in #2307
• Update all translated document pages by @github-actions[bot] in #2312
• Update all translated document pages by @github-actions[bot] in #2316
• chore: update test coverage rules to exclude tests/* by @seratch in #2318
• Release 0.6.7 by @github-actions[bot] in #2319

Full Changelog: v0.6.6...v0.6.7

v0.6.6

What's Changed

• feat: #2206 Add responses.compact: auto-compact long conversations by @ruskaruma in #2224 #2287
• Add AsyncSQLiteSession (aiosqlite-backed async session store) by @gustavz in #2284
• fix: #2009 #2010 Improve PCM duration calculation and handle VAD truncation by @ruskaruma in #2059
• Fix thinking tokens not attached without tool calls (#2195) by @AryanBagade in #2290
• Improve loading of OPENAI_AGENTS_DISABLE_TRACING by @seratch in #2302
• Harden tracing shutdown logging against closed handlers by @seratch in #2270
• fix: bump litellm to resolve pydantic deprecation warnings by @seratch in #2292
• fix: #2291 silence LiteLLM serializer warnings in streaming (opt-in) by @seratch in #2295

Documents & Others

• Add regression tests as prep for HITL changes by @seratch in #2267
• Add verify-changes skill to this project by @seratch in #2271
• docs: align contributor guide and skills with JS updates by @seratch in #2286
• docs: add PR draft guidance skill by @seratch in #2288
• Add runner script for examples and refresh sample outputs by @seratch in #2289
• docs: add ExecPlan guidance and template by @seratch in #2298
• Update examples by @seratch in #2300
• feat: add examples auto-run skill and refresh example scripts by @seratch in #2303
• Add two more agent skills by @seratch in #2304
• misc: add docs-sync skill by @seratch in #2306
• chore: add release workflows and review prompt by @seratch in #2309
• chore: add release PR labeling and milestone fallback by @seratch in #2311
• Release 0.6.6 by @github-actions[bot] in #2310

New Contributors

• @AryanBagade made their first contribution in #2290

Full Changelog: v0.6.5...v0.6.6

v0.6.5

What's Changed

• Add per-run tracing API key support by @rm-openai in #2260
• Add AgentHookContext with turn_input for agent hooks by @ihower in #2213
• feat: Add tool guardrails to function_tool decorator args (ref #2218) by @seratch in #2227
• Add realtime audio mapping support and SIP session payload tests by @seratch in #2225
• fix: #2204 Convert tool execution exception to runtime error by @aligokalppeker in #2243
• fix: handle output_text type in realtime text mode by @sbera77 in #2235
• fix: #2222 Streaming is blocking and cannot be cancelled by @seratch in #2226
• fix: Improve tracing shutdown safety by @seratch in #2229
• Gemini 3 Pro support and cross-model conversation compatibility by @ihower in #2158
• Preserve non-text tool outputs in LiteLLM and chatcmpl converters by @ihower in #2214
• Add explicit content=None to assistant tool-call messages in Chat Completions converter by @ihower in #2238
• v0.6.5 by @seratch in #2263

Documents

• docs: Add document updates for #2169 changes by @seratch in #2170
• Fix README.md typo in uv installation instructions by @zachparent-oai in #2210
• docs: fix code typo in for loop by @aniketmaurya in #2209
• Make example prompt consistent with Quick-start context by @zhaoyanthu in #2215
• Update all translated document pages by @github-actions[bot] in #2207
• Update all translated document pages by @github-actions[bot] in #2212
• Update all translated document pages by @github-actions[bot] in #2219
• Update all translated document pages by @github-actions[bot] in #2262

New Contributors

• @zachparent-oai made their first contribution in #2210
• @aniketmaurya made their first contribution in #2209
• @zhaoyanthu made their first contribution in #2215
• @aligokalppeker made their first contribution in #2243

Full Changelog: v0.6.4...v0.6.5

v0.6.4

What's Changed

• feat: Add on_stream to agents as tools by @seratch in #2169
• fix: Enable creating/disposing Computer per agent run by @seratch in #2191
• Expose failure_error_function in Agent.as_tool by @Nekowaii in #2179
• fix #2181 FunctionTool.strict_json_schema is missing when using Chat Completions API by @seratch in #2182
• fix: Enhance null handling for input and output token details in Usage class by @aliasgher-sketric in #2192
• Upgrade GitHub Actions to latest versions by @salmanmkc in #2194
• Upgrade GitHub Actions for Node 24 compatibility by @salmanmkc in #2193
• Fix pypa/gh-action-pypi-publish version to use SHA pinning by @salmanmkc in #2198
• v0.6.4 by @seratch in #2184

Documents

• Print called tool's name in examples/basic/stream_items.py by @habema in #2174
• docs: Upgrading to GPT-5.2 by @cguo-oai in #2188
• Update all translated document pages by @github-actions[bot] in #2189
• docs: Resolve code snippet issues within a narrow window size by @seratch in #2197

New Contributors

• @cguo-oai made their first contribution in #2188
• @salmanmkc made their first contribution in #2194
• @Nekowaii made their first contribution in #2179
• @aliasgher-sketric made their first contribution in #2192

Full Changelog: v0.6.3...v0.6.4