Add timeout settings to function tools

[varunursekar]

Currently, in order to implement adaptable timeouts for tool invocations, one either needs to: (a) construct tools dynamically using closures, or (b) pass timeout variables via RunContext and alter the timeout logic of the function. It would be convenient for developers to be able to specify a tool_timeout and model_response_timeout in the FunctionTool and RunConfig classes respectively in order to prevent tools from taking too long; for gated OAI tools, both options are out of the picture. Ideally, for tool timeouts one can decide whether to raise an AgentsException or not.

[seratch]

Thanks for sharing the idea. Generally speaking, the tool should keep consistent and fast-enough response time, but having an option to have timeouts on the SDK side may be helpful for many situations.

To make things simpler, I think starting with only timeout settings for function tools should make sense. If many developers really need the run config level ones too, we can consider adding them later.

Here is a quick design idea. If you have any suggestions, please let me know.

@function_tool(
    timeout=0.2,  # seconds
    timeout_behavior="error_as_result",  # or "raise_exception"
    timeout_error_function=my_timeout_error,  # optional
)
def slow_tool(...):
    ...

• timeout_behavior: explicit mode:
  • "error_as_result" (default): return a timed‑out error message to the LLM.
  • "raise_exception": raise an exception and fail the run.
• timeout_error_function: optional custom formatter for timeout errors. If omitted, return a default "Timed out after Xs" style message.

Some implementation sketch:

• Add fields to FunctionTool and function_tool(...):
  • timeout_seconds: float | None
  • timeout_behavior: Literal["error_as_result", "raise_exception"]
  • timeout_error_function: ToolErrorFunction | None (timeout‑specific)
• In run_internal/tool_execution.py:
  • Wrap tool invocation with asyncio.wait_for(...).
  • On asyncio.TimeoutError, create a ToolTimeoutError.
  • If timeout_behavior == "raise_exception" → raise an exception representing the timeout error
  • Else → return error string (via timeout_error_function or default).

Sync tools + timeout caveat:

• If a sync tool has timeout set, run it via asyncio.to_thread(...) so the caller can return early.
• Important: thread execution cannot be forcibly stopped in python; work may continue in background.

Other Notes:

• Default behavior is non‑fatal (return error text), but can be switched to fatal via timeout_behavior="raise".
• This is intentionally tool‑level only (no global RunConfig timeout in this proposal).

[varunursekar]

@seratch Thank you for addressing this quickly! The design looks flexible and clear to me. My only comment would be that for sync tools, while it is definitely important to be able to time them out (perhaps even more important since they block the event loop), I am wondering if running in a thread implicitly might obfuscate what users are enabling on the backend. One option might be to add a separate run_in_thread option and raise an error on FunctionTool instantiation if timeout is not None and not asyncio.iscoroutine(func) and not run_in_thread. Wdyt?

[seratch]

I see the benefit of an explicit way to disable threading, but I don’t want to encourage always setting the flag. If someone sets run_in_thread=False, we should allow it but treat timeout as invalid (raise an error) to avoid a false sense of safety. That keeps the API simple while preserving transparency for advanced users.