Skip to main content
Structured exceptions tell you what failed, whether to retry, and which agent or run was involved — without parsing raw tracebacks.

​
Quick Start

1

Catch any agent error

from praisonaiagents import Agent, PraisonAIError

agent = Agent(name="assistant", instructions="Be helpful")

try:
    result = agent.start("Say hello in one sentence.")
    print(result)
except PraisonAIError as e:
    print(f"{e.error_category}: {e.message} (agent={e.agent_id}, run={e.run_id})")
2

Handle tool errors specifically

from praisonaiagents import Agent, tool, ToolExecutionError

@tool
def divide(a: float, b: float) -> float:
    """Divide two numbers."""
    return a / b

agent = Agent(instructions="Use divide.", tools=[divide])

try:
    agent.start("Divide 10 by 0.")
except ToolExecutionError as e:
    print(f"Tool {e.tool_name} failed: {e.message}")
    print(f"Retryable: {e.is_retryable}")

​
How It Works

Every structured error carries message, agent_id, run_id, error_category, and is_retryable. Subclasses add domain fields such as tool_name or model_name.

​
The Error Hierarchy

ClassParentWhen raisedKey fieldsDefault retryable
PraisonAIErrorExceptionBase — catch-allerror_category, contextFalse
ToolExecutionErrorPraisonAIErrorTool fails or loop-guard HALTtool_nameTrue
LLMErrorPraisonAIErrorChat completion failsmodel_nameFalse
ValidationErrorPraisonAIErrorInvalid config or inputfield_nameFalse
NetworkErrorPraisonAIErrorExternal service unreachableservice_name, status_codeTrue
error_category uses typed kinds such as rate_limit, auth, context_overflow, and billing — useful for logging and selective retry policies.

​
Common Patterns

Retry on transient network failures, fail on config bugs: 
from praisonaiagents import Agent, NetworkError, ValidationError

agent = Agent(name="assistant")

for attempt in range(3):
    try:
        print(agent.start("Summarise today's news."))
        break
    except NetworkError:
        if attempt == 2:
            raise
    except ValidationError:
        raise  # fix config — retry won't help
Distinguish fatal exceptions from non-fatal results: raised errors stop the run; some callbacks and memory paths record failures on the output instead. See Non-Fatal Errors.

​
Choose Your Recovery

​
Best Practices

Use ToolExecutionError when you only care about tool failures; reserve PraisonAIError for top-level logging.
Include e.error_category, e.agent_id, and e.run_id in observability hooks — they correlate across multi-agent runs.
Validation failures usually mean a programming or config bug. Fix the root cause instead of retrying blindly.
Loop-guard HALT raises ToolExecutionError. Combine with Loop Guard when tools may repeat indefinitely.

Loop Guard

Stop runaway tool loops with HALT/WARN/BLOCK

Non-Fatal Errors

Callback failures captured without crashing

Async Tool Safety

Circuit breakers for async tool calls

Custom Tools

Build tools that raise clear errors