Improve tool_use_behavior documentation: Clarify import paths for StopAtTools and ToolsToFinalOutputFunction

[MuhammadHamidRaza]

Problem Description

The current documentation for tool_use_behavior within the OpenAI Agent SDK mentions StopAtTools and ToolsToFinalOutputFunction as valid options for configuring tool use behavior. However, the documentation does not explicitly state the correct import paths for these classes.

This lack of explicit import instructions leads to ImportError issues for developers attempting to use these functionalities. For instance, a common first attempt is:

from agents import Agent, Runner, function_tool, StopAtTools # This fails

This results in an ImportError:

ImportError: cannot import name 'StopAtTools' from 'agents' (/usr/local/lib/python3.11/dist-packages/agents/__init__.py)

This wastes significant developer time in debugging and searching for the correct import location.

Expected Behavior

The documentation should clearly specify the full import path for StopAtTools and ToolsToFinalOutputFunction to ensure developers can easily and correctly implement these configurations without encountering ImportError.

Proposed Solution / Improvement

Please update the tool_use_behavior section of the documentation to explicitly include the import statements for StopAtTools and ToolsToFinalOutputFunction.

For example, the documentation should clarify that these classes need to be imported as follows:

from agents import Agent, Runner, function_tool
from agents.agent import StopAtTools, ToolsToFinalOutputFunction # Correct import paths

Here's an example demonstrating the correct usage:

from agents import Agent, Runner, function_tool
from agents.agent import StopAtTools, ToolsToFinalOutputFunction
from dataclasses import dataclass

@function_tool
def get_weather(location: str) -> str:
    return f"The weather in {{location}} is sunny"

@function_tool
def sum_two_numbers(a: int, b: int) -> int:
    return a + b

# Example using StopAtTools
agent_stop_at_weather = Agent(
    "Hamid",
    model=model, # Assuming 'model' is defined elsewhere (e.g., from an OpenAI client)
    tool_use_behavior=StopAtTools(stop_at_tool_names=["get_weather"]),
    tools=[get_weather, sum_two_numbers]
)

result_weather = Runner.run_sync(agent_stop_at_weather, "Tell me Karachi weather and also 2 + 2=")
print(f"Result with StopAtTools: {{result_weather.final_output}}")

# Example using 'stop_on_first_tool' string (currently documented and working)
agent_stop_on_first = Agent(
    "AnotherAgent",
    model=model, # Assuming 'model' is defined elsewhere
    tool_use_behavior="stop_on_first_tool",
    tools=[get_weather, sum_two_numbers]
)

result_first_tool = Runner.run_sync(agent_stop_on_first, "Tell me Karachi weather and also 2 + 2=")
print(f"Result with 'stop_on_first_tool': {{result_first_tool.final_output}}")

# (Optional: If demonstrating ToolsToFinalOutputFunction, include an example for it too)
# @dataclass
# class ToolsToFinalOutputResult:
#     # ... (define as per actual class structure if available)
#
# def custom_output_function(context, tool_results):
#     # Your custom logic here
#     return ToolsToFinalOutputResult(...)
#
# agent_custom_output = Agent(
#     "CustomOutputAgent",
#     model=model,
#     tool_use_behavior=ToolsToFinalOutputFunction(custom_output_function),
#     tools=[get_weather, sum_two_numbers]
# )
# result_custom = Runner.run_sync(agent_custom_output, "Perform some tasks and give final output.")
# print(f"Result with custom output function: {{result_custom.final_output}}")

By adding these clear import instructions, the documentation will become more user-friendly and reduce friction for developers integrating with the Agent SDK. We encourage the team to review other parts of the documentation for similar opportunities to clarify import statements, ensuring a consistently smooth developer experience across the entire SDK.

[seratch]

Thanks for taking the time to report this. I think both StopAtTools and ToolsToFinalOutputFunction should be added to agents package. Will work on it.

[MuhammadHamidRaza]

close it because it finished now