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}")

3. Catch a failed LLM tool-calling loop

   from praisonaiagents import Agent
   from praisonaiagents.llm import LLMResponseError
   
   agent = Agent(name="assistant", instructions="Answer clearly.")
   
   try:
       result = agent.start("Summarise the latest project update.")
   except LLMResponseError as e:
       # A mid-loop tool-calling error now raises instead of returning ""
       print(f"LLM call failed: {e.message}")

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.

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

LLMResponseError is raised by LLM.get_response() when the tool-calling loop fails and cannot produce a response — previously this was swallowed and returned as an empty string. Catch it to distinguish tool-loop failures; a try/except Exception already covers it. See LLMResponseError.

LLM Response Errors

LLMResponseError is raised when the LLM tool-calling loop hits an exception it cannot recover from. It lives in praisonaiagents.llm alongside the other LLM exceptions:

from praisonaiagents.llm import LLMResponseError

LLMResponseError carries a message attribute describing the iteration that failed and chains the original exception via raise … from e, so e.__cause__ holds the underlying error.

Wrapper exceptions (praisonai.*)

PraisonAIError now catches every root exception in the praisonai wrapper too, so one except handler covers both tiers.

from praisonaiagents import PraisonAIError
from praisonai.recipe.registry import LocalRegistry

try:
    LocalRegistry().pull("missing-recipe")
except PraisonAIError as e:
    # Also catches RecipeError, CLIExecutionError, JobQueueFull, ToolTimeoutError, …
    print(f"{type(e).__name__}: {e}")

Stdlib parents stay in place through multiple inheritance, so existing except ValueError, except RuntimeError, and except TimeoutError handlers keep matching. Keep importing the base from praisonaiagents — the wrapper adds no new public module.

Subclasses such as RecipeNotFoundError, RunNotFoundError, and PolicyDeniedError inherit the change automatically.

Observing a terminal LLM failure

chat() / achat() return None on an unrecoverable LLM failure (a 500, a revoked key, a 429 after all retries). As of PR #5764, agent.last_stop_reason is set to "error" in that same path, so callers that cannot catch the raised exception (web handlers, bots, batch jobs) can still tell “the model answered empty” from “the model never answered”.

from praisonaiagents import Agent

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

reply = agent.chat("Draft a reply")
if reply is None and agent.last_stop_reason == "error":
    # The LLM call failed terminally. Retry on a healthy endpoint,
    # or surface the failure to the user.
    print("The model could not answer — please try again.")

The reason is reset to "completed" at the start of every turn, so an "error" from a previous turn cannot leak into the next one.

Tool Failure Behavior

On both chat() and achat(), a tool failure resolves down one of three branches:

1. Tool raises an exception → the framework wraps it as ToolExecutionError and propagates it.
2. Tool returns {"error": "..."} → the error dict is handed back to the LLM as a normal tool result, so the model can self-correct (new behavior since PR #4462, confirmed in #4470 which fixes issue #4446. The generic-exception branch in openai_client.py behaves the same way.).
3. Tool returns a retryable-transient / denial dict → ToolExecutionError with is_retryable=True, or a short-circuit denial.

If your tool raises, your agent’s turn ends — the same way whether you call chat() or achat(). Wrap both in try / except ToolExecutionError:

import asyncio
from praisonaiagents import Agent, tool, ToolExecutionError

@tool
def fetch(url: str) -> str:
    """Fetch a URL."""
    raise RuntimeError("429 too many requests")

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

try:
    agent.start("Fetch https://example.com")
except ToolExecutionError as e:
    print(f"Tool {e.tool_name} failed: {e.message}")

# Async — raises the same ToolExecutionError
try:
    asyncio.run(agent.achat("Fetch https://example.com"))
except ToolExecutionError as e:
    print(f"Tool {e.tool_name} failed: {e.message}")

A tool that returns an error dict (instead of raising) no longer aborts the run — the dict flows back to the model, which retries with corrected arguments:

from praisonaiagents import Agent, tool

@tool
def fetch(url: str) -> dict:
    """Fetch a URL — returns an error dict on bad input."""
    if not url:
        return {"error": "Empty URL", "stdout": "", "stderr": ""}
    ...

agent = Agent(instructions="Use fetch.", tools=[fetch])
# The model calling fetch("") no longer aborts the run.
# The error dict flows back to the model and it retries with a real URL.
agent.start("Fetch example.com and summarise.")

Sync and async paths are aligned (PR #6109). A tool that raises ends the turn with ToolExecutionError on both chat() and achat() — previously achat() handed the error to the model and returned its “the operation failed” reply as a success, so side-effecting tools (email, payments) could fail silently. A tool that returns {"error": "..."} is handed to the LLM as a normal tool result on both. See Async Tool Safety.

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

On a gateway, surface the reason to chat users — see Turn Completion Notes.

On the CLI: when a truncated run reaches praisonai run / praisonai-code run, the wrapper reports it distinctly from success — exit code 2 (not 0), status: "truncated" under --output json / --output stream-json with the wrap-up summary preserved in result, plus a one-line stderr warning in interactive mode. See praisonai run → Exit Codes.

Best Practices

Related