THE CORE AGENT LOOP

STEP LIMITS, TURN LIMITS, AND MAX ITERATIONS A step limit is a fixed cap on how many times the loop may go around. You will also see the same idea called a turn limit or max iterations. A turn usually means one round trip in which the model is called once, and an iteration is one pass through the loop, so in many harnesses the three terms describe nearly the same safeguard. Some harnesses separate them: a turn might count each model call, while a step counts each tool action. Always read a harness's documentation to see exactly what its numbers count. Why is a cap necessary? Models sometimes get stuck. They may repeat the same failed action again and again, or chase an endless trail of small subtasks. Each extra loop costs money, because model providers usually charge by the amount of text processed, and it costs time. Without a cap, one confused agent could run all night and produce a large bill. The cap works like the fuse in a home electrical panel. You hope it never trips, but when something goes wrong, it prevents a fire. Choosing the number is a judgment call. If the limit is too low, a perfectly healthy agent is cut off before it can finish, and users see unfinished work. If the limit is too high, a stuck agent burns a lot of money before anyone notices. A good practice is to measure how many steps successful runs usually take, then set the limit a comfortable distance above the typical high end, for example about twice the number that 95 out of 100 successful runs need. What should happen when the cap is reached? The best answer is a graceful stop, meaning the harness ends the run cleanly, tells the user what happened, and returns whatever partial progress exists. You will study graceful failure further in Chapter 12. Other smart safeguards go beyond a raw count. A repeat detector watches for the same action with the same inputs happening several times in a row and stops or redirects the agent. A no-progress detector notices when several steps pass without any new information. A time limit, sometimes called a wall-clock timeout, caps how long the run may take in real seconds, no matter how few steps it used.