max_iterations Guide

Control Your Agent's Power

max_iterations determines how many tool calls your agent can make. Master this to build efficient, reliable agents.

Default: 10 iterationsFully customizableSmart patterns included

What Are Iterations?

Think of iterations as "attempts" - how many times your agent can use tools to complete a task.

1# Your agent tries to complete the task
2# Iteration 1: "I need to search for info" → calls search tool
3# Iteration 2: "Now I'll calculate something" → calls calculate tool
4# Iteration 3: "Let me save the result" → calls save tool
5# Done! Task completed in 3 iterations

Quick Start - Super Simple

The Basics (90% of cases)

1from connectonion import Agent
2
3# Default: 10 iterations (works for most tasks!)
4agent = Agent("my_bot", tools=[search, calculate])
5
6# That's it! Just use it:
7result = agent.input("What's 2+2?")  # Uses 1 iteration
8result = agent.input("Search for Python tutorials")  # Uses 1-2 iterations

When You Need More Power

1# Complex tasks need more iterations
2research_agent = Agent(
3    "researcher",
4    tools=[search, analyze, summarize],
5    max_iterations=25  # I need more attempts for complex research
6)

Quick Override for One Task

1# Normal agent
2agent = Agent("helper", tools=[...])  # Default 10
3
4# But this ONE task is complex:
5result = agent.input(
6    "Do something really complex",
7    max_iterations=30  # Just for this task!
8)

Real Examples

Simple Calculator Bot

Calculator needs very few iterations - math is straightforward.

1def calculate(expression: str) -> float:
2    return eval(expression)  # Simple math
3
4# Calculator rarely needs many attempts
5calc_bot = Agent(
6    "calculator",
7    tools=[calculate],
8    max_iterations=3  # Math is simple, 3 attempts is plenty
9)
10
11# This works fine with just 1 iteration:
12result = calc_bot.input("What's 15 * 8?")
13print(result)  # "The answer is 120"

What Happens When You Hit The Limit?

"Task incomplete: Maximum iterations (10) reached."

Solution: Increase max_iterations for the agent or this specific task.

Cool Tricks & Advanced Patterns

Trick 1: Auto-Retry with Higher Limit

Automatically increases iterations if task fails.

1def smart_input(agent, prompt, max_retries=3):
2    """Automatically increases iterations if task fails."""
3    limits = [10, 25, 50]  # Try these limits in order
4    
5    for limit in limits:
6        result = agent.input(prompt, max_iterations=limit)
7        if "Maximum iterations" not in result:
8            return result  # Success!
9    
10    return "Task too complex even with 50 iterations"
11
12# Use it:
13agent = Agent("smart", tools=[...])
14result = smart_input(agent, "Complex task")  # Auto-adjusts!

Trick 2: Self-Adjusting Agent

Agent that learns optimal iterations from history.

1class SelfAdjustingAgent:
2    """Agent that learns optimal iterations from history."""
3    
4    def __init__(self, name, tools):
5        self.agent = Agent(name, tools, max_iterations=10)
6        self.task_history = {}
7    
8    def input(self, prompt):
9        # Start with learned limit or default
10        task_type = self._classify_task(prompt)
11        max_iter = self.task_history.get(task_type, 10)
12        
13        # Try with current limit
14        result = self.agent.input(prompt, max_iterations=max_iter)
15        
16        # If failed, increase and retry
17        while "Maximum iterations" in result and max_iter < 50:
18            max_iter += 10
19            print(f"Increasing to {max_iter} iterations...")
20            result = self.agent.input(prompt, max_iterations=max_iter)
21        
22        # Remember what worked
23        if "Maximum iterations" not in result:
24            self.task_history[task_type] = max_iter
25            print(f"Learned: {task_type} tasks need {max_iter} iterations")
26        
27        return result

Quick Reference

What You're Doing	Iterations	Example
Simple Q&A	3-5	"What's the weather?"
Calculations	5-10	"Calculate my taxes"
Multi-step tasks	10-20	"Search and summarize"
Complex workflows	20-40	"Analyze all data and generate report"
Research projects	30-50	"Research topic from multiple sources"

⏱️The One-Minute Summary

1.Most agents are fine with default max_iterations=10
2.Simple bots can use 5, complex ones need 20-30
3.Override per-task when needed: agent.input(prompt, max_iterations=X)
4.If you see "Maximum iterations reached", just increase the limit
5.Advanced: Build smart agents that adjust limits automatically

That's it! You now know everything about iteration control. Start simple, adjust when needed!

PreviousTools NextLLM Function