Heuristic:Openai Openai agents python Tool Choice Reset Prevents Loops
| Knowledge Sources | |
|---|---|
| Domains | Agent_Execution, Optimization |
| Last Updated | 2026-02-11 14:00 GMT |
Overview
Automatic tool_choice reset after first tool use prevents infinite tool-call loops in agent execution.
Description
When an agent has `tool_choice` set to force a specific tool (e.g., `tool_choice="required"`), the model will always attempt to call a tool on every turn. Without intervention, this creates an infinite loop where the agent never produces a final text response. The SDK solves this by automatically resetting `tool_choice` to `None` after the agent has used any tool at least once, allowing the model to choose between tool calls and text output on subsequent turns.
Usage
This heuristic is active by default (`reset_tool_choice=True`). Be aware of it when:
- You set `tool_choice` on an agent or model settings to force tool usage
- You notice agents producing only one tool call then immediately generating text
- You want to force continuous tool usage (set `reset_tool_choice=False` on the agent)
The Insight (Rule of Thumb)
- Action: The SDK automatically resets `tool_choice` to `None` after the agent uses any tool in the current run.
- Value: `Agent(reset_tool_choice=True)` is the default.
- Trade-off: When enabled, the agent can only be "forced" to use a tool on the first model call. After that, the model chooses freely. If you need repeated forced tool calls, set `reset_tool_choice=False` and manage loop termination yourself.
- Tracking: The `AgentToolUseTracker` uses object identity (`is` comparison) to track which agent instances have used tools, supporting multiple agents with the same name.
Reasoning
LLMs with `tool_choice="required"` will always generate a tool call, never a final text response. In agentic loops, this means the agent would call tools indefinitely until hitting `max_turns`. By resetting `tool_choice` to `None` after the first tool use, the model can organically decide to stop calling tools and produce a final answer. This is the expected behavior in 95%+ of use cases.
Code evidence from `agent.py:314-316`:
reset_tool_choice: bool = True
"""Whether to reset the tool choice to the default value after a tool has been called. Defaults
to True. This ensures that the agent doesn't enter an infinite loop of tool usage."""
Reset logic from `run_internal/tool_execution.py:129-137`:
def maybe_reset_tool_choice(
agent: Agent[Any],
tool_use_tracker: AgentToolUseTracker,
model_settings: ModelSettings,
) -> ModelSettings:
"""Reset tool_choice if the agent was forced to pick a tool previously and should be reset."""
if agent.reset_tool_choice is True and tool_use_tracker.has_used_tools(agent):
return dataclasses.replace(model_settings, tool_choice=None)
return model_settings