Skip to content

Commit be4737f

Browse files
feat: add timeout result policy for Codex function tools
1 parent ea29bd1 commit be4737f

12 files changed

Lines changed: 1023 additions & 34 deletions

File tree

‎examples/codex/tool_timeout.py‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
"""Choose a failed timeout result or a typed exception for each tool invocation."""
2+
3+
import asyncio
4+
5+
from agents import Agent, ToolContext, ToolTimeoutError, function_tool
6+
7+
8+
async def timeout_message(context: ToolContext[None], error: ToolTimeoutError) -> str:
9+
return f"{error.tool_name} exceeded {error.timeout_seconds:g} seconds. Try another approach."
10+
11+
12+
@function_tool(
13+
callback_timeout=0.1,
14+
timeout_behavior="error_as_result",
15+
timeout_error_function=timeout_message,
16+
)
17+
async def lookup(record: str) -> dict[str, str]:
18+
"""Look up a record through a slow external service."""
19+
await asyncio.sleep(1)
20+
return {"record": record}
21+
22+
23+
async def main() -> None:
24+
agent = Agent(instructions="Use lookup once, then explain its result.", tools=[lookup])
25+
result = await agent.run("Look up record-a.")
26+
print(result.final_output)
27+
# The default timeout_behavior="raise_exception" raises ToolTimeoutError.
28+
# Neither policy undoes side effects. Cleanup can delay completion.
29+
# Timeout text bypasses the normal result type and the after hook.
30+
31+
32+
if __name__ == "__main__":
33+
asyncio.run(main())

‎packages/codex/src/_agents_codex/_function_tools.py‎

Lines changed: 56 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,24 @@
7474
ParametersT = ParamSpec("ParametersT")
7575

7676

77+
ToolTimeoutBehavior: TypeAlias = Literal["raise_exception", "error_as_result"]
78+
79+
80+
class ToolTimeoutError(TimeoutError):
81+
"""A function invocation exceeded its callback deadline.
82+
83+
Cleanup is joined before the timeout settles. Effects already performed
84+
by the callback are not undone.
85+
"""
86+
87+
def __init__(self, tool_name: str, timeout_seconds: float):
88+
self.tool_name = tool_name
89+
self.timeout_seconds = timeout_seconds
90+
super().__init__(
91+
f"Tool {tool_name!r} exceeded its callback timeout after {timeout_seconds:g} seconds"
92+
)
93+
94+
7795
@dataclass(frozen=True)
7896
class ToolContext(Generic[ContextT_co]):
7997
"""Application context and the admitted native invocation's identity.
@@ -125,6 +143,10 @@ class FunctionTool(Generic[InputT, ResultT, BinderT_co]):
125143
field(default=None, repr=False)
126144
)
127145
defer_loading: bool = False
146+
timeout_behavior: ToolTimeoutBehavior = "raise_exception"
147+
timeout_error_function: (
148+
Callable[[ToolContext[Any], ToolTimeoutError], str | Awaitable[str]] | None
149+
) = field(default=None, repr=False)
128150

129151
def __post_init__(self) -> None:
130152
if not isinstance(self.defer_loading, bool):
@@ -135,6 +157,12 @@ def __post_init__(self) -> None:
135157
callback = getattr(self, name)
136158
if callback is not None and not callable(callback):
137159
raise TypeError(f"FunctionTool {name} must be callable")
160+
if self.timeout_behavior not in ("raise_exception", "error_as_result"):
161+
raise ValueError(
162+
"FunctionTool timeout_behavior must be raise_exception or error_as_result"
163+
)
164+
if self.timeout_error_function is not None and not callable(self.timeout_error_function):
165+
raise TypeError("FunctionTool timeout_error_function must be callable or None")
138166
duration = self.callback_timeout
139167
if duration is not None and (
140168
isinstance(duration, bool)
@@ -145,7 +173,11 @@ def __post_init__(self) -> None:
145173
"FunctionTool callback_timeout must be a positive finite number or None"
146174
)
147175
if self._bind is None and (
148-
self.before is not None or self.after is not None or self.callback_timeout is not None
176+
self.before is not None
177+
or self.after is not None
178+
or self.callback_timeout is not None
179+
or self.timeout_behavior != "raise_exception"
180+
or self.timeout_error_function is not None
149181
):
150182
raise TypeError("Callback settings require a callback registered with function_tool")
151183

@@ -189,7 +221,10 @@ def _check_context(self, context: object) -> None:
189221
)
190222
if self._bind is not None:
191223
if context is None:
192-
for name in ("before", "after"):
224+
policies: tuple[str, ...] = ("before", "after")
225+
if self.callback_timeout is not None and self.timeout_behavior == "error_as_result":
226+
policies += ("timeout_error_function",)
227+
for name in policies:
193228
callback = getattr(self, name)
194229
if callback is None:
195230
continue
@@ -286,6 +321,9 @@ def function_tool(
286321
after: Callable[[ToolContext[Any], ToolOutput], ToolOutput | Awaitable[ToolOutput]]
287322
| None = None,
288323
defer_loading: bool = False,
324+
timeout_behavior: ToolTimeoutBehavior = "raise_exception",
325+
timeout_error_function: Callable[[ToolContext[Any], ToolTimeoutError], str | Awaitable[str]]
326+
| None = None,
289327
) -> _ToolDecorator: ...
290328

291329

@@ -304,6 +342,9 @@ def function_tool(
304342
after: Callable[[ToolContext[Any], ToolOutput], ToolOutput | Awaitable[ToolOutput]]
305343
| None = None,
306344
defer_loading: bool = False,
345+
timeout_behavior: ToolTimeoutBehavior = "raise_exception",
346+
timeout_error_function: Callable[[ToolContext[Any], ToolTimeoutError], str | Awaitable[str]]
347+
| None = None,
307348
) -> _PythonTool[Any] | _ToolDecorator:
308349
"""Declare a Python tool without starting a connection or runtime.
309350
@@ -326,6 +367,15 @@ def function_tool(
326367
a callback that refuses to finish can delay completion. Argument validation,
327368
result conversion and effects already performed are outside this deadline.
328369
370+
``timeout_behavior="raise_exception"`` preserves turn failure with
371+
ToolTimeoutError. With ``"error_as_result"``, joined expiry returns a failed
372+
textual ToolOutput to the model without validating the normal return type
373+
or running the after hook. ``timeout_error_function(context, error)`` can
374+
supply this text synchronously or asynchronously; it runs only in result
375+
mode after callback cleanup, while the invocation is still admitted.
376+
Formatter errors fail the turn. Without a deadline, these options are inactive.
377+
Timeout does not undo effects already performed by application code.
378+
329379
Observe tool starts and results through Session.events().
330380
331381
defer_loading=True requests native schema discovery for this declaration
@@ -384,6 +434,8 @@ def bind(context: object, declaration: FunctionTool[Any, Any, Any]) -> _Captured
384434
context=context,
385435
context_parameter=context_parameter,
386436
callback_timeout=declaration.callback_timeout,
437+
timeout_behavior=declaration.timeout_behavior,
438+
timeout_error_function=declaration.timeout_error_function,
387439
before=declaration.before,
388440
after=declaration.after,
389441
)
@@ -399,6 +451,8 @@ def bind(context: object, declaration: FunctionTool[Any, Any, Any]) -> _Captured
399451
before=before,
400452
after=after,
401453
defer_loading=defer_loading,
454+
timeout_behavior=timeout_behavior,
455+
timeout_error_function=timeout_error_function,
402456
)
403457

404458
return decorate(function) if function is not None else decorate

‎packages/codex/src/_agents_codex/session.py‎

Lines changed: 102 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,12 @@
6060
SessionItem as SessionItem,
6161
WebSearchCallItem,
6262
)
63-
from ._function_tools import FunctionTool as FunctionTool, Tool as Tool, ToolContext as ToolContext
63+
from ._function_tools import (
64+
FunctionTool as FunctionTool,
65+
Tool as Tool,
66+
ToolContext as ToolContext,
67+
ToolTimeoutError as ToolTimeoutError,
68+
)
6469
from ._history import project_history as project_history
6570
from ._lifecycle import (
6671
_close_after_error as _close_after_error,
@@ -8456,6 +8461,7 @@ async def _invoke_tool_body(
84568461
args = (context,)
84578462
if not self._admit_tool(state, request):
84588463
return
8464+
timeout_output: ToolOutput | None = None
84598465
duration = entry.callback_timeout
84608466
if duration is None:
84618467
value = await _call_callback(
@@ -8464,12 +8470,84 @@ async def _invoke_tool_body(
84648470
*args,
84658471
**kwargs,
84668472
)
8473+
elif entry.timeout_behavior == "error_as_result":
8474+
loop = asyncio.get_running_loop()
8475+
cutoff = loop.time() + duration
8476+
expired = False
8477+
timeout_error = ToolTimeoutError(entry.name, duration)
8478+
8479+
def admit_body() -> bool:
8480+
return not expired and self._admit_tool(state, request)
8481+
8482+
def expire_body(cancel_body: bool = True) -> None:
8483+
nonlocal expired
8484+
if self._closing or state.stopping or state.failure.done():
8485+
return
8486+
expired = True
8487+
if cancel_body:
8488+
cancel_once(body)
8489+
8490+
timer = loop.call_at(cutoff, expire_body)
8491+
8492+
async def invoke_body() -> Any:
8493+
try:
8494+
if admit_body():
8495+
return await _call_callback(entry.callback, admit_body, *args, **kwargs)
8496+
return None
8497+
finally:
8498+
timer.cancel()
8499+
# Settle at body exit, before unrelated ready work can
8500+
# delay the parent. Busy callbacks may outlast the timer.
8501+
if loop.time() >= cutoff:
8502+
expire_body(cancel_body=False)
8503+
8504+
try:
8505+
body = asyncio.create_task(invoke_body())
8506+
try:
8507+
# Do not let parent cancellation cancel an already
8508+
# unwinding body a second time and cut cleanup short.
8509+
await asyncio.wait((body,))
8510+
except BaseException as error:
8511+
cancel_once(body)
8512+
8513+
async def join_body() -> None:
8514+
await _join(body)
8515+
8516+
await _close_after_error(error, join_body)
8517+
raise
8518+
finally:
8519+
timer.cancel()
8520+
body_error = None if body.cancelled() else body.exception()
8521+
if not self._admit_tool(state, request):
8522+
return
8523+
if expired:
8524+
if body_error is not None:
8525+
timeout_error.__cause__ = body_error
8526+
# No late value is validated or serialized. Format only
8527+
# under the still-live parent's native admission.
8528+
text = str(timeout_error)
8529+
if entry.timeout_error_function is not None:
8530+
text = await _call_callback(
8531+
entry.timeout_error_function,
8532+
lambda: self._admit_tool(state, request),
8533+
context,
8534+
timeout_error,
8535+
)
8536+
if not self._admit_tool(state, request):
8537+
return
8538+
if not isinstance(text, str):
8539+
raise TypeError("Function timeout_error_function must return str")
8540+
timeout_output = ToolOutput.error(text)
8541+
timeout_output._validate()
8542+
value = None
8543+
else:
8544+
value = body.result()
84678545
else:
84688546
loop = asyncio.get_running_loop()
84698547
cutoff = loop.time() + duration
84708548
callback_task = asyncio.current_task()
84718549
assert callback_task is not None
8472-
timeout_error = TimeoutError(f"Tool {entry.name!r} exceeded its callback timeout")
8550+
timeout_error = ToolTimeoutError(entry.name, duration)
84738551

84748552
def expire_callback(cancel_body: bool = True) -> None:
84758553
if self._closing or state.stopping or state.failure.done():
@@ -8494,26 +8572,27 @@ def expire_callback(cancel_body: bool = True) -> None:
84948572
expire_callback(cancel_body=False)
84958573
if not self._admit_tool(state, request):
84968574
return
8497-
output: ToolOutput | None = None
8498-
try:
8499-
value = entry.output_adapter.validate_python(value)
8500-
if isinstance(value, ToolOutput):
8501-
output = value
8502-
else:
8503-
wire = entry.output_adapter.dump_json(value, warnings="error").decode()
8504-
# Declared strings retain raw text; other results keep JSON wire semantics.
8505-
text = json.loads(wire) if isinstance(value, str) else wire
8506-
output = ToolOutput.text(text if isinstance(text, str) else wire)
8507-
del wire, text
8508-
output._validate()
8509-
except Exception:
8510-
output = None
8511-
if output is None:
8512-
# End ownership of the original admission request and every
8513-
# invocation data reference without altering caller-owned objects.
8514-
del request, message, raw_arguments, parsed, kwargs, context, args, value
8515-
raise ValueError("Tool result failed validation")
8516-
if entry.after is not None:
8575+
output: ToolOutput | None = timeout_output
8576+
if timeout_output is None:
8577+
try:
8578+
value = entry.output_adapter.validate_python(value)
8579+
if isinstance(value, ToolOutput):
8580+
output = value
8581+
else:
8582+
wire = entry.output_adapter.dump_json(value, warnings="error").decode()
8583+
# Declared strings retain raw text; other results keep JSON wire semantics.
8584+
text = json.loads(wire) if isinstance(value, str) else wire
8585+
output = ToolOutput.text(text if isinstance(text, str) else wire)
8586+
del wire, text
8587+
output._validate()
8588+
except Exception:
8589+
output = None
8590+
if output is None:
8591+
# End ownership of the original admission request and every
8592+
# invocation data reference without altering caller-owned objects.
8593+
del request, message, raw_arguments, parsed, kwargs, context, args, value
8594+
raise ValueError("Tool result failed validation")
8595+
if entry.after is not None and timeout_output is None:
85178596
output = await _call_callback(
85188597
entry.after, lambda: self._admit_tool(state, request), context, output
85198598
)
@@ -8529,6 +8608,7 @@ def expire_callback(cancel_body: bool = True) -> None:
85298608
# The hook may have mutated the original callback result.
85308609
del request, message, raw_arguments, parsed, kwargs, context, args, value
85318610
raise ValueError("Tool result failed validation")
8611+
assert output is not None
85328612
reply = json.dumps({"request": message, "response": output.to_native()})
85338613
if not self._admit_tool(state, request):
85348614
return

‎packages/codex/src/_agents_codex/tools.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
from .manual import _CapturedManual as _CapturedManual
2222

2323
if TYPE_CHECKING:
24-
from ._function_tools import ToolContext
24+
from ._function_tools import ToolContext, ToolTimeoutBehavior, ToolTimeoutError
2525
from .native_interception import Allow, Deny, ReplaceArguments
2626

2727
_TOOL_RESPONSE = TypeAdapter(FunctionCallResponse)
@@ -345,6 +345,10 @@ class _CapturedFunction:
345345
callback: Callable[..., Any]
346346
context_parameter: inspect.Parameter | None
347347
callback_timeout: float | None
348+
timeout_behavior: ToolTimeoutBehavior
349+
timeout_error_function: (
350+
Callable[[ToolContext[Any], ToolTimeoutError], str | Awaitable[str]] | None
351+
)
348352
before: (
349353
Callable[
350354
[ToolContext[Any]],

0 commit comments

Comments
 (0)