Tool Timeouts & Cancellation

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)

Backward compatible. All new parameters are optional. With no timeout_ms and no cancel_token, execution delegates straight to the tool body — behaviour is unchanged.

Quick Start

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,
)

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.

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. 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)

`error_kind` Reference

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

`error_kind`	Exception	`result` payload	Example `structured_error`
`timeout`	`ToolTimeoutError`	`{"error": "timeout", "timeout_ms": ..., "tool": ...}`	`{"error": true, "kind": "timeout", "type": "ToolTimeoutError", "message": "...", "tool": "search"}`
`cancelled`	`ToolCancelledError`	`{"error": "cancelled", "tool": ...}`	`{"error": true, "kind": "cancelled", "type": "ToolCancelledError", "message": "...", "tool": "search"}`
`error`	the raised exception	`"Error executing tool: ..."`	`{"error": true, "kind": "error", "type": "ValueError", "message": "...", "tool": "search"}`

from praisonaiagents.tools import ToolTimeoutError, ToolCancelledError

Timeout, Cancel, or Both?

Config default via ToolExecutionConfig

ToolExecutionConfig.timeout_ms is now consumed by the executor, so a configured default flows through to execute_batch without per-call wiring.

Parallel batches

ParallelToolCallExecutor enforces the same per-tool timeout inside each worker, so one hung tool resolves to a typed timeout result instead of blocking collection of the others.

BaseTool compatibility

When PraisonAI wraps a framework tool with tool_timeout, the resulting proxy is an instance of a dynamic subclass of the original tool’s class — so isinstance(proxy, BaseTool) (and any framework-specific base check used by CrewAI / LangChain / praisonaiagents.tool_execution for dispatch) still returns True. A BaseTool subclass with tool_timeout set on its owning agent executes normally through the same isinstance-routed .run path as an unwrapped tool; the wrapper adds a deadline but does not change dispatch. See PraisonAI Package Integration → Cross-generator tool isolation for the multi-generator behaviour.

YAML `tool_timeout` precedence (multi-agent configs)

When you declare tool_timeout on agents or roles in YAML, PraisonAI resolves one effective per-tool timeout for the shared tool dict.

agents:
  - name: fast_agent
    instructions: "Answer quickly"
    tool_timeout: 5
  - name: slow_agent
    instructions: "Deep analysis"
    tool_timeout: 60

Precedence:

CLI tool_timeout wins. An explicit value passed on the command line overrides everything.
Otherwise the tightest (min) declared value applies across all roles: and agents: — here 5.0s, not 60.
Any agent whose declared value isn’t the tightest gets a warning naming it.
Booleans are ignored — only int/float values count. If nothing declares a timeout, no timeout is applied.

Copy this into your CI log filters:

Agent 'slow_agent' declared tool_timeout=60 but a shared tool dict forces the tightest value 5.0s for the whole run.

What changed (PR #3176): the effective timeout used to be the largest (max) declared value — a fast agent could inherit a slow agent’s budget and never time out. It is now the tightest (min). If a CI config passed only because a slow agent’s max() masked a fast agent’s timeout, the fast agent may now fail sooner. Single-agent configs and configs where only one agent declares tool_timeout are unaffected — the change only matters when multiple agents declare different values.

This precedence applies to the YAML per-agent tool_timeout field resolved for the shared tool dict. It is independent of the per-call timeout_ms argument to execute_batch documented above.

YAML Validation

Catch duplicate names and unknown task→agent references

Parallel Tool Calls

Run batched tool calls concurrently

Tool Progress

Stream incremental progress from slow tools

Deferred Tools

Hand back long-running work without blocking

Tools Overview

Build and register agent tools

Managed Config

Advanced Features Module

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Tool Timeouts & Cancellation

Quick Start

How It Works

`error_kind` Reference

Timeout, Cancel, or Both?

YAML `tool_timeout` precedence (multi-agent configs)

YAML Validation

Parallel Tool Calls

Tool Progress

Deferred Tools

Tools Overview

​Quick Start

​How It Works

​error_kind Reference

​Timeout, Cancel, or Both?

​YAML tool_timeout precedence (multi-agent configs)

​Related

YAML Validation

Parallel Tool Calls

Tool Progress

Deferred Tools

Tools Overview

Quick Start

How It Works

`error_kind` Reference

Timeout, Cancel, or Both?

YAML `tool_timeout` precedence (multi-agent configs)

Related