Report Tool Errors
Send an exception a tool raises back to the model as a failed tool result, so the run continues and the model can try another way. Without it, a tool like divide(a, b) called with b=0 raises ZeroDivisionError out of agent.run(). Use it when an agent runs tools you don’t control, and an unhandled edge case in one of them shouldn’t end the run.
While Pydantic AI Harness is on 0.x releases, the API may change between minor releases; when it does, deprecation warnings and release-note migration guidance tell you (or your agent) exactly how to upgrade. See the version policy.
pip install pydantic-ai-harness
uv add pydantic-ai-harness
from pydantic_ai import Agent
from pydantic_ai_harness import ReportToolErrors
agent = Agent('anthropic:claude-opus-5-5', capabilities=[ReportToolErrors()])
@agent.tool_plain
def divide(a: int, b: int) -> float:
return a / b
The failed call gets a tool result with outcome='failed' that names the tool and the exception type:
`divide` raised ZeroDivisionError
The exception’s message isn’t included, since it can carry file paths, hostnames or connection strings. When your tools’ messages are meant for the model, pass format_error, which builds the text from the run context and a ToolErrorInfo carrying the tool name, its arguments, the tool call ID and the exception:
from pydantic_ai import RunContext
from pydantic_ai_harness import ReportToolErrors
from pydantic_ai_harness.report_tool_errors import ToolErrorInfo
def with_message(ctx: RunContext[None], info: ToolErrorInfo) -> str:
return f'`{info.name}` raised {type(info.error).__name__}: {info.error}'
report = ReportToolErrors(format_error=with_message)
To report only some exceptions, pass exceptions. Any other exception ends the run as it would without the capability, so a programming error such as a KeyError still fails fast:
from pydantic_ai_harness import ReportToolErrors
report = ReportToolErrors(exceptions=(TimeoutError, ConnectionError))
ReportToolErrors wraps the agent’s toolset and turns an exception from a tool into a ToolFailed, as if the tool had raised it, so the rest of the agent treats the call like any other failed call:
- The tool stays available and nothing counts the failures: the model decides whether to call it again.
UsageLimits.request_limitstops a model that keeps calling a failing tool;tool_calls_limitcounts only successful calls. To cap calls to one tool, use Tool Budgets. ModelRetry,ToolFailed,ApprovalRequired,CallDeferredandSkipToolExecutionpass through unchanged, and so doesRunCancelledfrom a sub-agent, which core already reports.UsageLimitExceededandUserErrorstill end the run: a spent budget or a setup bug is not something the model can work around.- A tool that raises
ModelRetrymore often than itsretriesallow still ends the run withUnexpectedModelBehavior, so a tool’s retry limit keeps working. Coder reports those to the model instead. - Every function tool is covered, including MCP tools and tools other capabilities add. Output tools and argument validation errors aren’t.
To get the fail-fast behavior back, leave ReportToolErrors out of capabilities.
Under Temporal, a tool runs in an activity, and an exception it raises goes to the activity’s retry policy. When that gives up, the workflow gets Temporal’s ActivityError, which names the tool’s exception only by its type, so ReportToolErrors leaves it alone and the run fails as it would without the capability.
ReportToolErrors emits no spans of its own: core’s tool span already marks the call as an error and, when content is included, records the text the model sees as its result.
- A Tool Guardrails
result_guardscreens the reported text like any failed tool result, so it can redact what a customformat_errorincludes. on_tool_execute_errorhooks aren’t called for an exceptionReportToolErrorsreports, whatever order the capabilities are listed in, so a capability that logs or recovers in that hook no longer sees it. Narrowexceptionsto leave those types to the hook.- Under Code Mode, a tool that a snippet calls raises the reported
ToolFailedinto the snippet instead of its own exception, soexcept ZeroDivisionError:in the snippet no longer catches it. Narrowexceptionsto leave such types to the snippet. - Several
ReportToolErrorson one agent: the last one listed wraps the tools most closely, so it formats the error.
See the source.
Bases: AbstractCapability[AgentDepsT]
Report an exception a tool raises to the model as a failed tool result, so the run continues.
The exception becomes a ToolFailed, as if the tool had raised one itself. The model sees the tool name and the
exception type, and decides whether to call the tool again, try another way, or give up. There
is no limit of its own: UsageLimits.request_limit stops a model that keeps calling a failing tool. ModelRetry,
ToolFailed, ApprovalRequired, CallDeferred, SkipToolExecution, RunCancelled, UsageLimitExceeded and
UserError keep their usual meaning.
from pydantic_ai import Agent
from pydantic_ai_harness import ReportToolErrors
agent = Agent('anthropic:claude-opus-5-5', capabilities=[ReportToolErrors()])
Build the text the model sees from the run context and the failed call.
The default names the tool and the exception type. It leaves out the exception’s message, which can carry file paths, hostnames or connection strings; pass a formatter to include it.
Type: Callable[[RunContext[AgentDepsT], ToolErrorInfo], str] Default: _describe
The exception types to report. Any other exception propagates and ends the run, as without the capability.
Type: tuple[type[Exception], …] Default: (Exception,)
The failed tool call and the exception it raised, as ReportToolErrors.format_error sees them.
Name of the tool the model called.
Type: str
Validated arguments the tool was called with, as a copy.
Identifier of this call, for correlating with the run’s messages.
Type: str
The exception the tool raised.
Type: Exception