-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Description
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.