feat: #2346 add configurable timeout handling for function tools (#2479)

Author: seratch

src/agents/__init__.py

@@ -26,6 +26,7 @@
     RunErrorDetails,
     ToolInputGuardrailTripwireTriggered,
     ToolOutputGuardrailTripwireTriggered,
+    ToolTimeoutError,
     UserError,
 )
 from .guardrail import (
@@ -285,6 +286,7 @@ def enable_verbose_stdout_logging():
     "Prompt",
     "MaxTurnsExceeded",
     "ModelBehaviorError",
+    "ToolTimeoutError",
     "UserError",
     "InputGuardrail",
     "InputGuardrailResult",

src/agents/exceptions.py

@@ -75,6 +75,18 @@ def __init__(self, message: str):
         super().__init__(message)
 
 
+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.")
+
+
 class InputGuardrailTripwireTriggered(AgentsException):
     """Exception raised when a guardrail tripwire is triggered."""
 

src/agents/realtime/session.py

@@ -15,7 +15,7 @@
 from ..logger import logger
 from ..run_config import ToolErrorFormatterArgs
 from ..run_context import RunContextWrapper, TContext
-from ..tool import DEFAULT_APPROVAL_REJECTION_MESSAGE, FunctionTool
+from ..tool import DEFAULT_APPROVAL_REJECTION_MESSAGE, FunctionTool, invoke_function_tool
 from ..tool_context import ToolContext
 from ..util._approvals import evaluate_needs_approval_setting
 from .agent import RealtimeAgent
@@ -602,7 +602,11 @@ async def _handle_tool_call(
                 tool_arguments=event.arguments,
                 agent=agent,
             )
-            result = await func_tool.on_invoke_tool(tool_context, event.arguments)
+            result = await invoke_function_tool(
+                function_tool=func_tool,
+                context=tool_context,
+                arguments=event.arguments,
+            )
 
             await self._model.send_event(
                 RealtimeModelSendToolOutput(

src/agents/run_internal/tool_execution.py

@@ -52,6 +52,7 @@
     ShellCallOutcome,
     ShellCommandOutput,
     Tool,
+    invoke_function_tool,
     resolve_computer,
 )
 from ..tool_context import ToolContext
@@ -897,7 +898,11 @@ async def run_single_tool(func_tool: FunctionTool, tool_call: ResponseFunctionTo
                             else _coro.noop_coroutine()
                         ),
                     )
-                    real_result = await func_tool.on_invoke_tool(tool_context, tool_call.arguments)
+                    real_result = await invoke_function_tool(
+                        function_tool=func_tool,
+                        context=tool_context,
+                        arguments=tool_call.arguments,
+                    )
 
                     final_result = await _execute_tool_output_guardrails(
                         func_tool=func_tool,

src/agents/tool.py

@@ -3,6 +3,7 @@
 import asyncio
 import inspect
 import json
+import math
 import weakref
 from collections.abc import Awaitable, Mapping
 from dataclasses import dataclass, field
@@ -35,7 +36,7 @@
 from . import _debug
 from .computer import AsyncComputer, Computer
 from .editor import ApplyPatchEditor, ApplyPatchOperation
-from .exceptions import ModelBehaviorError, UserError
+from .exceptions import ModelBehaviorError, ToolTimeoutError, UserError
 from .function_schema import DocstringStyle, function_schema
 from .logger import logger
 from .run_context import RunContextWrapper
@@ -64,6 +65,9 @@
 ]
 
 DEFAULT_APPROVAL_REJECTION_MESSAGE = "Tool execution was not approved."
+ToolTimeoutBehavior = Literal["error_as_result", "raise_exception"]
+ToolErrorFunction = Callable[[RunContextWrapper[Any], Exception], MaybeAwaitable[str]]
+_SYNC_FUNCTION_TOOL_MARKER = "__agents_sync_function_tool__"
 
 
 class ToolOutputText(BaseModel):
@@ -259,6 +263,20 @@ class FunctionTool:
     function that takes (run_context, tool_parameters, call_id) and returns whether this
     specific call needs approval."""
 
+    # Keep timeout fields after needs_approval to preserve positional constructor compatibility.
+    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"."""
+
     _is_agent_tool: bool = field(default=False, init=False, repr=False)
     """Internal flag indicating if this tool is an agent-as-tool."""
 
@@ -271,6 +289,7 @@ class FunctionTool:
     def __post_init__(self):
         if self.strict_json_schema:
             self.params_json_schema = ensure_strict_json_schema(self.params_json_schema)
+        _validate_function_tool_timeout_config(self)
 
 
 @dataclass
@@ -905,8 +924,59 @@ def default_tool_error_function(ctx: RunContextWrapper[Any], error: Exception) -
     return f"An error occurred while running the tool. Please try again. Error: {str(error)}"
 
 
-ToolErrorFunction = Callable[[RunContextWrapper[Any], Exception], MaybeAwaitable[str]]
 _UNSET_FAILURE_ERROR_FUNCTION = object()
+_FUNCTION_TOOL_TIMEOUT_BEHAVIORS: tuple[ToolTimeoutBehavior, ...] = (
+    "error_as_result",
+    "raise_exception",
+)
+
+
+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."
+
+
+async def invoke_function_tool(
+    *,
+    function_tool: FunctionTool,
+    context: ToolContext[Any],
+    arguments: str,
+) -> Any:
+    """Invoke a function tool, enforcing timeout configuration when provided."""
+    timeout_seconds = function_tool.timeout_seconds
+    if timeout_seconds is None:
+        return await function_tool.on_invoke_tool(context, arguments)
+
+    tool_task: asyncio.Future[Any] = asyncio.ensure_future(
+        function_tool.on_invoke_tool(context, arguments)
+    )
+    try:
+        return await asyncio.wait_for(tool_task, timeout=timeout_seconds)
+    except asyncio.TimeoutError as exc:
+        if tool_task.done() and not tool_task.cancelled():
+            tool_exception = tool_task.exception()
+            if tool_exception is None:
+                return tool_task.result()
+            raise tool_exception from None
+
+        timeout_error = ToolTimeoutError(
+            tool_name=function_tool.name,
+            timeout_seconds=timeout_seconds,
+        )
+        if function_tool.timeout_behavior == "raise_exception":
+            raise timeout_error from exc
+
+        timeout_error_function = function_tool.timeout_error_function
+        if timeout_error_function is None:
+            return default_tool_timeout_error_message(
+                tool_name=function_tool.name,
+                timeout_seconds=timeout_seconds,
+            )
+
+        timeout_result = timeout_error_function(context, timeout_error)
+        if inspect.isawaitable(timeout_result):
+            return await timeout_result
+        return timeout_result
 
 
 @overload
@@ -924,6 +994,9 @@ def function_tool(
     | Callable[[RunContextWrapper[Any], dict[str, Any], str], Awaitable[bool]] = False,
     tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
     tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
+    timeout: float | None = None,
+    timeout_behavior: ToolTimeoutBehavior = "error_as_result",
+    timeout_error_function: ToolErrorFunction | None = None,
 ) -> FunctionTool:
     """Overload for usage as @function_tool (no parentheses)."""
     ...
@@ -943,6 +1016,9 @@ def function_tool(
     | Callable[[RunContextWrapper[Any], dict[str, Any], str], Awaitable[bool]] = False,
     tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
     tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
+    timeout: float | None = None,
+    timeout_behavior: ToolTimeoutBehavior = "error_as_result",
+    timeout_error_function: ToolErrorFunction | None = None,
 ) -> Callable[[ToolFunction[...]], FunctionTool]:
     """Overload for usage as @function_tool(...)."""
     ...
@@ -962,6 +1038,9 @@ def function_tool(
     | Callable[[RunContextWrapper[Any], dict[str, Any], str], Awaitable[bool]] = False,
     tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
     tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
+    timeout: float | None = None,
+    timeout_behavior: ToolTimeoutBehavior = "error_as_result",
+    timeout_error_function: ToolErrorFunction | None = None,
 ) -> FunctionTool | Callable[[ToolFunction[...]], FunctionTool]:
     """
     Decorator to create a FunctionTool from a function. By default, we will:
@@ -1000,9 +1079,15 @@ def function_tool(
             whether this specific call needs approval.
         tool_input_guardrails: Optional list of guardrails to run before invoking the tool.
         tool_output_guardrails: Optional list of guardrails to run after the tool returns.
+        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".
     """
 
     def _create_function_tool(the_func: ToolFunction[...]) -> FunctionTool:
+        is_sync_function_tool = not inspect.iscoroutinefunction(the_func)
         schema = function_schema(
             func=the_func,
             name_override=name_override,
@@ -1043,7 +1128,7 @@ async def _on_invoke_tool_impl(ctx: ToolContext[Any], input: str) -> Any:
             if not _debug.DONT_LOG_TOOL_DATA:
                 logger.debug(f"Tool call args: {args}, kwargs: {kwargs_dict}")
 
-            if inspect.iscoroutinefunction(the_func):
+            if not is_sync_function_tool:
                 if schema.takes_context:
                     result = await the_func(ctx, *args, **kwargs_dict)
                 else:
@@ -1106,6 +1191,9 @@ async def _on_invoke_tool(ctx: ToolContext[Any], input: str) -> Any:
                     )
                 return result
 
+        if is_sync_function_tool:
+            setattr(_on_invoke_tool, _SYNC_FUNCTION_TOOL_MARKER, True)
+
         return FunctionTool(
             name=schema.name,
             description=schema.description or "",
@@ -1116,6 +1204,9 @@ async def _on_invoke_tool(ctx: ToolContext[Any], input: str) -> Any:
             needs_approval=needs_approval,
             tool_input_guardrails=tool_input_guardrails,
             tool_output_guardrails=tool_output_guardrails,
+            timeout_seconds=timeout,
+            timeout_behavior=timeout_behavior,
+            timeout_error_function=timeout_error_function,
         )
 
     # If func is actually a callable, we were used as @function_tool with no parentheses
@@ -1140,6 +1231,34 @@ def _is_computer_provider(candidate: object) -> bool:
     )
 
 
+def _validate_function_tool_timeout_config(tool: FunctionTool) -> None:
+    timeout_seconds = tool.timeout_seconds
+    if timeout_seconds is not None:
+        if isinstance(timeout_seconds, bool) or not isinstance(timeout_seconds, (int, float)):
+            raise TypeError(
+                "FunctionTool timeout_seconds must be a positive number in seconds or None."
+            )
+        timeout_seconds = float(timeout_seconds)
+        if not math.isfinite(timeout_seconds):
+            raise ValueError("FunctionTool timeout_seconds must be a finite number.")
+        if timeout_seconds <= 0:
+            raise ValueError("FunctionTool timeout_seconds must be greater than 0.")
+        if getattr(tool.on_invoke_tool, _SYNC_FUNCTION_TOOL_MARKER, False):
+            raise ValueError(
+                "FunctionTool timeout_seconds is only supported for async @function_tool handlers."
+            )
+        tool.timeout_seconds = timeout_seconds
+
+    if tool.timeout_behavior not in _FUNCTION_TOOL_TIMEOUT_BEHAVIORS:
+        raise ValueError(
+            "FunctionTool timeout_behavior must be one of: "
+            + ", ".join(_FUNCTION_TOOL_TIMEOUT_BEHAVIORS)
+        )
+
+    if tool.timeout_error_function is not None and not callable(tool.timeout_error_function):
+        raise TypeError("FunctionTool timeout_error_function must be callable or None.")
+
+
 def _store_computer_initializer(tool: ComputerTool[Any]) -> None:
     config = tool.computer
     if callable(config) or _is_computer_provider(config):

tests/realtime/test_session.py

@@ -307,9 +307,16 @@ def mock_model():
     return MockRealtimeModel()
 
 
+def _set_default_timeout_fields(tool: Mock) -> Mock:
+    tool.timeout_seconds = None
+    tool.timeout_behavior = "error_as_result"
+    tool.timeout_error_function = None
+    return tool
+
+
 @pytest.fixture
 def mock_function_tool():
-    tool = Mock(spec=FunctionTool)
+    tool = _set_default_timeout_fields(Mock(spec=FunctionTool))
     tool.name = "test_function"
     tool.on_invoke_tool = AsyncMock(return_value="function_result")
     tool.needs_approval = False
@@ -1017,16 +1024,46 @@ async def test_function_tool_execution_success(
         assert tool_end_event.agent == mock_agent
         assert tool_end_event.arguments == '{"param": "value"}'
 
+    @pytest.mark.asyncio
+    async def test_function_tool_timeout_returns_result_message(self, mock_model, mock_agent):
+        async def invoke_slow_tool(_ctx: ToolContext[Any], _arguments: str) -> str:
+            await asyncio.sleep(0.2)
+            return "done"
+
+        timeout_tool = FunctionTool(
+            name="slow_tool",
+            description="slow",
+            params_json_schema={"type": "object", "properties": {}},
+            on_invoke_tool=invoke_slow_tool,
+            timeout_seconds=0.01,
+        )
+        mock_agent.get_all_tools.return_value = [timeout_tool]
+
+        session = RealtimeSession(mock_model, mock_agent, None)
+        tool_call_event = RealtimeModelToolCallEvent(
+            name="slow_tool",
+            call_id="call_timeout",
+            arguments="{}",
+        )
+
+        await session._handle_tool_call(tool_call_event)
+
+        assert len(mock_model.sent_tool_outputs) == 1
+        sent_call, sent_output, start_response = mock_model.sent_tool_outputs[0]
+        assert sent_call == tool_call_event
+        assert start_response is True
+        assert "timed out" in sent_output.lower()
+
     @pytest.mark.asyncio
     async def test_function_tool_with_multiple_tools_available(self, mock_model, mock_agent):
         """Test function tool execution when multiple tools are available"""
         # Create multiple mock tools
-        tool1 = Mock(spec=FunctionTool)
+        tool1 = _set_default_timeout_fields(Mock(spec=FunctionTool))
         tool1.name = "tool_one"
         tool1.on_invoke_tool = AsyncMock(return_value="result_one")
         tool1.needs_approval = False
 
-        tool2 = Mock(spec=FunctionTool)
+        tool2 = _set_default_timeout_fields(Mock(spec=FunctionTool))
         tool2.name = "tool_two"
         tool2.on_invoke_tool = AsyncMock(return_value="result_two")
         tool2.needs_approval = False
@@ -1329,7 +1366,7 @@ async def test_tool_call_with_custom_call_id(self, mock_model, mock_agent, mock_
     async def test_tool_result_conversion_to_string(self, mock_model, mock_agent):
         """Test that tool results are converted to strings for model output"""
         # Create tool that returns non-string result
-        tool = Mock(spec=FunctionTool)
+        tool = _set_default_timeout_fields(Mock(spec=FunctionTool))
         tool.name = "test_function"
         tool.on_invoke_tool = AsyncMock(return_value={"result": "data", "count": 42})
         tool.needs_approval = False
@@ -1353,15 +1390,15 @@ async def test_tool_result_conversion_to_string(self, mock_model, mock_agent):
     async def test_mixed_tool_types_filtering(self, mock_model, mock_agent):
         """Test that function tools and handoffs are properly separated"""
         # Create mixed tools
-        func_tool1 = Mock(spec=FunctionTool)
+        func_tool1 = _set_default_timeout_fields(Mock(spec=FunctionTool))
         func_tool1.name = "func1"
         func_tool1.on_invoke_tool = AsyncMock(return_value="result1")
         func_tool1.needs_approval = False
 
         handoff1 = Mock(spec=Handoff)
         handoff1.name = "handoff1"
 
-        func_tool2 = Mock(spec=FunctionTool)
+        func_tool2 = _set_default_timeout_fields(Mock(spec=FunctionTool))
         func_tool2.name = "func2"
         func_tool2.on_invoke_tool = AsyncMock(return_value="result2")
         func_tool2.needs_approval = False