feat(app): let tools opt out of background offloading or override the offload timeout - #3899

Part of #3845

AgentScope Version

main @ d8ebf89

Description

Problem

ToolOffloadMiddleware applies one deployment-wide timeout (tool_offload_timeout_secs, #3330) to every tool, and only is_state_injected / is_external_tool tools escape offloading entirely. Tool authors who know better have no say:

• a tool whose delayed result would confuse the caller (it must complete within the reply, or not at all) cannot opt out of offloading;
• a tool that knows it needs more (or less) wall-clock time than the deployment default cannot express that, so deployments must either raise the global timeout for everyone or let that tool get offloaded.

This is the "Make execution policy and timeout configurable per tool" item of #3845.

Changes

src/agentscope/tool/_base.py — two new ToolBase attributes, following the existing per-tool policy pattern (is_state_injected, is_external_tool):

• is_offloadable: bool = True — when False, the middleware always runs the tool synchronously, exactly like is_state_injected tools.
• offload_timeout_secs: float | None = None — when set, replaces the middleware-wide timeout for this tool's calls; None keeps the deployment default.

src/agentscope/app/middleware/_tool_offload_middleware.py:

• the bypass guard grows a third arm (not tool.is_offloadable);
• the rolling deadline is computed from the per-tool override when present (falling back to the configured timeout when the tool object is unavailable);
• class and on_acting docstrings document the two knobs.

Both attributes default to the current behavior, so existing tools and deployments are unaffected; tool_offload_timeout_secs=None (middleware disabled) continues to work as before. This complements #3853, which makes the offload placeholder itself machine-readable.

How to test

pytest tests/tool_offload_middleware_test.py — 10 passed (7 existing + 3 new).

• test_tool_opting_out_of_offload_runs_synchronously: is_offloadable=False tool that outlives the timeout returns its real result and registers nothing in the background; fails on unpatched source (the tool gets a synthetic placeholder).
• test_per_tool_timeout_override_extends_the_wait: offload_timeout_secs=1.0 survives a 0.05 s middleware-wide timeout; fails on unpatched source.
• test_per_tool_timeout_override_shortens_the_wait: offload_timeout_secs=0.01 offloads a 0.5 s tool even under a 5 s middleware-wide timeout; fails on unpatched source.
• black --line-length=79 and flake8 clean on all three changed files.

Checklist

• An issue has been created for this PR
• I have read the CONTRIBUTING.md
• Related documentation has been updated (e.g. links, examples, etc.) in documentation repository — no documentation change needed
• Code is ready for review

/cc @lins — this and #3853 are the two slices of #3845 that can land without design decisions; the remaining items there (persistent result store, task management API) are untouched.