# What Does the max_steps Parameter in Needle run() Control?

> Discover what the max_steps parameter in Needle run() controls. Learn how to set the maximum reasoning iterations for your agent to prevent infinite loops.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: api-reference
- Published: 2026-08-17

---

**The `max_steps` parameter in `Needle.run()` sets the maximum number of reasoning iterations (tool-calling cycles) the agent can perform before terminating, with a default limit of 8 steps.**

The `max_steps` parameter is a critical safeguard in the Needle agent framework that controls how many times the model can invoke tools during a single query execution. Located in the core implementation at [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), this parameter prevents runaway execution while giving developers fine-grained control over multi-step reasoning workflows. Understanding how `max_steps` functions is essential for optimizing both the reliability and cost-effectiveness of your AI agent applications.

## How max_steps Controls Tool-Calling Iterations

When you invoke `Needle.run()`, the method enters a controlled loop defined by `for _ in range(max_steps):` (lines 25-45 in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py)). During each iteration, the agent sends the current prompt to the LLM via `self.complete()` and checks the response for `function_calls` of type `"call"`.

If the model requests tool execution, the engine invokes the specified functions, aggregates the results, and feeds them back into the context for the next iteration. This cycle continues until one of two conditions is met:

- The model returns a response without a `"call"` type, indicating completion
- The loop reaches the `max_steps` limit (default: 8)

The loop includes an early exit mechanism (line 30) that breaks immediately when the model stops requesting tool calls, ensuring efficient termination before hitting the cap if the task completes early.

## Why Configuring max_steps Matters

Setting an appropriate `max_steps` value directly impacts three key operational aspects:

- **Preventing infinite loops:** Without an upper bound, a model caught in a circular reasoning pattern could invoke tools indefinitely, consuming excessive resources and never returning a final answer.
- **Managing latency and cost:** Each step requires a full LLM inference pass. Limiting steps reduces API calls and response time, which is crucial when using large, expensive models.
- **Tuning workflow complexity:** Complex multi-tool workflows (e.g., research agents requiring sequential searches) need higher limits, while simple Q&A tasks benefit from stricter constraints to prevent over-processing.

## Practical Examples of max_steps Usage

### Basic Usage with Default Limit

```python
from needle import Needle

agent = Needle()
response = agent.run("What is the weather in Paris and can you book a hotel?")
print(response["results"])  # Aggregated tool call results

print(response["type"])     # Final response type (e.g., "text")

```

### Restricting to Single-Step Execution

```python
agent = Needle()

# Force termination after one tool call regardless of completion status

response = agent.run(
    "Find the current price of Bitcoin.",
    max_steps=1,  # Maximum one tool-calling cycle

)
print(response["results"])

```

### Expanding Limits for Complex Workflows

```python
agent = Needle()

# Allow up to 15 iterations for multi-stage planning tasks

response = agent.run(
    "Plan a 3-day itinerary in Tokyo, including flights, hotels, and activities.",
    max_steps=15,
)
print(response["results"])

```

### Combining with Generation Limits

```python
agent = Needle()
response = agent.run(
    "Summarize the latest research on quantum computing and cite three papers.",
    max_steps=5,
    max_new_tokens=512,  # Controls tokens per LLM response

)
print(response["text"])

```

## Implementation Details in needle/__init__.py

The `max_steps` logic resides in the `Needle.run()` method within [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py). The implementation uses a straightforward counting mechanism:

```python

# Conceptual representation of the loop structure

for _ in range(max_steps):
    response = self.complete(prompt)
    if not has_tool_calls(response):
        break  # Early exit at line 30

    # Execute tools and update prompt...

```

After the loop terminates—whether through completion or step exhaustion—the method returns a dictionary containing the final LLM response and a `results` field aggregating all tool outputs collected during the execution chain.

## Summary

- The `max_steps` parameter caps the number of tool-calling cycles in `Needle.run()`, defaulting to 8 iterations
- It prevents infinite loops by forcing termination after the specified number of LLM interactions
- Each step represents one full pass: LLM inference → tool execution → result aggregation
- The loop exits early if the model stops requesting tools before reaching the limit
- Adjust `max_steps` based on workflow complexity to balance capability against latency and cost

## Frequently Asked Questions

### What is the default value of max_steps in Needle?

The default value is **8**, meaning the agent can perform up to eight tool-calling iterations before automatically terminating. This default provides a reasonable balance for most single-query tasks while preventing excessive API usage.

### Does max_steps limit the total number of LLM calls?

Yes, `max_steps` directly limits how many times `self.complete()` is invoked during a single `run()` execution. Since each iteration requires one LLM inference to check for tool calls, the parameter effectively caps the maximum number of model calls per query.

### How does max_steps prevent infinite loops?

Without `max_steps`, a model might enter a recursive pattern where it repeatedly calls the same tool or cycles between tools without reaching a conclusion. The parameter acts as a hard ceiling—once the iteration count reaches the specified limit (regardless of completion status), the loop terminates and returns the current state.

### Can max_steps be set to zero?

Setting `max_steps=0` would prevent the loop from executing entirely, causing `run()` to return immediately without processing the query. While technically possible, this would render the agent non-functional for any task requiring tool use, making values of 1 or higher practical for actual deployments.