Intermediate7 min
Tool Error Handling
By default, tool errors crash the agent. Use @wrap_tool_call to intercept failures, return actionable error messages, and implement retry logic — all without touching the tool itself.
Quick Reference
- →@wrap_tool_call wraps every tool execution — intercept errors before the model sees them
- →Return ToolMessage(content='...', tool_call_id=request.tool_call['id']) on failure
- →The model receives the error message and can decide to retry or recover
- →Retry logic belongs in wrap_tool_call, not inside the tool itself
- →Always include the tool_call_id — the model needs it to match requests to responses
The Default Behavior
When a tool raises an exception without any error handling, the agent crashes and the error propagates to the caller. The model never gets a chance to recover, retry, or route around the failure. For production agents — where tools call external APIs, databases, or services that fail — this is unacceptable. @wrap_tool_call gives you a hook to intercept every tool execution, catch failures, and return a message the model can act on.
Default: unhandled tool error crashes the agent