Skip to content
Blog

Timeouts and Deadlines: Protecting Agents from Hanging Tool Calls

Why agent tool calls hang forever, and how to layer per-tool timeouts, deadline propagation, asyncio cancellation, and graceful degradation in the OpenAI Agents SDK.

Published on • November 16, 2026

AI Assistant

You ship a demo agent, it works beautifully in the office, and then one user asks it to check a vendor’s API. The HTTP socket stalls in a half-open state, the tool coroutine never returns, and your agent process spins forever with a single request pinned at 100% of an event-loop tick. No error, no log line, no traceback — just a hang. Multiply that by a fleet of workers and you have a support incident.

In this post, you will learn how to layer defense in depth around agent tool calls: per-tool timeout budgets, deadline propagation with remaining-budget math across nested calls, asyncio cancellation and hard kills for stuck subprocesses, model-call timeouts, telling a timeout apart from a real failure in the error the model sees, and graceful degradation when a tool can’t finish. We’ll build on the OpenAI Agents SDK, which gives us the primitives — agents, tools, guardrails, and the Runner loop — but leaves the durability policy to us.

Prerequisites

  • Python 3.10+ and pip install openai-agents
  • An OPENAI_API_KEY in your environment
  • Comfort with asyncio, contextvars, and Python decorators
  • Skim the SDK’s Tools and Running agents pages so the APIs below look familiar

Why Tools Hang

A tool call is just a Python function the Runner invokes between model turns. Three failure modes dominate in production:

  1. Network stalls. A requests call with no timeout, a keepalive connection that dies silently, or a DNS resolver that never answers. The socket is open, the app waits forever.
  2. Blocked subprocesses. subprocess.run(["git", "fetch"]) waiting on an interactive credential prompt, or a child process that inherits a pipe and never exits.
  3. Unbounded LLM calls. A nested “agent as tool” doing its own model calls with no ceiling. Each layer assumes the layer below will finish.

The SDK documents the agent loop plainly: call the LLM, execute any tool calls, re-run until the model produces final output or max_turns is exceeded. If step two never returns, the loop never advances. Timeouts are not an optimization — they are the invariant that keeps the loop a loop.

Layer 1: Per-Tool Timeout Budgets

The SDK’s function tools accept a timeout for async handlers. This is the cheapest layer: declare the budget where you declare the tool.

import asyncio
from agents import Agent, Runner
from agents.decorators import tool

@tool(timeout=5.0)
async def fetch_inventory(sku: str) -> str:
    """Look up stock for a SKU."""
    await asyncio.sleep(30)  # pretend this is a slow vendor API
    return f"{sku}: 42 in stock"

agent = Agent(name="Ops", tools=[fetch_inventory])

When the budget is exhausted, the default timeout_behavior="error_as_result" sends a model-visible message such as Tool 'fetch_inventory' timed out after 5 seconds. The run continues; the model can try a different tool or answer with what it has. That default is deliberate — a timeout is information, not a crash.

Two alternatives exist when you want the run to stop instead:

from agents import ToolTimeoutError

@tool(timeout=5.0, timeout_behavior="raise_exception")
async def critical_lookup(sku: str) -> str: ...

try:
    await Runner.run(agent, "Check the SKU")
except ToolTimeoutError as e:
    print(f"{e.tool_name} timed out in {e.timeout_seconds}s")

Use raise_exception only for tools where a partial answer is worse than no answer. Note that timeout configuration applies to async function tools only; a sync handler blocks the event loop, so wrap it with asyncio.to_thread first if you must.

Layer 2: Deadlines and Remaining-Budget Math

Per-tool timeouts don’t stop a sequence of five slow tools from each eating five seconds. For that you need a deadline for the whole run, propagated down into every nested call. A contextvar is the right vehicle: it flows into Runner.run() and into agents-as-tools automatically without threading an argument through every signature.

import contextvars, time
from contextlib import contextmanager

deadline_var: contextvars.ContextVar[float | None] = contextvars.ContextVar(
    "deadline", default=None
)

class DeadlineExceeded(Exception):
    pass

def remaining() -> float:
    d = deadline_var.get()
    return float("inf") if d is None else max(0.0, d - time.monotonic())

@contextmanager
def deadline(seconds: float):
    token = deadline_var.set(time.monotonic() + seconds)
    try:
        yield
    finally:
        deadline_var.reset(token)

@tool(timeout=5.0)
async def search_docs(query: str) -> str:
    budget = remaining()            # how much of the run is left
    if budget <= 0.5:
        raise DeadlineExceeded("run budget exhausted before tool started")
    await asyncio.sleep(min(3.0, budget))
    return f"results for {query}"

The math is trivial — remaining = deadline - now — but the discipline is what matters: every tool clips its own timeout to the remaining budget. A nested agent-as-tool inherits the same contextvar, so a sub-run that would exceed the parent’s deadline fails fast instead of doubling the wall-clock cost. Wrap the whole run with with deadline(20.0): and no combination of tools can push you past twenty seconds.

Layer 3: Cancellation and Killing Stuck Subprocesses

asyncio.wait_for is the primitive behind the SDK’s tool timeouts, and it works because task cancellation propagates. But cancellation only reaches code that awaits. Subprocesses and blocking I/O need extra care.

import asyncio, signal

async def run_with_kill(cmd: list[str], budget: float) -> str:
    proc = await asyncio.create_subprocess_exec(
        *cmd,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
        start_new_session=True,      # own process group: kill the whole tree
    )
    try:
        out, err = await asyncio.wait_for(proc.communicate(), timeout=budget)
    except asyncio.TimeoutError:
        proc.send_signal(signal.SIGTERM)          # ask nicely first
        try:
            await asyncio.wait_for(proc.wait(), timeout=2.0)
        except asyncio.TimeoutError:
            proc.kill()                            # then insist
            await proc.wait()                      # reap to avoid zombies
        raise TimeoutError(f"{' '.join(cmd)} exceeded {budget}s")
    if proc.returncode != 0:
        raise RuntimeError(err.decode() or f"exit {proc.returncode}")
    return out.decode()

Three details carry the weight here. start_new_session=True puts the child in its own process group so a hung grandchild dies with it. The two-phase SIGTERM then SIGKILL gives well-behaved tools a chance to clean up. And the final await proc.wait() reaps the process — skipping it leaks zombies in a long-lived worker.

For the rest of the run, an outer asyncio.timeout(...) (Python 3.11+) or asyncio.wait_for(Runner.run(...), timeout=budget) gives you a hard ceiling even if some tool ignores its budget.

Layer 4: Bounding Model Calls

Tools aren’t the only unbounded await. The SDK exposes ModelSettings.timeout, which bounds each model-call attempt including transport waits; exceeding it cancels the attempt, waits for cleanup, and raises ModelTimeoutError. It does not limit the whole run, tool execution, or retry backoff — which is exactly why it complements, rather than replaces, the layers above.

from agents import Agent, ModelSettings

agent = Agent(
    name="Ops",
    model_settings=ModelSettings(timeout=30.0),
    tools=[fetch_inventory],
)

Combine it with RunConfig(tool_execution=ToolExecutionConfig(max_function_tool_concurrency=4)) so a model that emits twenty parallel tool calls doesn’t open twenty sockets at once.

Telling Timeout Apart From Failure

The string the model receives decides what it does next. “Timed out, retry differently” and “tool is broken, stop using it” must not look the same. Beyond the default timeout message, the SDK gives you two hooks.

failure_error_function shapes what a crashing tool reports to the model:

from agents import RunContextWrapper

def tool_error(ctx: RunContextWrapper, error: Exception) -> str:
    if isinstance(error, TimeoutError):
        return "TOOL_TIMEOUT: upstream did not respond. Do not retry this tool; use the cache tool instead."
    return "TOOL_ERROR: unexpected failure. Report it and stop."

@tool(failure_error_function=tool_error)
async def vendor_lookup(sku: str) -> str: ...

For run-wide messages — approval rejections, unknown tool names — pass RunConfig(tool_error_formatter=...), which receives a ToolErrorFormatterArgs with kind, tool_name, call_id, and default_message. Returning None keeps the SDK default; returning a string replaces it. A structured, machine-parsable prefix (TOOL_TIMEOUT:) beats prose: models follow explicit instructions in the error far more reliably than hints buried in a sentence.

Graceful Degradation

The last layer is product behavior: what does the user see when the deadline hits? Two SDK features do the heavy lifting.

First, degrade inside the tool. On timeout, return the best partial data you already have — a cache hit, a stale snapshot, an empty-but-well-formed result — clearly labeled. Second, catch run-level failure with error_handlers:

from agents import Runner, RunErrorHandlerResult

def on_max_turns(_data) -> RunErrorHandlerResult:
    return RunErrorHandlerResult(
        final_output="I ran out of time to finish this. Here's what I found so far; ask me to continue.",
        include_in_history=True,
    )

result = Runner.run_sync(agent, "Audit all vendors", max_turns=6,
                         error_handlers={"max_turns": on_max_turns})

The pattern to internalize: timeouts surface as recoverable model-visible results by default, and escalate to exceptions only where you opt in. That’s the opposite of most web frameworks, and it’s correct — the model is the only component that can actually choose a different plan.

Putting It All Together

The pieces compose into a run with a wall-clock ceiling:

import asyncio
from agents import Agent, ModelSettings, Runner

async def main():
    agent = Agent(
        name="Ops",
        instructions="Use tools to answer. If a tool times out, say so and continue.",
        model_settings=ModelSettings(timeout=30.0),
        tools=[fetch_inventory, search_docs],   # both carry timeout=...
    )
    async with asyncio.timeout(20):            # hard ceiling over everything
        result = await Runner.run(agent, "Check SKU-123 and summarize")
    print(result.final_output)

asyncio.run(main())

Expected output when the vendor API stalls:

SKU-123 is out of stock per the live lookup — that tool timed out after 5s,
so I'm reporting the cached value from 10 minutes ago: 42 in stock.

Wall-clock: exactly 20 seconds, worst case. The process exits, the loop survives, and the user gets a truthful, qualified answer instead of a spinner.

Conclusion and Next Steps

You now have four independent layers — per-tool timeouts, propagated deadlines with remaining-budget math, cancellation and subprocess kills, and model-call timeouts — plus two response strategies: model-visible timeout messages with failure_error_function / tool_error_formatter, and run-level recovery with error_handlers. Each layer catches what the one below it can’t, which is the only way to bound a system whose components are themselves unbounded.

Homework: (1) add a deadline budget to an existing agent and log remaining() at every tool entry — you’ll be surprised how little budget survives the first nested call; (2) run your worst tool under asyncio.timeout and confirm its grandchild processes actually die; (3) wire ModelTimeoutError and ToolTimeoutError into your tracing so you can graph timeout rate per tool — that metric is your earliest warning that a dependency is degrading.