docs: Add a comprehensive example for handling function tool errors. #1354
Conversation
docs/tools.md
Outdated
| import asyncio | ||
| from agents import Agent, Runner, function_tool, FunctionTool, Model | ||
|
|
||
| def my_custom_error_function(error, *args) -> str: |
There was a problem hiding this comment.
I don't think this method signature is correct.
docs/tools.md
Outdated
| raise ValueError("Data list cannot be empty.") | ||
| return "Operation successful." | ||
|
|
||
| async def main(): |
There was a problem hiding this comment.
To keep the document page as simple as possible, let's have only the tool and its error function in this code snippet.
There was a problem hiding this comment.
please delete this main function part
docs/tools.md
Outdated
| return "An internal server error occurred. Please try again later." | ||
|
|
||
| @function_tool(failure_error_function=my_custom_error_function) | ||
| def risky_operation(data) -> str: |
There was a problem hiding this comment.
I feel "risky" is not the case here. It should be more of something that can fail. How about using an example to perform a backend API call (no need to use real backend; just pseudo code)?
docs/tools.md
Outdated
| from agents import Agent, Runner, function_tool | ||
| from typing import Any, List | ||
|
|
||
| def my_custom_error_function(error: Exception, *args: Any, **kwargs: Any) -> str: |
There was a problem hiding this comment.
@seratch hello
I hope you are well
It's my request you should merge it because it's soo clear and user-friendly and I run this it's work correct so this kind of code need in document
There was a problem hiding this comment.
@MuhammadHamidRaza As you know, I review everything in this repo. So, please avoid pinging me like this. I’d appreciate your understanding.
docs/tools.md
Outdated
| raise ValueError("Data list cannot be empty.") | ||
| return "Operation successful." | ||
|
|
||
| async def main(): |
There was a problem hiding this comment.
please delete this main function part
|
fix it |
|
I actually created an issue proposing a documentation update and included this exact example myself, so it's great to see that we're aligned on the best approach! I also tested it by passing user_id 'user_456', and it worked flawlessly, correctly demonstrating the custom error handling. |
|
Merge it @seratch |
| @@ -320,3 +320,26 @@ When you create a function tool via `@function_tool`, you can pass a `failure_er | |||
| - If you explicitly pass `None`, then any tool call errors will be re-raised for you to handle. This could be a `ModelBehaviorError` if the model produced invalid JSON, or a `UserError` if your code crashed, etc. | |||
|
|
|||
| If you are manually creating a `FunctionTool` object, then you must handle errors inside the `on_invoke_tool` function. | |||
|
|
|||
| ## Example: Custom Error Handling in Function Tools | |||
There was a problem hiding this comment.
Sorry, can you delete this headline, plus move the whole change above L322? I noticed placing here does not make sense.
If you are manually creating a
FunctionToolobject, then you must handle errors inside theon_invoke_toolfunction.
This Pull Request adds a comprehensive and runnable code example to the "Handling errors in function tools" documentation section. The goal is to make a complex topic more accessible to new users.
The current documentation accurately describes the theory behind using failure_error_function, but it lacks a practical, complete example that shows the concept in action. This can make it challenging for developers to correctly implement custom error handling.
This PR addresses that gap by providing a clean, working example that demonstrates the following:
This contribution makes the documentation more robust and user-friendly, which will significantly improve the developer experience for the community.