# maxTurns Option

> The option that caps how many turns an agent run may take.

**Field:** Artificial Intelligence  
**Category:** Claude Agent SDK  
**Also known as:** maxTurns, max_turns, Agent SDK turn limit, Claude Agent SDK maxTurns

## Think of it like

It is like ten more turns on the swing, then you stop.

## Definition

maxTurns is the Agent SDK option that caps how many turns a run may take. In Python it is max_turns. A turn is one pass where Claude replies and its tool calls run, and the final text-only reply counts too. When the cap is hit, the run ends with an error_max_turns result. Left unset, or set to 0, there is no limit.

## Example

Leo's agent sometimes loops on a hard bug. He sets maxTurns to 30, so it stops and reports instead of running on.

## Why it matters

An open-ended task can run for a long time, and a cap keeps it in check.

## Common mistake

Setting it too tight. Count every tool turn plus one for the final answer.

## Three principles

- **Caps the turns.** Per run.
- **Final reply counts.** Add one.
- **0 means no limit.** Same as unset.

## Related terms

- [maxBudgetUsd Option](https://learn.benibix.com/term/ai/max-budget-usd-option)
- [Result Subtype](https://learn.benibix.com/term/ai/result-subtype)
- [--max-turns Flag](https://learn.benibix.com/term/ai/max-turns-flag)
- [Agent Loop](https://learn.benibix.com/term/ai/agent-loop)
- [Agent Stop Condition](https://learn.benibix.com/term/ai/agent-stop-condition)

---

Source: https://learn.benibix.com/term/ai/max-turns-option
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-20
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
