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-levelfailure_error_functionvalues override the agent-level setting, so setfailure_error_function=Noneon 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