Skip to content
BENIBIX Learn

maxTurns Option

Also known as maxTurns, max_turns, Agent SDK turn limit, Claude Agent SDK maxTurns

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

Think of it like

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

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.

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.

Common mistake

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

Key takeaways

  1. 1
    Caps the turns. Per run.
  2. 2
    Final reply counts. Add one.
  3. 3
    0 means no limit. Same as unset.