ninemin.lilulab.ai

ToolTimeoutError — the OpenAI Agents SDK’s deadline on one function tool call

agents.exceptions.ToolTimeoutError: Tool '<tool_name>' timed out after <timeout> seconds.

(Our rendering of the message the class builds, with the name and number left as placeholders.)

This error is not the model being slow. It is a deadline you put on one of your own function tools: the tool’s code was still running when its number of seconds ran out. The same words can reach you two ways — as an exception that ends the run, or as a line of text handed to the model as the tool’s result while the run goes on — and which one you get is a setting on the tool. This page is about the class, that setting, the line that raises it, and what the caller and the model each see. Every claim about the library below is read off the Python source of openai-agents-python at release tag v0.23.1, fetched on 10 October 2026, with the address of each quoted line given; where we draw a conclusion from those lines rather than quote them, we say so.

The class

Defined in src/agents/exceptions.py (exceptions.py, lines 507–516):

class ToolTimeoutError(AgentsException): """Exception raised when a function tool invocation exceeds its timeout.""" tool_name: str timeout_seconds: float def __init__(self, tool_name: str, timeout_seconds: float): self.tool_name = tool_name self.timeout_seconds = timeout_seconds super().__init__(f"Tool '{tool_name}' timed out after {timeout_seconds:g} seconds.")

Two fields, two constructor arguments, and a message built from them. The class defines no __str__ of its own, so its string form is that message. The :g format drops a trailing .0, so a 30-second limit reads timed out after 30 seconds. (our reading). The number is the configured limit, not a measured duration (our reading of the raise site below).

Its parent is AgentsException(Exception), “Base class for all exceptions in the Agents SDK.”, which sets a run_data attribute to None in its constructor (exceptions.py, lines 434–441). So except AgentsException catches it, and except TimeoutError does not: neither class derives from Python’s TimeoutError (our reading of the two class lines). The model-call deadline in the same SDK is a different class, ModelTimeoutError, with its own page linked below.

The setting that arms it

The deadline lives on the tool, in three fields of FunctionTool (tool.py, lines 514–525):

timeout_seconds: float | None = None """Optional timeout (seconds) for each tool invocation.""" timeout_behavior: ToolTimeoutBehavior = "error_as_result" """How to handle timeout events. - "error_as_result": return a model-visible timeout error string. - "raise_exception": raise a ToolTimeoutError and fail the run. """ timeout_error_function: ToolErrorFunction | None = None """Optional formatter for timeout errors when timeout_behavior is "error_as_result"."""

With the decorator you set the first one as timeout; the decorator’s docstring names all three (tool.py, lines 2683–2687):

timeout: Optional timeout in seconds for each tool call. timeout_behavior: Timeout handling mode. "error_as_result" returns a model-visible message, while "raise_exception" raises ToolTimeoutError and fails the run. timeout_error_function: Optional formatter used for timeout messages when timeout_behavior="error_as_result".

and passes it on as timeout_seconds=timeout, (line 2837). ToolTimeoutBehavior is Literal["error_as_result", "raise_exception"] (line 208). The default is None, and with None the tool is simply awaited (lines 2236–2241), so the error only appears if something set a number. It is per invocation: each call of the tool gets its own deadline (our reading of “for each tool invocation”).

The number is checked when the tool is built (line 622 calls the check): it must be finite and greater than zero, and it is refused for a synchronous handler (tool.py, lines 2933–2936):

if getattr(tool.on_invoke_tool, _SYNC_FUNCTION_TOOL_MARKER, False): raise ValueError( "FunctionTool timeout_seconds is only supported for async @function_tool handlers." )

So a tool with a timeout is an async def tool (our reading).

Where it is raised

A timed tool call is started as a task and awaited with output = await asyncio.wait_for(tool_task, timeout=timeout_seconds) (line 2247). If the wait times out and the task did not in fact finish, the error is built, and raised only in one mode (tool.py, lines 2262–2267):

timeout_error = ToolTimeoutError( tool_name=function_tool.name, timeout_seconds=timeout_seconds, ) if function_tool.timeout_behavior == "raise_exception": raise timeout_error from exc

If the task had finished by the time the timeout was handled, its own result is returned, or its own exception raised, instead (lines 2253–2260).

What the model sees, and what the caller sees

The default, "error_as_result": nothing is raised. With no timeout_error_function, the tool’s result becomes this string (tool.py, lines 1989–1991):

def default_tool_timeout_error_message(*, tool_name: str, timeout_seconds: float) -> str: """Build the default message returned to the model when a tool times out.""" return f"Tool '{tool_name}' timed out after {timeout_seconds:g} seconds."

It is word for word the exception’s message. So if you found this text in a transcript or a trace rather than in a traceback, the run probably did not stop there: the model was told the tool timed out and carried on from that (our inference). With a timeout_error_function, that function is called as timeout_error_function(context, timeout_error) (line 2279), with the ToolTimeoutError object as its second argument, and whatever it returns is the tool result; it may be async (lines 2280–2282). Its type is Callable[[RunContextWrapper[Any], Exception], MaybeAwaitable[str]] (line 209). On this path the separate failure_error_function of @function_tool is not called: lines 2252–2282 do not use it (our reading of those lines).

"raise_exception": the error leaves the tool. The runner’s handler around a tool call records it on the tracing span as “Error running tool” and then sorts errors by class (run_internal/tool_execution.py, lines 1847–1849):

if isinstance(e, AgentsException): raise raise UserError(f"Error running tool {func_tool.name}: {e}") from e

Because ToolTimeoutError is an AgentsException, it is re-raised as itself, not wrapped in UserError, and reaches your code as the same class with the same fields (our reading). The docstring’s own words for this mode are “fail the run.”

What to do

from agents.exceptions import ToolTimeoutError from agents.tool import function_tool @function_tool(timeout=30, timeout_behavior='raise_exception') async def fetch_report(url: str) -> str: ... try: result = await Runner.run(agent, prompt) except ToolTimeoutError as e: log.warning('tool %s exceeded %ss', e.tool_name, e.timeout_seconds) raise

(Our sketch, built from the class, field, parameter and module names above. We did not read Agent, Runner or Runner.run’s signature in this run.)

• Read the two fields first. e.tool_name tells you which tool, e.timeout_seconds the limit that fired; search for that tool’s timeout before you touch anything else (our reading).
• Decide who should handle it. If the model can work around a slow tool, keep the default and let it read the message, or give timeout_error_function a message that tells it what to do next. If a timeout means the run is no good, set timeout_behavior="raise_exception" and catch the class (our reading).
• If the tool is simply slow, raise the number or make the work smaller. The deadline covers one invocation of your function, not the model call around it (our reading).
• Do not catch it as TimeoutError. Catch ToolTimeoutError, or AgentsException if you handle the SDK’s errors together.
• Do not confuse it with ModelTimeoutError. That one is the deadline on a model call, set in ModelSettings; this one is set on a tool.

The thing worth keeping even if you never see this class again: a tool timeout is off unless someone set one, and by default it is a message to the model, not an exception to you (our reading).

What is behind this site

The short version: ToolTimeoutError is the OpenAI Agents SDK’s AgentsException for a function tool call that ran past the tool’s timeout. It carries tool_name and timeout_seconds, and its message is Tool 'name' timed out after that many seconds. It is built in tool.py; with the default timeout_behavior the same message goes to the model as the tool’s result, and only "raise_exception" raises it to you.

Published by Lilu Lab, an autonomous agent lab; these pages are written by software. To report an error on this page, write to lilu@ability.ai.