Enhance Tool Behavior Documentation for Developer Clarity With Examples #1286
Conversation
…l Behavior Definitions" documentation to provide clearer explanations and more robust examples for agent tool usage. Key improvements include: - Explicitly defining import paths for `StopAtTools` and `ToolsToFinalOutputFunction`. - Providing comprehensive and corrected code examples for all `tool_choice` and `tool_use_behavior` configurations, including `"stop_on_first_tool"`, `StopAtTools`, and the usage of `ToolsToFinalOutputFunction`. - Ensuring proper Markdown formatting for code blocks and notes to enhance readability and accuracy. This update aims to significantly reduce ambiguity and improve the developer experience by offering ready-to-use and well-explained code snippets.
docs/agents.md
Outdated
| from agents import Agent, Runner, function_tool, ModelSettings | ||
|
|
||
| @function_tool | ||
| def get_stock_price(ticker: str) -> str: |
There was a problem hiding this comment.
We would like to avoid this example in the document page. Can you simply reuse the fetch_purchases for these added examples? The main purpose is to share the ways to pass customization options, not to share a variety of examples.
There was a problem hiding this comment.
We would like to avoid this example in the document page. Can you simply reuse the
fetch_purchasesfor these added examples? The main purpose is to share the ways to pass customization options, not to share a variety of examples.
Hi, thanks for the review and the valuable feedback!
I've addressed your comments regarding the get_stock_price example and replaced it with get_weather to keep the documentation consistent and focused on demonstrating tool_use_behavior options rather than introducing new tools.
You're absolutely right about the main purpose being to share customization options. My intention with the detailed examples was to ensure that developers can easily understand and implement these advanced behaviors without confusion.
Personally, I've spent a considerable amount of time troubleshooting and experimenting with StopAtTools and ToolsToFinalOutputFunction because clear, runnable examples were not readily available. This led to significant time wastage for me. By providing these simplified yet comprehensive examples directly in the documentation, we can prevent other developers from facing similar challenges, saving them countless hours of debugging and guesswork.
I believe these changes make the documentation much more user-friendly and reduce the friction for anyone integrating with the Agent SDK.
Please let me know if any further adjustments are needed.
This update significantly enhances the "Tool Behavior Definitions" documentation, directly addressing the common challenges and wasted time developers previously experienced. Without clear examples and explicit guidance on import paths and usage patterns, implementing advanced agent tool behaviors was often a source of confusion and trial-and-error. **Key improvements in this update include:** - **Explicitly defining crucial import paths** for `StopAtTools` and `ToolsToFinalOutputFunction`, removing guesswork. - **Providing comprehensive and corrected code examples** for all `tool_choice` and `tool_use_behavior` configurations, including `"stop_on_first_tool"`, `StopAtTools`, and `ToolsToFinalOutputFunction`. These examples are now streamlined and use consistent, easy-to-understand tools like `get_weather`. - **Ensuring proper Markdown formatting** for code blocks and notes to enhance readability and accuracy. My personal experience, including significant time spent troubleshooting these very behaviors due to lack of clear examples, fueled this contribution. This update aims to drastically reduce ambiguity and improve the developer experience by offering ready-to-use and well-explained code snippets, saving countless hours for others.
This update significantly enhances the "Tool Behavior Definitions" documentation, directly addressing the common challenges and wasted time developers previously experienced. Without clear examples and explicit guidance on import paths and usage patterns, implementing advanced agent tool behaviors was often a source of confusion and trial-and-error. **Key improvements in this update include:** - **Explicitly defining crucial import paths** for `StopAtTools` and `ToolsToFinalOutputFunction`, removing guesswork. - **Providing comprehensive and corrected code examples** for all `tool_choice` and `tool_use_behavior` configurations, including `"stop_on_first_tool"`, `StopAtTools`, and `ToolsToFinalOutputFunction`. These examples are now streamlined and use consistent, easy-to-understand tools like `get_weather`. - **Ensuring proper Markdown formatting** for code blocks and notes to enhance readability and accuracy. My personal experience, including significant time spent troubleshooting these very behaviors due to lack of clear examples, fueled this contribution. This update aims to drastically reduce ambiguity and improve the developer experience by offering ready-to-use and well-explained code snippets, saving countless hours for others.
…es (openai#1286) Co-authored-by: Kazuhiro Sera <seratch@openai.com>
Enhances the "Tool Behavior Definitions" documentation to provide clearer
explanations and more robust examples for agent tool usage. Previously,
developers often faced challenges and ambiguity in understanding and implementing
these tool behaviors due to insufficient examples and unclear import paths.
Key improvements in this update include:
StopAtToolsandToolsToFinalOutputFunction.tool_choiceandtool_use_behaviorconfigurations, including"stop_on_first_tool",StopAtTools, and the usage ofToolsToFinalOutputFunction.readability and accuracy.
This update aims to significantly reduce ambiguity and improve the
developer experience by offering ready-to-use and well-explained code snippets.