Step Budget

Cap the number of tool-use steps and detect graceful truncation

Cap how many tool-use steps an agent may take before wrapping up with its best final answer.

max_steps is the unified outer-loop step budget honoured identically by both tool-execution loops (OpenAI-native and LiteLLM). On the final permitted step the model is asked to wrap up, so you get a coherent answer instead of a hard cut.

Quick Start

1. Raise the budget with a scalar

   from praisonaiagents import Agent, ExecutionConfig
   
   agent = Agent(
       name="coder",
       instructions="You are a coding assistant.",
       execution=ExecutionConfig(max_steps=50),
   )
   
   result = agent.start("Refactor the auth module across all files")

2. Detect truncation with last_stop_reason

   from praisonaiagents import Agent, ExecutionConfig
   
   agent = Agent(
       name="coder",
       instructions="You are a coding assistant.",
       execution=ExecutionConfig(max_steps=50),
   )
   
   result = agent.start("Refactor the auth module across all files")
   
   if agent.last_stop_reason == "max_steps":
       # Truncated — the wrap-up answer summarises progress. Re-invoke to continue.
       print("Run truncated, continuing…")
       result = agent.start("Continue from where you left off.")
   elif agent.last_stop_reason == "completed":
       print("Done:", result)

How It Works

On the final permitted step both loops inject an internal user-role message so the model produces a coherent final answer:

“You are approaching the maximum number of tool-use steps for this task. Stop calling tools now and provide your best final answer, summarising the work completed so far and clearly noting anything left incomplete.”

The wrap-up message works on a local copy of the conversation, so it never leaks into the caller’s history.

A "max_steps" result is sticky and is never downgraded by a later provider block; a provider block/refusal recorded on a run that did not hit max_steps surfaces as content_filtered / refused / length_truncated instead of completed.

On the CLI

A step-limit-truncated run through praisonai run / praisonai-code run exits 2 and emits status: "truncated" under --output json, preserving the wrap-up summary in result.

praisonai run --output json "Refactor the auth module across all files"
# →
# {"status": "truncated", "result": "I started by …, but did not finish because the step limit was reached."}
# exit code: 2

Set a low ceiling in the YAML to demonstrate:

# agents.yaml
execution:
  max_steps: 5

Interactive (non-JSON) mode additionally prints a one-line stderr warning:

Run hit the step/iteration limit; the answer above is a summary of partial progress, not a completed task. Raise the budget with ExecutionConfig(max_steps=…) on the agent (or `execution: {max_steps: …}` in the YAML) and re-run.

praisonai code overrides this general default with a coding-sized budget and adds a --max-steps flag — see praisonai code defaults.

See praisonai run → Exit Codes for the full CLI contract.

Choosing a Value

praisonai code defaults

praisonai code overrides the general-purpose Agent default with a coding-sized budget of 200 steps, raising both ExecutionConfig.max_steps and ExecutionConfig.max_tool_calls_per_turn. This applies only to the coding CLI — the SDK Agent defaults (max_steps=20, max_tool_calls_per_turn=10) are unchanged.

Override at any level:

See praisonai code → Step budget for the full contract and the “why 200” rationale.

Configuration Options

Two helpers resolve the effective values:

How it relates to max_tool_calls_per_turn

max_steps bounds outer-loop iterations — one LLM round-trip each. max_tool_calls_per_turn caps how many tool calls the model can fire inside one response. They are independent on purpose: if they were coupled, a single parallel-tool response could exhaust the whole step budget (e.g. max_steps=5 truncating after one round of 5 parallel calls). Set them separately when you need both a long overall budget and a small per-turn burst.

Common Patterns

Pattern 1 — Raise the budget for long runs

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="coder",
    instructions="Refactor the auth module across all files",
    execution=ExecutionConfig(max_steps=50),
)
result = agent.start("Refactor the auth module across all files")

Pattern 2 — Detect and continue after truncation

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="coder",
    instructions="You are a coding assistant.",
    execution=ExecutionConfig(max_steps=50),
)

result = agent.start("Refactor the auth module across all files")

while agent.last_stop_reason == "max_steps":
    result = agent.start("Continue from where you left off.")

print(result)

Pattern 3 — Independent per-turn guardrail

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="researcher",
    execution=ExecutionConfig(
        max_steps=50,              # outer-loop budget
        max_tool_calls_per_turn=5, # parallel-tool guardrail per LLM response
    ),
)

Best Practices

Related