Enhance Tool Behavior Documentation for Developer Clarity With Examples

docs/agents.md

@@ -143,8 +143,107 @@ Supplying a list of tools doesn't always mean the LLM will use a tool. You can f
 3. `none`, which requires the LLM to _not_ use a tool.
 4. Setting a specific string e.g. `my_tool`, which requires the LLM to use that specific tool.
 
+```python
+from agents import Agent, Runner, function_tool, ModelSettings
+
+@function_tool
+def get_stock_price(ticker: str) -> str:
+    """Fetches the stock price for a given ticker symbol."""
+    prices = {"AAPL": "$150.00", "GOOGL": "$2750.00"}
+    return prices.get(ticker, "Stock not found")
+
+agent = Agent(
+    name="Stock Price Agent",
+    instructions="Retrieve the stock price if relevant, otherwise respond directly.",
+    tools=[get_stock_price],
+    model_settings=ModelSettings(tool_choice="get_stock_price") 
+)
+
+```
+
+## Tool Use Behavior
+
+The `tool_use_behavior` parameter in the `Agent` configuration controls how tool outputs are handled:
+- `"run_llm_again"`: The default. Tools are run, and the LLM processes the results to produce a final response.
+- `"stop_on_first_tool"`: The output of the first tool call is used as the final response, without further LLM processing.
+
+```python
+from agents import Agent, Runner, function_tool, ModelSettings
+
+@function_tool
+def get_stock_price(ticker: str) -> str:
+    """Fetches the stock price for a given ticker symbol."""
+    prices = {"AAPL": "$150.00", "GOOGL": "$2750.00"}
+    return prices.get(ticker, "Stock not found")
+
+# Create the agent
+agent = Agent(
+    name="Stock Price Agent",
+    instructions="Retrieve the stock price.",
+    tools=[get_stock_price],
+    tool_use_behavior="stop_on_first_tool"
+)
+```
+
+- `StopAtTools(stop_at_tool_names=[...])`: Stops if any specified tool is called, using its output as the final response.
+```python
+from agents import Agent, Runner, function_tool
+from agents.agent import StopAtTools
+
+@function_tool
+def get_stock_price(ticker: str) -> str:
+    """Fetches the stock price for a given ticker symbol."""
+    prices = {"AAPL": "$150.00", "GOOGL": "$2750.00"}
+    return prices.get(ticker, "Stock not found")
+
+agent = Agent(
+    name="Stop At Stock Agent",
+    instructions="Get stock price and stop.",
+    tools=[get_stock_price],
+    tool_use_behavior=StopAtTools(stop_at_tool_names=["get_stock_price"])
+)
+```
+- `ToolsToFinalOutputFunction`: A custom function that processes tool results and decides whether to stop or continue with the LLM.
+
+```python
+
+from agents import Agent, Runner, function_tool, FunctionToolResult, RunContextWrapper
+from agents.agent import ToolsToFinalOutputResult
+from typing import List, Any
+
+@function_tool
+def get_product_price(product_id: str) -> str:
+    """Fetches the price for a given product ID."""
+    prices = {"P101": "$25.00", "P102": "$49.99"}
+    return prices.get(product_id, "Product not found")
+
+def custom_tool_handler(
+    context: RunContextWrapper[Any],
+    tool_results: List[FunctionToolResult]
+) -> ToolsToFinalOutputResult:
+    """Processes tool results to decide final output."""
+    for result in tool_results:
+        if result.output and "$25.00" in result.output:
+            return ToolsToFinalOutputResult(
+                is_final_output=True,
+                final_output=f"Final result: {result.output}"
+            )
+    return ToolsToFinalOutputResult(
+        is_final_output=False,
+        final_output=None
+    )
+
+# Create the agent
+agent = Agent(
+    name="Product Price Agent",
+    instructions="Retrieve product prices and format them.",
+    tools=[get_product_price],
+    tool_use_behavior=custom_tool_handler
+)
+
+```
+
 !!! note
 
     To prevent infinite loops, the framework automatically resets `tool_choice` to "auto" after a tool call. This behavior is configurable via [`agent.reset_tool_choice`][agents.agent.Agent.reset_tool_choice]. The infinite loop is because tool results are sent to the LLM, which then generates another tool call because of `tool_choice`, ad infinitum.
 
-    If you want the Agent to completely stop after a tool call (rather than continuing with auto mode), you can set [`Agent.tool_use_behavior="stop_on_first_tool"`] which will directly use the tool output as the final response without further LLM processing.