Error Handling

Catch and recover from agent, tool, and LLM errors

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

from praisonaiagents import Agent, PraisonAIError

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

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

The user runs the agent; failures raise typed PraisonAIError with category, message, and run context for recovery.

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.

Class	When raised	Key fields	Default retryable
PraisonAIError	Base — catch-all	error_category, context	False
ToolExecutionError	Tool fails or loop-guard HALT	tool_name	True
LLMError	Chat completion fails	model_name	False
ValidationError	Invalid config or input	field_name	False
NetworkError	External service unreachable	service_name, status_code	True

error_category uses typed kinds such as rate_limit, auth, context_overflow, and billing.

---

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

Raised errors stop the run; some callbacks record failures on the output instead. See Non-Fatal Errors.

---

Reaching the Step Limit

When the tool-calling loop reaches ExecutionConfig.max_steps (or max_iter when max_steps is unset), the agent does not hard-cut. On the final permitted step it injects a graceful wrap-up instruction, so the model returns a real summary of what it accomplished and what remains — not a placeholder.

Detect truncation with agent.last_stop_reason instead of string-matching:

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="coder",
    instructions="You are a coding assistant.",
    execution=ExecutionConfig(max_steps=50),
)
result = agent.start("Refactor the auth module across all files")

if agent.last_stop_reason == "max_steps":
    result = agent.start("Continue from where you left off.")

Step Budget

Cap tool-use steps and detect graceful truncation with last_stop_reason

---

Best Practices

Catch the most specific class you can handle

Use ToolExecutionError when you only care about tool failures; reserve PraisonAIError for top-level logging.

Log structured context

Include e.error_category, e.agent_id, and e.run_id in observability hooks — they correlate across multi-agent runs.

Don't swallow ValidationError

Validation failures usually mean a programming or config bug. Fix the root cause instead of retrying blindly.

Pair with loop guard for retry loops

Loop-guard HALT raises ToolExecutionError. Combine with Loop Guard when tools may repeat indefinitely.

---

Related

Loop Guard

Stop runaway tool loops with HALT/WARN/BLOCK

Non-Fatal Errors

Callback failures captured without crashing