Allow tool call to be fatal instead of always passing info as tool execution result

[jackgerrits]

[ekzhu]

We should be able to allow errors in executin tools in AssistantAgent to raise through the stack.

Options:

• By default, raise all errors from tool
• By default, catch and stringify all errors from tool

Error handling options:

• Add tool handling function as part of the BaseTool constructor, which will be invoked when there is an exception raised from the tool
• Add a list of exception classes that we shuold not ignore.

[ekzhu]

Relevant discussion: #5488

[majiayu000]

Hi @ekzhu, I'd like to work on this issue.

Based on your comments and the discussion in PR #5488, here's my proposed approach:

Default behavior change:

• Change AssistantAgent to raise errors by default from tool execution, rather than catching and stringifying them. This aligns with the principle of failing loudly — silent error stringification can mask serious issues and cause the LLM to hallucinate recovery paths.

Error handling options (added to AssistantAgent constructor):

1. tool_call_error_handler: Callable[[Exception, FunctionCall], str] | None — a custom handler invoked when a tool raises an exception. If provided, the exception is caught, passed to the handler, and the handler's return string is sent back as the tool result. If None, the exception propagates up the stack.

2. tool_call_safe_exceptions: list[type[Exception]] | None — a list of exception classes that should be caught and stringified rather than raised. For example, [ValueError, KeyError] would catch those and pass the error message to the LLM, while all other exceptions propagate. This gives users fine-grained control.

These two options are mutually exclusive — if tool_call_error_handler is set, it takes precedence.

Scope:

• Modify AssistantAgent._execute_tool_call (or equivalent) to implement the above logic
• Add corresponding parameters to AssistantAgent.__init__
• Add tests covering: default raise behavior, custom handler, safe exception list
• Update tool usage documentation to describe error handling

Does this direction look right? Happy to adjust based on your feedback.