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, they are disabled by default. To enable them, 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

v0.6.3

What's Changed

• feat: preserve logprobs from chat completions API in ModelResponse by @JRMeyer in #2134
• Attach context to apply patch operations by @gustavz in #2162
• [fix] Realtime CLI demo energy threshold by @lionel-oai in #2166
• upgrade openai dep to v2.9.0 by @rm-openai in #2177
• v0.6.3 by @rm-openai in #2178

New Contributors

• @JRMeyer made their first contribution in #2134
• @gustavz made their first contribution in #2162
• @lionel-oai made their first contribution in #2166

Full Changelog: v0.6.2...v0.6.3

v0.6.2

What's Changed

• fix: allow static tool filtering without agent and run_context in MCPServer by @sevakva in #2108
• Fix as_tool returning blank string on early tool termination by @ihower in #2112
• docs: clarify handoff() docs, callable not supported by @ihower in #2116
• Fix: usage from earlier stream chunks when later chunks have none by @ihower in #2126
• Fix #2130 streaming hang when session.add_items raises an exception by @ihower in #2131
• fix: save conversation to session before handoff for non-streaming path by @mjschock in #2128
• docs: add community session implementations section by @knowsuchagency in #2139
• Update all translated document pages by @github-actions[bot] in #2142
• fix(usage): Normalize None token detail objects on Usage initialization by @codefromthecrypt in #2141
• Enable previous_response_id chaining for internal calls on the first turn by @ihower in #2117
• fix(litellm): preserve reasoning.summary when passing to LiteLLM by @Chesars in #2144
• Update all translated document pages by @github-actions[bot] in #2147
• Allow user to send None values to Realtime API by @Sean-Der in #2152
• v0.6.2 by @rm-openai in #2153

New Contributors

• @sevakva made their first contribution in #2108
• @mjschock made their first contribution in #2128
• @Chesars made their first contribution in #2144
• @Sean-Der made their first contribution in #2152

Full Changelog: v0.6.1...v0.6.2

v0.6.1

What's Changed

• fix: invalid model setting when passing prompt to Agent by @seratch in #1852
• docs: document input guardrail execution modes by @RVV-karma in #2084
• Update all translated document pages by @github-actions[bot] in #2104
• fix: #2097 fix the default settings for SIP realtime runner by @seratch in #2105
• version 0.6.1 by @seratch in #2106

Full Changelog: v0.6.0...v0.6.1