Tool Timeouts & Cancellation

Give every tool call a hard deadline, cancel with a token, and read discriminated error kinds

Give any single tool call a hard deadline, cancel a batch mid-flight with a token, and read a discriminated error_kind instead of an opaque error string — so your agent can decide to retry, switch tools, or abort.

from praisonaiagents.tools.call_executor import (
    ToolCall,
    SequentialToolCallExecutor,
)

def execute_tool_fn(name, arguments, tool_call_id):
    # Your real dispatch logic; this stub just echoes.
    return f"ran {name}"

executor = SequentialToolCallExecutor()
results = executor.execute_batch(
    [ToolCall("search", {"q": "recent papers on X"}, "call-1")],
    execute_tool_fn,
    timeout_ms=5000,   # abandon any single tool after 5s
)

for r in results:
    print(r.result, r.error_kind)

Quick Start

1. Add a hard deadline

   Pass timeout_ms (milliseconds) to execute_batch. A tool that runs longer is abandoned on a dedicated worker and returns a typed timeout result — the turn never hangs.

   from praisonaiagents.tools.call_executor import ToolCall, SequentialToolCallExecutor
   
   def execute_tool_fn(name, arguments, tool_call_id):
       return slow_lookup(**arguments)  # your tool
   
   executor = SequentialToolCallExecutor()
   results = executor.execute_batch(
       [ToolCall("slow_lookup", {"id": 42}, "call-1")],
       execute_tool_fn,
       timeout_ms=3000,
   )

2. Add a cancel token

   Pass any threading.Event-like token. Signal it from another thread to short-circuit pending calls with a typed cancelled result.

   import threading
   from praisonaiagents.tools.call_executor import ToolCall, SequentialToolCallExecutor
   
   cancel = threading.Event()
   
   executor = SequentialToolCallExecutor()
   # From elsewhere: cancel.set()
   results = executor.execute_batch(
       [ToolCall("search", {"q": "X"}, "call-1")],
       execute_tool_fn,
       cancel_token=cancel,
   )

   The token is duck-typed: threading.Event (.is_set()) and InterruptController-like tokens (.is_cancelled / .cancelled) both work — no concrete import required.

3. Handle structured errors

   Pattern-match on error_kind and read structured_error for a discriminated payload:

   for r in results:
       if r.error is None:
           print("ok:", r.result)
       elif r.error_kind == "timeout":
           print("retry later:", r.structured_error)
       elif r.error_kind == "cancelled":
           print("user cancelled")
       else:  # "error"
           print("tool failed:", r.structured_error)

How It Works

Because Python threads can’t be force-killed, a timed-out tool’s worker is abandoned (not joined) and a typed result is returned immediately — the turn keeps moving. It is now a daemon thread (PR #5589), so a hung tool cannot block interpreter exit.

Both executors forward timeout_ms and cancel_token:

from praisonaiagents.tools.call_executor import (
    ParallelToolCallExecutor,
    SequentialToolCallExecutor,
)

# Same signature on both:
SequentialToolCallExecutor().execute_batch(calls, fn, timeout_ms=5000, cancel_token=tok)
ParallelToolCallExecutor(max_workers=5).execute_batch(calls, fn, timeout_ms=5000, cancel_token=tok)

Retry-on-timeout is opt-in for mutating tools

A wall-clock timeout is no longer auto-retried unless the tool is idempotent — because the timed-out body keeps running in an orphaned worker thread (Future.cancel() is a no-op once the task has started), so re-driving a mutating tool would duplicate its side effects (a second invoice email, a double charge).

Opt in for a specific tool by setting idempotent = True on the callable:

from praisonaiagents import Agent

def read_current_price(symbol: str) -> float:
    ...
read_current_price.idempotent = True   # safe to retry on timeout

agent = Agent(
    name="Trader",
    instructions="Look up prices.",
    tools=[read_current_price],
)

The same attribute works on a registered FunctionTool — set it on the object the agent holds:

from praisonaiagents.tools import tool

@tool
def read_current_price(symbol: str) -> float:
    ...
read_current_price.idempotent = True   # opt in to retry-on-timeout

Idempotency is decided in this order: an explicit idempotent attribute on the tool wins; then, with ToolConfig(allow_global_tools=True), the global registry’s flag; then the shared IDEMPOTENT_TOOLS / MUTATING_TOOLS name registry in praisonaiagents.escalation.loop_guard. Unknown tools default to non-idempotent — the safe choice, so a timeout surfaces once instead of duplicating side effects.

AgentsGenerator is a closable resource

The wrapper-level tool-timeout guard runs inside an AgentsGenerator, and closing that generator closes its worker pool permanently.

That generator owns a ThreadPoolExecutor for sync tool workers. A tool invoked after close() no longer silently resurrects the pool — it raises an actionable RuntimeError naming the fix.

Prefer the context-manager form so cleanup is not conditional:

from praisonai.agents_generator import AgentsGenerator

with AgentsGenerator(agent_file="agents.yaml", framework="praisonai", config_list=cfg) as gen:
    gen.generate_crew_and_kickoff()
# Pool is torn down here. A tool held past this line raises RuntimeError.

If a background hook, framework lifecycle callback, or shared registry keeps a wrapped tool alive past the with … as gen: block, invoking it now raises:

RuntimeError: AgentsGenerator is closed; refusing to construct a new tool-timeout executor. This tool was invoked after close(); hold a live generator (e.g. keep the `with ... as gen:` block open) for the lifetime of any tool it wraps.

Per-call tool-timeout wraps travel on the per-run prep dict, not on the generator instance, so two concurrent calls on one AgentsGenerator cannot swap each other’s budget. See Registry DI → Concurrent runs on one AgentsGenerator.

Concurrent recycle races are absorbed

A concurrent recycle can shut the captured pool down between capture and submit, or cancel a queued future before it runs. The wrapper now retries once against a freshly-minted pool. A second failure surfaces as ToolTimeoutError (with background_work_may_continue=False when the tool never executed), preserving the module contract so RuntimeError / CancelledError never leak to caller code.

Both attempts share a single time.monotonic() deadline, so a retry can never extend the declared budget — if the first attempt’s pool recycle burned 3 s of a 5 s budget, the retry waits at most the remaining 2 s before surfacing ToolTimeoutError.

error_kind Reference

ToolResult.error_kind is a discriminated tag; ToolResult.structured_error is None on success and a discriminated dict on failure.

from praisonaiagents.tools import ToolTimeoutError, ToolCancelledError

Timeout, Cancel, or Both?

from praisonaiagents import Agent, ToolConfig

def slow_lookup(symbol: str) -> float:
    ...  # takes a while

agent = Agent(
    name="Trader",
    instructions="Look up prices.",
    tools=[slow_lookup],
    tool_config=ToolConfig(timeout=5),   # core enforces — single pool
)

# A timeout now returns core's structured dict rather than raising
# the wrapper ToolTimeoutError:
#   {"error": "Tool timed out after 5s", "timeout": True,
#    "_praison_retryable": False}
agent.start("Price of X")

YAML tool_timeout precedence (multi-agent configs)

When you declare tool_timeout on agents or roles in YAML, PraisonAI now honours each agent’s declared budget independently.

Precedence (per agent):

1. CLI tool_timeout wins for every agent — an explicit --tool-timeout value overrides YAML for all agents.
2. Per-agent YAML value wins over the CLI absence. Each agent’s declared value is applied to its own tool calls.
3. Uniform declared values (every agent declares tool_timeout and every value is identical) take a shared-wrap fast path. If any agent omits tool_timeout, the shared wrap is skipped entirely — even if the remaining declarations agree.
4. Heterogeneous per-agent values (different agents declare different values) are honoured per-agent — the tightest value no longer collapses onto every agent.
5. Agents without a declared tool_timeout fall through to the CLI value if set, otherwise their tools run with no imposed timeout — they do not inherit another agent’s declared value via the shared dict.
6. Booleans are ignored — only int/float values count.

roles:
  strict_router:
    tool_timeout: 5          # declared
    tools: [internet_search]
  scraper:
    # omitted — no imposed timeout
    tools: [scrape_page]

roles:
  strict_router:
    tool_timeout: 5
    tools: [internet_search]
  scraper:
    tool_timeout: 5          # declared, same value
    tools: [scrape_page]

praisonai run agents.yaml --tool-timeout 5

A heterogeneous config where both budgets are honoured — fast_router aborts cheap tools at 5s, slow_analyst keeps its 120s window:

roles:
  fast_router:
    role: Router
    tool_timeout: 5      # quick-abort on cheap tools
    tools: [internet_search]
  slow_analyst:
    role: Analyst
    tool_timeout: 120    # long window for large-doc scraping
    tools: [scrape_page]

Related