Heuristic:Openai Openai agents python Default Max Turns Safety Limit
| Knowledge Sources | |
|---|---|
| Domains | Agent_Execution, Safety |
| Last Updated | 2026-02-11 14:00 GMT |
Overview
Default maximum of 10 turns per agent run prevents runaway execution loops and excessive API costs.
Description
The SDK enforces a hard limit on the number of agent "turns" (model call + tool execution cycles) per run. The default is 10. When exceeded, a `MaxTurnsExceeded` exception is raised. This acts as a safety net against infinite loops caused by misconfigured agents, circular handoffs, or models that repeatedly call tools without converging on a final answer.
Usage
Be aware of this limit when:
- Building complex multi-step agents that may need more than 10 tool calls
- Using agent handoffs where each handoff counts as a new turn for the receiving agent
- Debugging `MaxTurnsExceeded` errors that indicate the agent didn't converge
The Insight (Rule of Thumb)
- Action: Override `max_turns` in `RunOptions` when your agent needs more than 10 cycles. Set it to a specific number, not infinity.
- Value: `DEFAULT_MAX_TURNS = 10`
- Trade-off: Lower values protect against runaway costs but may cut off complex workflows. Higher values allow more complex tasks but risk infinite loops and higher API bills.
Reasoning
Agentic loops are inherently open-ended: the model decides when to stop. Without a hard cap, a buggy or confused agent could call tools indefinitely, consuming API credits. The default of 10 turns is a pragmatic middle ground: enough for most single-agent tasks (typically 1-5 turns) while catching infinite loops early. The `MaxTurnsExceeded` exception includes a `run_result` field so callers can inspect partial progress.
Code evidence from `run_config.py:27`:
DEFAULT_MAX_TURNS = 10
The max_turns parameter in `RunOptions`:
class RunOptions(TypedDict, Generic[TContext]):
max_turns: NotRequired[int]
"""The maximum number of turns to run for."""