tool_error

Sync handler: return content to surface the error as a ToolMessage; return None (or nothing) to let the exception propagate.

Async handler: return content to surface the error as a ToolMessage; return None (or nothing) to let the exception propagate.

Base middleware class for an agent.

Subclass this and implement any of the defined methods to customize agent behavior between steps in the main agent loop.

State schema for the agent.

Return selected tool-execution exceptions to the model as error ToolMessages.

on_error is called for each exception raised by tool execution. Return content (a str or a list of content blocks) to convert the exception into a ToolMessage(status="error"); return None — or simply don't return — to let the exception propagate (halting the run). Handling is therefore opt-in — exceptions you do not return content for propagate unchanged, so arbitrary internal exceptions are never serialized to the model or end user unless you choose to surface them.

Langgraph control-flow signals (interrupts, parent commands) always propagate and never reach on_error.

Prefer returning content that names the exception type over the raw exception message, which may carry sensitive or internal detail.

Provide at least one of on_error or aon_error. aon_error handles errors on the async execution path (falling back to on_error when omitted); the sync path only ever calls on_error. For async-only usage, pass aon_error alone — running such a middleware on the sync path raises, since the async handler cannot be awaited there.

This middleware does not retry. For retries, compose with ToolRetryMiddleware placed inner and configured with on_failure="error" so exceptions reach this middleware.

This middleware only sees exceptions raised by tool execution. Argument-binding and validation errors are handled upstream by ToolNode (converted to an error ToolMessage before the tool runs), so they do not reach on_error.