Fix and Document parallel_tool_calls Attribute in ModelSettings (openai#763)

Rehan-Ul-Haq · web-flow · commit 816b7702bc78 · 2025-06-27T10:37:57.000-04:00
Closes openai#762 **Description** This PR updates the docstring for the `parallel_tool_calls` attribute in the `ModelSettings` dataclass to accurately reflect its default behavior.. The previous docstring incorrectly stated that the default of `False`, while the actual behavior is dependent on the underlying model provider's default. As noted in OpenAI's (here refers as model provider) [Function Calling](https://platform.openai.com/docs/guides/function-calling?api-mode=responses#parallel-function-calling) documentation, "The model may choose to call multiple functions in a single turn. You can prevent this by setting parallel_tool_calls to false, which ensures exactly zero or one tool is called." Therefore, when the `parallel_tool_calls` attribute in the `ModelSettings` dataclass is set to `None` (i.e., `parallel_tool_calls: bool | None = None`), and this value is passed directly to the API without modification, it defers to the model provider's default behavior for parallel tool calls. This is typically `True` for most current providers, but it's important to acknowledge that this isn't a fixed default within our codebase. The new docstring is formatted for automatic documentation generation and provides clear, accurate information for users and developers. **Key changes:** * **Clarified the default behavior of `parallel_tool_calls`:** Instead of stating a fixed default, the docstring now accurately reflects that the behavior defaults to whatever the model provider does when the attribute is `None`. * Improved the docstring format for compatibility with documentation tools. * Clarified the purpose and usage of the `parallel_tool_calls` attribute. **Testing:** * Explicitly set `parallel_tool_calls=False` in both the `run_config` of the `Runner.run` method and in the agent’s `model_settings` attribute. * Example for `Runner.run`: ```python Runner.run(agent, input, run_config=RunConfig(model_settings=ModelSettings(parallel_tool_calls=False))) ``` * Example for agent initialization: ```python agent = Agent(..., model_settings=ModelSettings(parallel_tool_calls=False)) ``` * Verified that when `parallel_tool_calls=False`, tools are called sequentially. * Confirmed that by default (without setting the attribute), tools are called in parallel (Tested with openai models). * Checked that the updated docstring renders correctly in the generated documentation. * Ensured the default value in code matches the documentation. **Why this is important:** * Prevents confusion for users and developers regarding the default behavior of `parallel_tool_calls`. * Ensures that generated documentation is accurate and up-to-date. * Improves overall code quality and maintainability.
diff --git a/src/agents/model_settings.py b/src/agents/model_settings.py
@@ -37,8 +37,13 @@ class ModelSettings:
     """The tool choice to use when calling the model."""
 
     parallel_tool_calls: bool | None = None
-    """Whether to use parallel tool calls when calling the model.
-    Defaults to False if not provided."""
+    """Controls whether the model can make multiple parallel tool calls in a single turn.
+    If not provided (i.e., set to None), this behavior defers to the underlying
+    model provider's default. For most current providers (e.g., OpenAI), this typically
+    means parallel tool calls are enabled (True).
+    Set to True to explicitly enable parallel tool calls, or False to restrict the
+    model to at most one tool call per turn.
+    """
 
     truncation: Literal["auto", "disabled"] | None = None
     """The truncation strategy to use when calling the model."""
